# Функции для работы с географическими координатами

## greatCircleDistance

Вычисляет расстояние между двумя точками на поверхности Земли по [формуле большого круга](https://en.wikipedia.org/wiki/Great-circle_distance).

```sql
greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```

**Входные параметры**

- `lon1Deg` — долгота первой точки в градусах. Диапазон — `[-180°, 180°]`.
- `lat1Deg` — широта первой точки в градусах. Диапазон — `[-90°, 90°]`.
- `lon2Deg` — долгота второй точки в градусах. Диапазон — `[-180°, 180°]`.
- `lat2Deg` — широта второй точки в градусах. Диапазон — `[-90°, 90°]`.

Положительные значения соответствуют северной широте и восточной долготе, отрицательные — южной широте и западной долготе.

**Возвращаемое значение**

Расстояние между двумя точками на поверхности Земли в метрах.

Генерирует исключение, когда значения входных параметров выходят за границы диапазонов.

**Пример**

```sql
SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673)
```

```text
┌─greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673)─┐
│                                                14132374.194975413 │
└───────────────────────────────────────────────────────────────────┘
```

## pointInEllipses

Проверяет, принадлежит ли точка хотя бы одному из эллипсов.
Координаты — геометрические в декартовой системе координат.

```
pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ)
```

**Входные параметры**

- `x, y` — координаты точки на плоскости.
- `xᵢ, yᵢ` — координаты центра `i`-го эллипса.
- `aᵢ, bᵢ` — полуоси `i`-го эллипса (в единицах измерения координат x,y).

Входных параметров должно быть `2+4⋅n`, где `n` — количество эллипсов.

**Возвращаемые значения**

`1`, если точка внутри хотя бы одного из эллипсов, `0`, если нет.

**Пример**

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

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

## pointInPolygon

Проверяет, принадлежит ли точка многоугольнику на плоскости.

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

**Входные значения**

- `(x, y)` — координаты точки на плоскости. Тип данных — [Tuple](../../data_types/tuple.md) —  кортеж из двух чисел.
- `[(a, b), (c, d) ...]` — вершины многоугольника. Тип данных — [Array](../../data_types/array.md). Каждая вершина представлена парой координат `(a, b)`. Вершины следует указывать в порядке обхода по или против часовой стрелки. Минимальное количество вершин — 3. Многоугольник должен быть константным.
- функция поддерживает также многоугольники с дырками (вырезанными кусками). Для этого случая, добавьте многоугольники, описывающие вырезанные куски, дополнительными аргументами функции. Функция не поддерживает не односвязные многоугольники.

**Возвращаемые значения**

`1`, если точка внутри многоугольника, `0`, если нет.
Если точка находится на границе многоугольника, функция может возвращать как 0, так и 1.

**Пример**

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

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

## geohashEncode

Кодирует широту и долготу в строку geohash, смотрите [http://geohash.org/](http://geohash.org/), [https://en.wikipedia.org/wiki/Geohash](https://en.wikipedia.org/wiki/Geohash).

```sql
geohashEncode(longitude, latitude, [precision])
```

**Входные значения**

- longitude — долгота. Диапазон — `[-180°, 180°].`
- latitude — широта. Диапазон — `[-90°, 90°].`
- precision — длина результирующей строки, по умолчанию `12`. Опционально. Целое число в диапазоне `[1, 12]`. Любое значение меньше, чем `1` или больше `12` автоматически преобразуются в `12`.

**Возвращаемые значения**

- Строка с координатой, закодированной модифицированной версией алфавита base32.

**Пример**

```sql
SELECT geohashEncode(-5.60302734375, 42.593994140625, 0) AS res
```

```text
┌─res──────────┐
│ ezs42d000000 │
└──────────────┘
```

## geohashDecode

Декодирует любую строку, закодированную в geohash, на долготу и широту.

```sql
geohashDecode(geohash_string)
```

**Входные значения**

- `geohash_string` — строка, содержащая geohash.

**Возвращаемые значения**

- `(longitude, latitude)` — широта и долгота. Кортеж из двух значений типа `Float64`.

**Пример**

```sql
SELECT geohashDecode('ezs42') AS res
```

```text
┌─res─────────────────────────────┐
│ (-5.60302734375,42.60498046875) │
└─────────────────────────────────┘
```

## geoToH3

Получает H3 индекс точки `(lon, lat)` с заданным разрешением

```sql
geoToH3(lon, lat, resolution)
```

**Входные значения**

- `lon` — географическая долгота. Тип данных — [Float64](../../data_types/float.md).
- `lat` — географическая широта. Тип данных — [Float64](../../data_types/float.md).
- `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../data_types/int_uint.md). Диапазон возможных значений — `[0, 15]`.

**Возвращаемые значения**

- Порядковый номер шестиугольника.
- 0 в случае ошибки.

Тип — [UInt64](../../data_types/int_uint.md).

**Пример**

```sql
SELECT geoToH3(37.79506683, 55.71290588, 15) as h3Index
```
```text
┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘
```

[Оригинальная статья](https://clickhouse.yandex/docs/ru/query_language/functions/geo/) <!--hide-->