Functions for Working with Geographical Coordinates

greatCircleDistance

Calculates the distance between two points on the Earth's surface using the great-circle formula.

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 Earth's surface, in meters.

Generates an exception when the input parameter values fall outside of the range.

Example

SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance

┌─greatCircleDistance─┐
│            14128352 │
└─────────────────────┘

geoDistance

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.

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 Earth's surface, in meters.

Generates an exception when the input parameter values fall outside of the range.

Example

SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance

┌─geoDistance─┐
│   212458.73 │
└─────────────┘

greatCircleAngle

Calculates the central angle between two points on the Earth's surface using the great-circle formula.

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

SELECT greatCircleAngle(0, 0, 45, 0) AS arc

┌─arc─┐
│  45 │
└─────┘

geoToUTM

Converts WGS84 geographic coordinates (longitude, latitude) to Universal Transverse Mercator (UTM) coordinates.

UTM is a set of 60 transverse Mercator projections, each covering a 6°-wide longitudinal zone, that map geographic coordinates to a planar grid in metres. The zone is selected automatically from the longitude, applying the standard exceptions for Norway and Svalbard, unless an explicit zone is given. UTM is only defined for latitudes in the range [-80°, 84°]; the polar caps use the separate UPS system.

geoToUTM(longitude, latitude[, zone])

Arguments

• longitude — Longitude in degrees. Range: [-180°, 180°]. Float32/Float64.
• latitude — Latitude in degrees. Range: [-80°, 84°]. Float32/Float64.
• zone — Optional. Force the projection into this UTM zone instead of selecting it automatically. Range: [1, 60]. (U)Int*.

Returned value

A named tuple (easting, northing, zone, band): easting and northing in metres (Float64), the UTM zone number (UInt8), and the MGRS latitude band letter (FixedString(1)). A band of 'N' or later denotes the northern hemisphere.

Generates an exception when the latitude is outside [-80°, 84°] or the longitude is outside [-180°, 180°].

Example

SELECT geoToUTM(2.294497, 48.858222) AS utm; -- Eiffel Tower

(448251.5978370684,5411935.125629659,31,'U')

UTMToGeo

Converts UTM coordinates back to WGS84 geographic coordinates (longitude, latitude). This is the inverse of geoToUTM.

UTMToGeo(easting, northing, zone, is_north)

Arguments

• easting — Easting in metres (includes the 500000 m false easting). (U)Int*/Float*.
• northing — Northing in metres (includes the 10000000 m false northing on the southern hemisphere). (U)Int*/Float*.
• zone — UTM zone number. Range: [1, 60]. (U)Int*.
• is_north — Hemisphere: 1 for the northern hemisphere, 0 for the southern. (U)Int*.

Returned value

A named tuple (longitude, latitude) in degrees. Tuple(Float64, Float64).

Example

SELECT UTMToGeo(448251.6, 5411935.13, 31, 1) AS coord;

(2.2944970289079203,48.85822204127082)

geoToMGRS

Encodes WGS84 geographic coordinates (longitude, latitude) as a Military Grid Reference System (MGRS) string.

The string is <zone><band><100km square><easting><northing>, for example 31UDQ4825111935. The precision argument controls the number of digits used for each of the easting and northing: 5 (default) for 1 m, 4 for 10 m, 3 for 100 m, 2 for 1 km, 1 for 10 km, and 0 for the 100 km grid square only. MGRS is only defined for latitudes in the range [-80°, 84°].

geoToMGRS(longitude, latitude[, precision])

Arguments

• longitude — Longitude in degrees. Range: [-180°, 180°]. Float32/Float64.
• latitude — Latitude in degrees. Range: [-80°, 84°]. Float32/Float64.
• precision — Optional. Number of digits for each of easting and northing. Default: 5. Range: [0, 5]. (U)Int*.

Returned value

The MGRS reference string. String.

Example

SELECT geoToMGRS(2.294497, 48.858222) AS mgrs, geoToMGRS(2.294497, 48.858222, 3) AS mgrs_100m;

┌─mgrs────────────┬─mgrs_100m───┐
│ 31UDQ4825111935 │ 31UDQ482119 │
└─────────────────┴─────────────┘

MGRSToGeo

Decodes an MGRS string into WGS84 geographic coordinates (longitude, latitude). This is the inverse of geoToMGRS.

The returned point is the centre of the referenced grid square, so the precision of the result matches the precision encoded in the string. Whitespace in the input is ignored and letters are case-insensitive.

MGRSToGeo(mgrs)

Arguments

• mgrs — MGRS reference string to decode. String/FixedString.

Returned value

A named tuple (longitude, latitude) in degrees. Tuple(Float64, Float64).

Example

SELECT MGRSToGeo('31UDQ4825111935') AS coord;

(2.294495618908297,48.85822536113692)

pointInEllipses

Checks whether the point belongs to at least one of the ellipses. Coordinates are geometric in the Cartesian coordinate system.

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+4⋅n, where n is the number of ellipses.

Returned values

1 if the point is inside at least one of the ellipses; 0if it is not.

Example

SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)

┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│                                               1 │
└─────────────────────────────────────────────────┘

pointInPolygon

Checks whether the point belongs to the polygon on the plane.

pointInPolygon((x, y), [(a, b), (c, d) ...], ...)

Input values

• (x, y) — Coordinates of a point on the plane. Data type — Tuple — A tuple of two numbers.
• [(a, b), (c, d) ...] — Polygon vertices. Data type — Array. 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 supports polygon with holes (cut-out sections). Data type — Polygon. Either pass the entire Polygon as the second argument, or pass the outer ring first and then each hole as separate additional arguments.
• The function also supports multipolygon. Data type — MultiPolygon. Either pass the entire MultiPolygon as the second argument, or list each component polygon as its own argument.

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

SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res

┌─res─┐
│   1 │
└─────┘

Note
• You can set validate_polygons = 0 to bypass geometry validation.
• pointInPolygon assumes every polygon is well-formed. If the input is self-intersecting, has mis-ordered rings, or overlapping edges, results become unreliable—especially for points that sit exactly on an edge, a vertex, or inside a self-intersection where the notion of "inside" vs. "outside" is undefined. • When the polygon argument is constant and the point is expressed using indexed key columns (for example, pointInPolygon((x, y), constant_polygon) on a table where x, y are part of the PRIMARY KEY or covered by a minmax index), ClickHouse can use both the primary key and minmax data-skipping indexes to prune irrelevant granules.