Project: ClickHouse (App Definition and Development / Database)
File: coordinates.md

slug: /en/sql-reference/functions/geo/coordinates sidebar_label: Geographical Coordinates sidebar_position: 62 title: "Functions for Working with Geographical Coordinates" Calculates the distance between two points on the Earths surface using . ``` sql greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg) ``` Input parameters `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]`. Positive values correspond to North latitude and East longitude, and negative values correspond to South latitude and West longitude. Returned value The distance between two points on the Earths surface, in meters. Generates an exception when the input parameter values fall outside of the range. Example ``` sql SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance ``` ``` text greatCircleDistance 14128352 ``` Similar to `greatCircleDistance` but calculates the distance on WGS-84 ellipsoid instead of sphere. This is more precise approximation of the Earth Geoid. The performance is the same as for `greatCircleDistance` (no performance drawback). It is recommended to use `geoDistance` to calculate the distances on Earth. Technical note: for close enough points we calculate the distance using planar approximation with the metric on the tangent plane at the midpoint of the coordinates. ``` sql geoDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg) ``` Input parameters `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]`. Positive values correspond to North latitude and East longitude, and negative values correspond to South latitude and West longitude. Returned value The distance between two points on the Earths surface, in meters. Generates an exception when the input parameter values fall outside of the range. Example ``` sql SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance ``` ``` text geoDistance 212458.73 ``` Calculates the central angle between two points on the Earths surface using

``` sql greatCircleAngle(lon1Deg, lat1Deg, lon2Deg, lat2Deg) ``` Input parameters `lon1Deg` Longitude of the first point in degrees. `lat1Deg` Latitude of the first point in degrees. `lon2Deg` Longitude of the second point in degrees. `lat2Deg` Latitude of the second point in degrees. Returned value The central angle between two points in degrees. Example ``` sql SELECT greatCircleAngle(0, 0, 45, 0) AS arc ``` ``` text arc 45 ``` Checks whether the point belongs to at least one of the ellipses. Coordinates are geometric in the Cartesian coordinate system. ``` sql pointInEllipses(x, y, x, y, a, b,...,x, y, a, b) ``` Input parameters `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. The input parameters must be `2+4n`, 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. Example ``` sql SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999) ``` ``` text pointInEllipses(10., 10., 10., 9.1, 1., 0.9999) 1 ``` Checks whether the point belongs to the polygon on the plane. ``` sql pointInPolygon((x, y), [(a, b), (c, d) ...], ...) ``` Input values `(x, y)` Coordinates of a point on the plane. Data type A tuple of two numbers. `. 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. 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. 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 ``` sql SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res ``` ``` text res 1 ```