Geographical

Name	Description	Example
earth_distance	Returns the orthodromic distance between two points (given as their latitude and longitude in degrees) in meters	`earth_distance(50.075538,14.437800,52.520007,13.404954) < 282000`
geo_polygon	Creates a spherical polygon represented by points with geographical coordinates	`geo_polygon([[40.800, -73.957], [40.767, -73.981], [40.764, -73.972], [40.796, -73.949]])`
geo_radius	Creates a spherical cap represented by a center with geographical coordinates and a radius in km	`geo_radius([40.689167, -74.044444], 10)`

Geographical functions geo_polygon and geo_radius construct geographical values, on which queries for testing geographic containment may be applied. For a detailed description and examples of usage, see the Geographical Containment section.

Earth Distance

Returns the orthodromic distance in meters between two points specified by their latitude and longitude in degrees.

Definition

earth_distance(lat1,lon1,lat2,lon2)

Argument	Type	Meaning
lat1	`number`	Latitude of the first point in degrees
lon1	`number`	Longitude of the first point in degrees
lat2	`number`	Latitude of the second point in degrees
lon2	`number`	Longitude of the second point in degrees

Example

All the following expressions result in true:

earth_distance(10,10,10,10) == 0

// Distance between Prague (50.075538,14.437800) and Berlin (52.520007,13.404954)
281000 < earth_distance(50.075538,14.437800,52.520007,13.404954) < 282000

Geographical Point

To specify a point with geographical coordinates, use an array of length two, which contains number values latitude and longitude as its elements, respectively:

// Geographical coordinates of One World Trade Center
[40.713056, -74.013333]

Geographical Polygon

Creates a spherical polygon represented by points with geographical coordinates, on which queries of testing for geographical containment may be applied.

Definition

geo_polygon(polygon points, strict)

Argument	Type	Meaning
polygon points	`array` of points	The boundary of the polygon
strict	`boolean`	Optional. Boolean specifying if any non-valid polygon results in an error. Default if not provided: `false`

A polygon is specified as an array of geographical coordinates of at least 3 points
The points of a polygon can be specified in both CW and CCW orders
The interior of a polygon is such that the polygon encloses at most half of the sphere (from two possible interpretations of a polygon, the one with the smaller area is considered). The interior does not include the boundary, except for the points

To avoid ambiguity of the requests, the following requirements should be kept:

No two points of a polygon may share coordinates (the first and the last point are presumed to be connected automatically),
Edges of a polygon may not cross anywhere but in the points

By default, if any of the requirements above are not fulfilled, the geo containment query will be handled on a best-effort basis.

Should you want to enable strict checking, set the boolean parameter strict to true. In that case, any failure to comply with the requirements will result in an error.

Example

// A geo_polygon roughly encompassing NYC's Manhattan
geo_polygon([[40.878273, -73.925268], [40.711673, -74.027338], [40.698674, -73.984877], [40.761036, -73.957467], [40.794154, -73.913269], [40.834948, -73.934384], [40.872342, -73.908634]])

// A geo_polygon roughly encompassing NYC's Manhattan with strict checking
geo_polygon([[40.878273, -73.925268], [40.711673, -74.027338], [40.698674, -73.984877], [40.761036, -73.957467], [40.794154, -73.913269], [40.834948, -73.934384], [40.872342, -73.908634]], true)

Geographical Radius

Creates a spherical cap represented by a center point with geographical coordinates and a radius in km, on which queries of testing for geographical containment may be applied.

Definition

geo_radius(center point, radius)

Argument	Type	Meaning
center point	point	Coordinates of the center of the `geo_radius`
radius	`number`	Length of the `geo_radius` radius in km

Everything that is within the orthodromic distance of a given radius to the center point is contained within the geo_radius (inclusively).

Nothing is contained within a geo_radius with a negative radius, and everything is contained within a geo_radius with a radius larger than half of the Earth Equator’s length.

Example

// A geo_radius of 10km around Statue of Liberty
geo_radius([40.689167, -74.044444], 10)

Geographical Containment

Geographical values geo_polygon and geo_radius support the in operator for checking containtment of a geographical point. The result of the operator is truthy if the point is contained within the given geographical value. The syntax of such a query is: point in geographical value.

Examples

All the following expressions result in true:

// One World Trade Center is contained within a geo_polygon roughly encompassing NYC's Manhattan
[40.713056, -74.013333] in geo_polygon([[40.878273, -73.925268], [40.711673, -74.027338], [40.698674, -73.984877], [40.761036, -73.957467], [40.794154, -73.913269], [40.834948, -73.934384], [40.872342, -73.908634]])

// One World Trade Center is contained within a geo_radius of 10km around Statue of Liberty
[40.713056, -74.013333] in geo_radius([40.689167, -74.044444], 10)

docs.recombee.com