2020-04-03 13:23:32 +00:00
---
toc_priority: 62
toc_title: Working with geographical coordinates
---
2020-03-20 10:10:48 +00:00
# Functions for Working with Geographical Coordinates {#functions-for-working-with-geographical-coordinates}
2018-09-04 11:18:59 +00:00
2020-03-20 10:10:48 +00:00
## greatCircleDistance {#greatcircledistance}
2018-09-04 11:18:59 +00:00
2020-03-20 10:10:48 +00:00
Calculate the distance between two points on the Earth’ s surface using [the great-circle formula ](https://en.wikipedia.org/wiki/Great-circle_distance ).
2018-09-04 11:18:59 +00:00
2020-03-20 10:10:48 +00:00
``` sql
2018-09-04 11:18:59 +00:00
greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```
**Input parameters**
2020-03-21 04:11:51 +00:00
- `lon1Deg` — Longitude of the first point in degrees. Range: `[-180°, 180°]` .
- `lat1Deg` — Latitude of the first point in degrees. Range: `[-90°, 90°]` .
- `lon2Deg` — Longitude of the second point in degrees. Range: `[-180°, 180°]` .
- `lat2Deg` — Latitude of the second point in degrees. Range: `[-90°, 90°]` .
2018-09-04 11:18:59 +00:00
Positive values correspond to North latitude and East longitude, and negative values correspond to South latitude and West longitude.
**Returned value**
2020-03-20 10:10:48 +00:00
The distance between two points on the Earth’ s surface, in meters.
2018-09-04 11:18:59 +00:00
Generates an exception when the input parameter values fall outside of the range.
**Example**
2020-03-20 10:10:48 +00:00
``` sql
2018-09-04 11:18:59 +00:00
SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673)
```
2020-03-20 10:10:48 +00:00
``` text
2018-09-04 11:18:59 +00:00
┌─greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673)─┐
│ 14132374.194975413 │
└───────────────────────────────────────────────────────────────────┘
```
2020-03-20 10:10:48 +00:00
## pointInEllipses {#pointinellipses}
2018-09-04 11:18:59 +00:00
Checks whether the point belongs to at least one of the ellipses.
2019-09-09 17:51:58 +00:00
Coordinates are geometric in the Cartesian coordinate system.
2018-09-04 11:18:59 +00:00
2020-03-20 10:10:48 +00:00
``` sql
2018-09-04 11:18:59 +00:00
pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ)
```
**Input parameters**
2020-03-21 04:11:51 +00:00
- `x, y` — Coordinates of a point on the plane.
- `xᵢ, yᵢ` — Coordinates of the center of the `i` -th ellipsis.
- `aᵢ, bᵢ` — Axes of the `i` -th ellipsis in units of x, y coordinates.
2018-09-04 11:18:59 +00:00
The input parameters must be `2+4⋅n` , where `n` is the number of ellipses.
**Returned values**
`1` if the point is inside at least one of the ellipses; `0` if it is not.
2018-09-05 08:41:04 +00:00
**Example**
2018-09-04 11:18:59 +00:00
2020-03-20 10:10:48 +00:00
``` sql
2019-09-09 17:51:58 +00:00
SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)
2018-09-04 11:18:59 +00:00
```
2020-03-20 10:10:48 +00:00
``` text
2019-09-09 17:51:58 +00:00
┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│ 1 │
└─────────────────────────────────────────────────┘
2018-09-04 11:18:59 +00:00
```
2020-03-20 10:10:48 +00:00
## pointInPolygon {#pointinpolygon}
2018-09-05 08:41:04 +00:00
Checks whether the point belongs to the polygon on the plane.
2020-03-20 10:10:48 +00:00
``` sql
2018-09-05 08:41:04 +00:00
pointInPolygon((x, y), [(a, b), (c, d) ...], ...)
```
**Input values**
2020-04-30 18:19:18 +00:00
- `(x, y)` — Coordinates of a point on the plane. Data type — [Tuple ](../../sql-reference/data-types/tuple.md ) — A tuple of two numbers.
- `[(a, b), (c, d) ...]` — Polygon vertices. Data type — [Array ](../../sql-reference/data-types/array.md ). Each vertex is represented by a pair of coordinates `(a, b)` . Vertices should be specified in a clockwise or counterclockwise order. The minimum number of vertices is 3. The polygon must be constant.
2020-03-21 04:11:51 +00:00
- The function also supports polygons with holes (cut out sections). In this case, add polygons that define the cut out sections using additional arguments of the function. The function does not support non-simply-connected polygons.
2018-09-05 08:41:04 +00:00
**Returned values**
`1` if the point is inside the polygon, `0` if it is not.
If the point is on the polygon boundary, the function may return either 0 or 1.
**Example**
2020-03-20 10:10:48 +00:00
``` sql
2018-09-05 08:41:04 +00:00
SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res
```
2020-03-20 10:10:48 +00:00
``` text
2018-09-05 08:41:04 +00:00
┌─res─┐
│ 1 │
└─────┘
```
2020-03-20 10:10:48 +00:00
## geohashEncode {#geohashencode}
2019-04-09 19:19:30 +00:00
Encodes latitude and longitude as a geohash-string, please see (http://geohash.org/, https://en.wikipedia.org/wiki/Geohash).
2020-03-20 10:10:48 +00:00
``` sql
2019-04-09 19:19:30 +00:00
geohashEncode(longitude, latitude, [precision])
```
**Input values**
2020-03-21 04:11:51 +00:00
- longitude - longitude part of the coordinate you want to encode. Floating in range`[-180°, 180°]`
- latitude - latitude part of the coordinate you want to encode. Floating in range `[-90°, 90°]`
- precision - Optional, length of the resulting encoded string, defaults to `12` . Integer in range `[1, 12]` . Any value less than `1` or greater than `12` is silently converted to `12` .
2019-04-09 19:19:30 +00:00
**Returned values**
2020-03-21 04:11:51 +00:00
- alphanumeric `String` of encoded coordinate (modified version of the base32-encoding alphabet is used).
2019-04-09 19:19:30 +00:00
**Example**
2020-03-20 10:10:48 +00:00
``` sql
2019-04-09 19:19:30 +00:00
SELECT geohashEncode(-5.60302734375, 42.593994140625, 0) AS res
```
2020-03-20 10:10:48 +00:00
``` text
2019-04-09 19:19:30 +00:00
┌─res──────────┐
│ ezs42d000000 │
└──────────────┘
```
2020-03-20 10:10:48 +00:00
## geohashDecode {#geohashdecode}
2019-04-09 19:19:30 +00:00
Decodes any geohash-encoded string into longitude and latitude.
**Input values**
2020-03-21 04:11:51 +00:00
- encoded string - geohash-encoded string.
2019-04-09 19:19:30 +00:00
**Returned values**
2020-03-21 04:11:51 +00:00
- (longitude, latitude) - 2-tuple of `Float64` values of longitude and latitude.
2019-04-09 19:19:30 +00:00
**Example**
2020-03-20 10:10:48 +00:00
``` sql
2019-04-09 19:19:30 +00:00
SELECT geohashDecode('ezs42') AS res
```
2020-03-20 10:10:48 +00:00
``` text
2019-04-09 19:19:30 +00:00
┌─res─────────────────────────────┐
│ (-5.60302734375,42.60498046875) │
└─────────────────────────────────┘
```
2018-10-16 10:47:17 +00:00
2020-03-18 18:43:51 +00:00
## geoToH3 {#geotoh3}
2019-07-18 11:04:45 +00:00
2019-12-16 19:35:12 +00:00
Returns [H3 ](https://uber.github.io/h3/#/documentation/overview/introduction ) point index `(lon, lat)` with specified resolution.
2020-03-20 10:10:48 +00:00
[H3 ](https://uber.github.io/h3/#/documentation/overview/introduction ) is a geographical indexing system where Earth’ s surface divided into even hexagonal tiles. This system is hierarchical, i. e. each hexagon on the top level can be splitted into seven even but smaller ones and so on.
2019-12-16 19:35:12 +00:00
2019-12-16 19:25:14 +00:00
This index is used primarily for bucketing locations and other geospatial manipulations.
2020-03-20 10:10:48 +00:00
**Syntax**
2019-07-18 11:04:45 +00:00
2020-03-20 10:10:48 +00:00
``` sql
2019-07-18 11:04:45 +00:00
geoToH3(lon, lat, resolution)
```
2020-03-20 10:10:48 +00:00
**Parameters**
2019-07-18 11:04:45 +00:00
2020-04-30 18:19:18 +00:00
- `lon` — Longitude. Type: [Float64 ](../../sql-reference/data-types/float.md ).
- `lat` — Latitude. Type: [Float64 ](../../sql-reference/data-types/float.md ).
- `resolution` — Index resolution. Range: `[0, 15]` . Type: [UInt8 ](../../sql-reference/data-types/int-uint.md ).
2019-07-18 11:04:45 +00:00
**Returned values**
2020-03-21 04:11:51 +00:00
- Hexagon index number.
- 0 in case of error.
2019-07-18 11:04:45 +00:00
2019-12-16 19:25:14 +00:00
Type: `UInt64` .
2019-07-18 11:04:45 +00:00
**Example**
2019-12-16 19:25:14 +00:00
Query:
2020-03-20 10:10:48 +00:00
``` sql
2019-07-18 11:04:45 +00:00
SELECT geoToH3(37.79506683, 55.71290588, 15) as h3Index
```
2019-12-16 19:25:14 +00:00
Result:
2020-03-20 10:10:48 +00:00
``` text
2019-07-18 11:04:45 +00:00
┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘
```
2020-03-20 10:10:48 +00:00
## geohashesInBox {#geohashesinbox}
2019-07-15 12:51:08 +00:00
Returns an array of geohash-encoded strings of given precision that fall inside and intersect boundaries of given box, basically a 2D grid flattened into array.
**Input values**
2020-03-21 04:11:51 +00:00
- longitude\_min - min longitude, floating value in range `[-180°, 180°]`
- latitude\_min - min latitude, floating value in range `[-90°, 90°]`
- longitude\_max - max longitude, floating value in range `[-180°, 180°]`
- latitude\_max - max latitude, floating value in range `[-90°, 90°]`
- precision - geohash precision, `UInt8` in range `[1, 12]`
2019-07-15 12:51:08 +00:00
Please note that all coordinate parameters should be of the same type: either `Float32` or `Float64` .
**Returned values**
2020-03-21 04:11:51 +00:00
- array of precision-long strings of geohash-boxes covering provided area, you should not rely on order of items.
- \[\] - empty array if *min* values of *latitude* and *longitude* aren’ t less than corresponding *max* values.
2019-07-15 12:51:08 +00:00
2020-03-20 10:10:48 +00:00
Please note that function will throw an exception if resulting array is over 10’ 000’ 000 items long.
2019-07-15 12:51:08 +00:00
**Example**
2020-03-20 10:10:48 +00:00
``` sql
2019-07-15 12:51:08 +00:00
SELECT geohashesInBox(24.48, 40.56, 24.785, 40.81, 4) AS thasos
```
2020-03-20 10:10:48 +00:00
``` text
2019-07-15 12:51:08 +00:00
┌─thasos──────────────────────────────────────┐
│ ['sx1q','sx1r','sx32','sx1w','sx1x','sx38'] │
└─────────────────────────────────────────────┘
```
2020-03-20 10:10:48 +00:00
## h3GetBaseCell {#h3getbasecell}
2020-01-26 19:16:10 +00:00
Returns the base cell number of the index.
**Syntax**
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
h3GetBaseCell(index)
```
2020-03-20 10:10:48 +00:00
**Parameters**
2020-01-26 19:16:10 +00:00
2020-04-30 18:19:18 +00:00
- `index` — Hexagon index number. Type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Returned values**
2020-04-30 18:19:18 +00:00
- Hexagon base cell number. Type: [UInt8 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Example**
Query:
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
SELECT h3GetBaseCell(612916788725809151) as basecell
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2020-01-26 19:16:10 +00:00
┌─basecell─┐
│ 12 │
└──────────┘
```
2020-03-20 10:10:48 +00:00
## h3HexAreaM2 {#h3hexaream2}
2020-01-26 19:16:10 +00:00
Average hexagon area in square meters at the given resolution.
2020-03-20 10:10:48 +00:00
**Syntax**
2020-01-26 19:16:10 +00:00
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
h3HexAreaM2(resolution)
```
2020-03-20 10:10:48 +00:00
**Parameters**
2020-01-26 19:16:10 +00:00
2020-04-30 18:19:18 +00:00
- `resolution` — Index resolution. Range: `[0, 15]` . Type: [UInt8 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Returned values**
2020-04-30 18:19:18 +00:00
- Area in m². Type: [Float64 ](../../sql-reference/data-types/float.md ).
2020-01-26 19:16:10 +00:00
**Example**
Query:
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
SELECT h3HexAreaM2(13) as area
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2020-01-26 19:16:10 +00:00
┌─area─┐
│ 43.9 │
└──────┘
```
2020-03-20 10:10:48 +00:00
## h3IndexesAreNeighbors {#h3indexesareneighbors}
2020-01-26 19:16:10 +00:00
Returns whether or not the provided H3Indexes are neighbors.
**Syntax**
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
h3IndexesAreNeighbors(index1, index2)
```
2020-03-20 10:10:48 +00:00
**Parameters**
2020-01-26 19:16:10 +00:00
2020-04-30 18:19:18 +00:00
- `index1` — Hexagon index number. Type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
- `index2` — Hexagon index number. Type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Returned values**
2020-04-30 18:19:18 +00:00
- Returns `1` if the indexes are neighbors, `0` otherwise. Type: [UInt8 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Example**
Query:
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2020-01-26 19:16:10 +00:00
┌─n─┐
│ 1 │
└───┘
```
2020-03-20 10:10:48 +00:00
## h3ToChildren {#h3tochildren}
2020-01-26 19:16:10 +00:00
Returns an array with the child indexes of the given index.
**Syntax**
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
h3ToChildren(index, resolution)
```
2020-03-20 10:10:48 +00:00
**Parameters**
2020-01-26 19:16:10 +00:00
2020-04-30 18:19:18 +00:00
- `index` — Hexagon index number. Type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
- `resolution` — Index resolution. Range: `[0, 15]` . Type: [UInt8 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Returned values**
2020-04-30 18:19:18 +00:00
- Array with the child H3 indexes. Array of type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Example**
Query:
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
SELECT h3ToChildren(599405990164561919, 6) AS children
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2020-01-26 19:16:10 +00:00
┌─children───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [603909588852408319,603909588986626047,603909589120843775,603909589255061503,603909589389279231,603909589523496959,603909589657714687] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
2020-03-20 10:10:48 +00:00
## h3ToParent {#h3toparent}
2020-01-26 19:16:10 +00:00
Returns the parent (coarser) index containing the given index.
**Syntax**
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
h3ToParent(index, resolution)
```
2020-03-20 10:10:48 +00:00
**Parameters**
2020-01-26 19:16:10 +00:00
2020-04-30 18:19:18 +00:00
- `index` — Hexagon index number. Type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
- `resolution` — Index resolution. Range: `[0, 15]` . Type: [UInt8 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Returned values**
2020-04-30 18:19:18 +00:00
- Parent H3 index. Type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Example**
Query:
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
SELECT h3ToParent(599405990164561919, 3) as parent
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2020-01-26 19:16:10 +00:00
┌─────────────parent─┐
│ 590398848891879423 │
└────────────────────┘
```
2020-03-20 10:10:48 +00:00
## h3ToString {#h3tostring}
2020-01-26 19:16:10 +00:00
2020-03-20 10:10:48 +00:00
Converts the H3Index representation of the index to the string representation.
2020-01-26 19:16:10 +00:00
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
h3ToString(index)
```
2020-03-20 10:10:48 +00:00
**Parameters**
2020-01-26 19:16:10 +00:00
2020-04-30 18:19:18 +00:00
- `index` — Hexagon index number. Type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Returned values**
2020-04-30 18:19:18 +00:00
- String representation of the H3 index. Type: [String ](../../sql-reference/data-types/string.md ).
2020-01-26 19:16:10 +00:00
**Example**
2020-03-20 10:10:48 +00:00
Query:
2020-01-26 19:16:10 +00:00
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
SELECT h3ToString(617420388352917503) as h3_string
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2020-01-26 19:16:10 +00:00
┌─h3_string───────┐
│ 89184926cdbffff │
└─────────────────┘
```
2020-03-20 10:10:48 +00:00
## stringToH3 {#stringtoh3}
2020-01-26 19:16:10 +00:00
Converts the string representation to H3Index (UInt64) representation.
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
stringToH3(index_str)
```
2020-03-20 10:10:48 +00:00
**Parameters**
2020-01-26 19:16:10 +00:00
2020-04-30 18:19:18 +00:00
- `index_str` — String representation of the H3 index. Type: [String ](../../sql-reference/data-types/string.md ).
2020-01-26 19:16:10 +00:00
**Returned values**
2020-04-30 18:19:18 +00:00
- Hexagon index number. Returns 0 on error. Type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Example**
Query:
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
SELECT stringToH3('89184926cc3ffff') as index
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2020-01-26 19:16:10 +00:00
┌──────────────index─┐
│ 617420388351344639 │
└────────────────────┘
```
2020-03-20 10:10:48 +00:00
## h3GetResolution {#h3getresolution}
2020-01-26 19:16:10 +00:00
Returns the resolution of the index.
**Syntax**
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
h3GetResolution(index)
```
2020-03-20 10:10:48 +00:00
**Parameters**
2020-01-26 19:16:10 +00:00
2020-04-30 18:19:18 +00:00
- `index` — Hexagon index number. Type: [UInt64 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Returned values**
2020-04-30 18:19:18 +00:00
- Index resolution. Range: `[0, 15]` . Type: [UInt8 ](../../sql-reference/data-types/int-uint.md ).
2020-01-26 19:16:10 +00:00
**Example**
Query:
2020-03-20 10:10:48 +00:00
``` sql
2020-01-26 19:16:10 +00:00
SELECT h3GetResolution(617420388352917503) as res
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2020-01-26 19:16:10 +00:00
┌─res─┐
│ 9 │
└─────┘
```
2020-01-30 10:34:55 +00:00
[Original article ](https://clickhouse.tech/docs/en/query_language/functions/geo/ ) <!--hide-->