geo_within_distance

Determines geospatial objects in proximity to a point.

boolean geo_within_distance(any*, any*,double)

The first and the second parameters any* can be any geometric object.

The function determines if the first geometry is within a distance of N meters from the second geometry.

If any of the two parameters does not return a single valid geometry object, and if it can be detected at compile time then the function raises an error.

The runtime behavior is as follows:

• Returns false if any parameter returns 0 or more than 1 item.
• Returns NULL if any of the first two parameters returns NULL.
• Returns false if any of the first two parameters returns an item that is not a valid geometry object.

Finally, if both the parameters return a single geometry object each, it returns true if the first geometry is within a distance of N meters from the second geometry, where N is the number returned by the third parameter; otherwise false. The distance between 2 geometries is defined as the minimum among the distances of any pair of points where the first point belongs to the first geometry and the second point to the second geometry. If N is a negative number, it is set to 0.

Example: Is a city hall there in the next 5 km? How far is it?

SELECT t.poi.address.street AS city_hall_address,
geo_distance(
    t.poi.location,
    { 
        "type" : "point",
        "coordinates" : [-120.653828125,38.85682013474361]
    }

) AS distance_in_meters
FROM PointsOfInterest t
WHERE t.poi.kind = "city hall" AND
geo_within_distance( 
    t.poi.location,
    { 
        "type" : "point",
        "coordinates" : [-120.653828125,38.85682013474361]
    },
    5000
);

Explanation:

• You query the PointsOfInterest table to filter the rows for city hall.
• You use the geo_within_distance function to filter city hall within 5 km (5000m) of the given location.
• You also fetch the actual distance between your location and the city hall using the geo_distance function.

Result:

{"city_hall_address":"70 North 1st street","distance_in_meters":1736.0144040331768}

The city hall is 1736 m(1.73 km) from the current location.