# Geographical

> Source: https://docs.recombee.com/reql/functions/geographical

> For the complete documentation index, see [llms.txt](/llms.txt).

# Geographical

| Name                                         | Description                                                                                                      | Example                                                                                              |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [earth\_distance](#reql-func-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](#reql-func-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](#reql-func-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](#reql-func-geo-containment).

## 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](/reql/value-types-and-operators#arrays) 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](#reql-func-geo-point) with geographical coordinates, on which queries of testing for [geographical containment](#reql-func-geo-containment) may be applied.

### Definition

```
geo_polygon(polygon points, strict)
```

| Argument       | Type                                    | Meaning                                                                                                     |
| -------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| polygon points | array of [points](#reql-func-geo-point) | 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](#reql-func-geo-point)
* 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](#reql-func-geo-point) with geographical coordinates and a radius in km, on which queries of testing for [geographical containment](#reql-func-geo-containment) may be applied.

### Definition

```
geo_radius(center point, radius)
```

| Argument     | Type                          | Meaning                                      |
| ------------ | ----------------------------- | -------------------------------------------- |
| center point | [point](#reql-func-geo-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](#reql-func-geo-point). The result of the operator is truthy if the [point](#reql-func-geo-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)
```