> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > Documentación de coordenadas # Funciones para trabajar con coordenadas geográficas
## greatCircleDistance
Calcula la distancia entre dos puntos sobre la superficie terrestre usando [la fórmula del gran círculo](https://en.wikipedia.org/wiki/Great-circle_distance). ```sql theme={null} greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg) ``` **Parámetros de entrada** * `lon1Deg` — Longitud del primer punto en grados. Rango: `[-180°, 180°]`. * `lat1Deg` — Latitud del primer punto en grados. Rango: `[-90°, 90°]`. * `lon2Deg` — Longitud del segundo punto en grados. Rango: `[-180°, 180°]`. * `lat2Deg` — Latitud del segundo punto en grados. Rango: `[-90°, 90°]`. Los valores positivos corresponden a la latitud norte y la longitud este, mientras que los valores negativos corresponden a la latitud sur y la longitud oeste. **Valor devuelto** La distancia entre dos puntos de la superficie terrestre, en metros. Genera una excepción cuando los valores de los parámetros de entrada están fuera del rango. **Ejemplo** ```sql theme={null} SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance ``` ```text theme={null} ┌─greatCircleDistance─┐ │ 14128352 │ └─────────────────────┘ ```
## geoDistance
Es similar a `greatCircleDistance`, pero calcula la distancia sobre el elipsoide WGS-84 en lugar de hacerlo sobre una esfera. Esta es una aproximación más precisa del geoide terrestre. El rendimiento es el mismo que el de `greatCircleDistance` (sin pérdida de rendimiento). Se recomienda usar `geoDistance` para calcular distancias sobre la Tierra. Nota técnica: para puntos suficientemente cercanos, calculamos la distancia mediante una aproximación plana con la métrica en el plano tangente en el punto medio de las coordenadas. ```sql theme={null} geoDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg) ``` **Parámetros de entrada** * `lon1Deg` — Longitud del primer punto en grados. Rango: `[-180°, 180°]`. * `lat1Deg` — Latitud del primer punto en grados. Rango: `[-90°, 90°]`. * `lon2Deg` — Longitud del segundo punto en grados. Rango: `[-180°, 180°]`. * `lat2Deg` — Latitud del segundo punto en grados. Rango: `[-90°, 90°]`. Los valores positivos corresponden a la latitud norte y la longitud este, y los valores negativos corresponden a la latitud sur y la longitud oeste. **Valor devuelto** La distancia entre dos puntos de la superficie terrestre, en metros. Genera una excepción cuando los valores de los parámetros de entrada están fuera del rango. **Ejemplo** ```sql theme={null} SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance ``` ```text theme={null} ┌─geoDistance─┐ │ 212458.73 │ └─────────────┘ ```
## greatCircleAngle
Calcula el ángulo central entre dos puntos de la superficie terrestre usando [la fórmula del gran círculo](https://en.wikipedia.org/wiki/Great-circle_distance). ```sql theme={null} greatCircleAngle(lon1Deg, lat1Deg, lon2Deg, lat2Deg) ``` **Parámetros de entrada** * `lon1Deg` — Longitud del primer punto, en grados. * `lat1Deg` — Latitud del primer punto, en grados. * `lon2Deg` — Longitud del segundo punto, en grados. * `lat2Deg` — Latitud del segundo punto, en grados. **Valor devuelto** El ángulo central entre dos puntos, en grados. **Ejemplo** ```sql theme={null} SELECT greatCircleAngle(0, 0, 45, 0) AS arc ``` ```text theme={null} ┌─arc─┐ │ 45 │ └─────┘ ```
## geoToUTM
Convierte coordenadas geográficas WGS84 `(longitude, latitude)` en coordenadas de la [Universal Transversa de Mercator (UTM)](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system). UTM es un conjunto de 60 proyecciones transversas de Mercator, cada una de las cuales cubre una zona longitudinal de 6°, que convierten coordenadas geográficas en una cuadrícula plana en metros. La zona se selecciona automáticamente a partir de la longitud, aplicando las excepciones estándar para Noruega y Svalbard, a menos que se indique una `zone` explícita. UTM solo está definido para latitudes en el rango `[-80°, 84°]`; los casquetes polares usan el sistema UPS por separado. ```sql theme={null} geoToUTM(longitude, latitude[, zone]) ``` **Argumentos** * `longitude` — Longitud en grados. Rango: `[-180°, 180°]`. [`Float32`](/docs/es/reference/data-types/float)/[`Float64`](/docs/es/reference/data-types/float). * `latitude` — Latitud en grados. Rango: `[-80°, 84°]`. [`Float32`](/docs/es/reference/data-types/float)/[`Float64`](/docs/es/reference/data-types/float). * `zone` — Opcional. Fuerza el uso de esta zona UTM en lugar de seleccionarla automáticamente. Rango: `[1, 60]`. [`(U)Int*`](/docs/es/reference/data-types/int-uint). **Valor devuelto** Una tupla con nombre `(easting, northing, zone, band)`: `easting` y `northing` en metros ([`Float64`](/docs/es/reference/data-types/float)), el número de zona UTM `zone` ([`UInt8`](/docs/es/reference/data-types/int-uint)) y la letra de banda de latitud MGRS `band` ([`FixedString(1)`](/docs/es/reference/data-types/fixedstring)). Un `band` de `'N'` o una letra posterior indica el hemisferio norte. Genera una excepción cuando la latitud está fuera de `[-80°, 84°]` o la longitud está fuera de `[-180°, 180°]`. **Ejemplo** ```sql theme={null} SELECT geoToUTM(2.294497, 48.858222) AS utm; -- Eiffel Tower ``` ```text theme={null} (448251.5978370684,5411935.125629659,31,'U') ```
## UTMToGeo
Convierte las coordenadas [UTM](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system) nuevamente a coordenadas geográficas WGS84 `(longitud, latitud)`. Es la operación inversa de [`geoToUTM`](#geotoutm). ```sql theme={null} UTMToGeo(easting, northing, zone, is_north) ``` **Argumentos** * `easting` — Coordenada este en metros (incluye el falso este de 500000 m). [`(U)Int*`](/docs/es/reference/data-types/int-uint)/[`Float*`](/docs/es/reference/data-types/float). * `northing` — Coordenada norte en metros (incluye el falso norte de 10000000 m en el hemisferio sur). [`(U)Int*`](/docs/es/reference/data-types/int-uint)/[`Float*`](/docs/es/reference/data-types/float). * `zone` — Número de zona UTM. Rango: `[1, 60]`. [`(U)Int*`](/docs/es/reference/data-types/int-uint). * `is_north` — Hemisferio: `1` para el hemisferio norte, `0` para el hemisferio sur. [`(U)Int*`](/docs/es/reference/data-types/int-uint). **Valor devuelto** Una tupla con nombre `(longitude, latitude)` en grados. [`Tuple(Float64, Float64)`](/docs/es/reference/data-types/tuple). **Ejemplo** ```sql theme={null} SELECT UTMToGeo(448251.6, 5411935.13, 31, 1) AS coord; ``` ```text theme={null} (2.2944970289079203,48.85822204127082) ```
## geoToMGRS
Codifica coordenadas geográficas WGS84 `(longitude, latitude)` como una cadena del [Military Grid Reference System (MGRS)](https://en.wikipedia.org/wiki/Military_Grid_Reference_System). La cadena es `<100km square>`, por ejemplo `31UDQ4825111935`. El argumento `precision` controla el número de dígitos usados para cada uno de los valores de coordenada este y coordenada norte: `5` (por defecto) para 1 m, `4` para 10 m, `3` para 100 m, `2` para 1 km, `1` para 10 km y `0` únicamente para el cuadrado de cuadrícula de 100 km. MGRS solo está definido para latitudes en el intervalo `[-80°, 84°]`. ```sql theme={null} geoToMGRS(longitude, latitude[, precision]) ``` **Argumentos** * `longitude` — Longitud en grados. Rango: `[-180°, 180°]`. [`Float32`](/docs/es/reference/data-types/float)/[`Float64`](/docs/es/reference/data-types/float). * `latitude` — Latitud en grados. Rango: `[-80°, 84°]`. [`Float32`](/docs/es/reference/data-types/float)/[`Float64`](/docs/es/reference/data-types/float). * `precision` — Opcional. Número de dígitos para cada una de las coordenadas este y norte. Valor predeterminado: `5`. Rango: `[0, 5]`. [`(U)Int*`](/docs/es/reference/data-types/int-uint). **Valor devuelto** La cadena de referencia MGRS. [`String`](/docs/es/reference/data-types/string). **Ejemplo** ```sql theme={null} SELECT geoToMGRS(2.294497, 48.858222) AS mgrs, geoToMGRS(2.294497, 48.858222, 3) AS mgrs_100m; ``` ```text theme={null} ┌─mgrs────────────┬─mgrs_100m───┐ │ 31UDQ4825111935 │ 31UDQ482119 │ └─────────────────┴─────────────┘ ```
## MGRSToGeo
Decodifica una cadena [MGRS](https://en.wikipedia.org/wiki/Military_Grid_Reference_System) en coordenadas geográficas WGS84 `(longitud, latitud)`. Esta es la operación inversa de [`geoToMGRS`](#geotomgrs). El punto devuelto es el centro del cuadrado de la cuadrícula indicado, por lo que la precisión del resultado coincide con la precisión codificada en la cadena. Se ignoran los espacios en blanco de la entrada y no se distingue entre mayúsculas y minúsculas en las letras. ```sql theme={null} MGRSToGeo(mgrs) ``` **Argumentos** * `mgrs` — cadena de referencia MGRS que se va a decodificar. [`String`](/docs/es/reference/data-types/string)/[`FixedString`](/docs/es/reference/data-types/fixedstring). **Valor devuelto** Una tupla con nombre `(longitude, latitude)` en grados. [`Tuple(Float64, Float64)`](/docs/es/reference/data-types/tuple). **Ejemplo** ```sql theme={null} SELECT MGRSToGeo('31UDQ4825111935') AS coord; ``` ```text theme={null} (2.294495618908297,48.85822536113692) ```
## pointInEllipses
Comprueba si el punto pertenece a al menos una de las elipses. Las coordenadas son geométricas y se expresan en el sistema de coordenadas cartesianas. ```sql theme={null} pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ) ``` **Parámetros de entrada** * `x, y` — Coordenadas de un punto en el plano. * `xᵢ, yᵢ` — Coordenadas del centro de la elipse `i`. * `aᵢ, bᵢ` — Ejes de la elipse `i` en unidades de las coordenadas `x` e `y`. La cantidad de parámetros de entrada debe ser `2+4⋅n`, donde `n` es el número de elipses. **Valores devueltos** `1` si el punto está dentro de al menos una de las elipses; `0` si no lo está. **Ejemplo** ```sql theme={null} SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999) ``` ```text theme={null} ┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐ │ 1 │ └─────────────────────────────────────────────────┘ ```
## pointInPolygon
Comprueba si el punto está dentro del polígono en el plano. ```sql theme={null} pointInPolygon((x, y), [(a, b), (c, d) ...], ...) ``` **Valores de entrada** * `(x, y)` — Coordenadas de un punto en el plano. Tipo de dato — [Tuple](/docs/es/reference/data-types/tuple) — Una tupla de dos números, o un [Point](/docs/es/reference/data-types/geo#point). * `[(a, b), (c, d) ...]` — Vértices del polígono. Tipo de dato — [Array](/docs/es/reference/data-types/array) o [Ring](/docs/es/reference/data-types/geo#ring). Cada vértice se representa mediante un par de coordenadas `(a, b)`. Los vértices deben especificarse en sentido horario o antihorario. El número mínimo de vértices es 3. * La función admite polígonos con huecos (secciones recortadas). Tipo de dato — [Polygon](/docs/es/reference/data-types/geo#polygon). Pase el `Polygon` completo como segundo argumento, o bien pase primero el anillo exterior y luego cada hueco como argumento adicional independiente. * La función también admite multipolígonos. Tipo de dato — [MultiPolygon](/docs/es/reference/data-types/geo#multipolygon). Pase el `MultiPolygon` completo como segundo argumento, o indique cada polígono componente como un argumento independiente. * El argumento del polígono también puede ser una columna [Geometry](/docs/es/reference/data-types/geo#geometry) que contenga valores de tipo polígono (`Ring`, `Polygon` o `MultiPolygon`). Los tipos de polígono ([Ring](/docs/es/reference/data-types/geo#ring), [Polygon](/docs/es/reference/data-types/geo#polygon), [MultiPolygon](/docs/es/reference/data-types/geo#multipolygon) y [Geometry](/docs/es/reference/data-types/geo#geometry)) pueden pasarse tanto como constantes como columnas de tabla normales (no constantes). Cuando el polígono se proporciona mediante varios argumentos independientes (un anillo exterior seguido de huecos, o varios polígonos de un multipolígono), todos esos argumentos deben ser constantes. **Valores devueltos** `1` si el punto está dentro del polígono, `0` si no lo está. Si el punto está en el borde del polígono, la función puede devolver 0 o 1. **Ejemplo** ```sql theme={null} SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res ``` ```text theme={null} ┌─res─┐ │ 1 │ └─────┘ ``` El polígono también puede proporcionarse mediante los tipos de datos geométricos con nombre, incluso como columna de una tabla: ```sql theme={null} CREATE TABLE poly (id UInt32, shape Polygon) ENGINE = Memory; INSERT INTO poly VALUES (1, [[(0, 0), (10, 0), (10, 10), (0, 10)], [(4, 4), (6, 4), (6, 6), (4, 6)]]); SELECT id, pointInPolygon((2., 2.), shape) AS res FROM poly; ``` ```text theme={null} ┌─id─┬─res─┐ │ 1 │ 1 │ └────┴─────┘ ``` > **Nota** > • Puede establecer `validate_polygons = 0` para omitir la validación geométrica. > • `pointInPolygon` asume que cada polígono está bien formado. Si la entrada se interseca a sí misma, tiene anillos en un orden incorrecto o bordes superpuestos, los resultados dejan de ser fiables, especialmente para puntos que están exactamente sobre un borde, un vértice o dentro de una autointersección, donde la noción de "dentro" frente a "fuera" no está definida. > • Cuando el argumento del polígono es constante y el punto se expresa mediante columnas de clave indexadas (por ejemplo, `pointInPolygon((x, y), constant_polygon)` en una tabla donde `x, y` forman parte de la `PRIMARY KEY` o están incluidas en un índice `minmax`), ClickHouse puede usar tanto la clave primaria como los índices de omisión de datos `minmax` para descartar gránulos irrelevantes.