---
description: Изучите формат и все параметры HTTP-запросов к Geocoder API для преобразования адресов в координаты и, наоборот, городов или улиц в широту и долготу.
---
> **Documentation Index:** Fetch the complete configuration index at https://dev-geocode.docs-viewer.yandex.ru/ru/llms.txt


# Формат запроса

## Все параметры {#params}

```http
https://geocode-maps.yandex.ru/v1
  ? apikey=<string>
  & geocode=<string>
  & lang=<string>
  & [kind=<string>]
  & [rspn=<boolean>]
  & [ll=<number>,<number>]
  & [spn=<number>,<number>]
  & [bbox=<number>,<number>~<number>,<number>]
  & [results=<integer>]
  & [skip=<integer>]
  & [uri=<string>]
  & [format=<string>]
```
<!-- markdownlint-disable MD001 MD018 MD022 MD036 -->
#|
||#### apikey |
*Обязательный параметр*

Ключ, полученный в [Кабинете Разработчика](https://developer.tech.yandex.ru/).

{% include notitle [apikey](_includes/apikey.md) %}
||

||#### geocode |
*Обязательный параметр*

Адрес либо географические координаты искомого объекта. Указанные данные определяют тип геокодирования:

* Если указан адрес, то он преобразуется в координаты объекта. Этот процесс называется прямым геокодированием.
* Если указаны координаты, они преобразуются в адрес объекта. Этот процесс называется обратным геокодированием.

Доступны несколько [форматов](#coords) записи координат.
||

||#### lang |
*Обязательный параметр*

Язык ответа и региональные особенности карты.

Формат записи `lang=language_region`, где:

* `language` — двузначный код языка. Указывается в формате [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php). Задает язык, на котором будут отображаться названия географических объектов.
* `region` — двузначный код страны. Указывается в формате [ISO 3166-1](https://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm). Определяет региональные особенности.

Список поддерживаемых значений:

* `ru_RU` — русский;
* `uk_UA` — украинский;
* `be_BY` — белорусский;
* `en_RU` — ответ на английском, российские особенности карты;
* `en_US` — ответ на английском, американские особенности карты;
* `tr_TR` — турецкий (только для карты Турции).

Если в значении параметра передается локаль, не входящая в этот список, сервис подбирает язык максимально близкий к заданному.

Пример: `lang=uk_UA`.
||


||#### sco |
Только если в параметре `geocode` указаны координаты. Порядок записи координат.

Возможные значения:

* `longlat` — долгота, широта;
* `latlong` — широта, долгота.

Значение по умолчанию: `longlat`.
||


||#### kind |
Только если в параметре `geocode` указаны координаты. Вид необходимого топонима. Список допустимых значений:

* `house` — дом;
* `street` — улица;
* `metro` — станция метро;
* `district` — район города;
* `locality` — населенный пункт (город/поселок/деревня/село)

Если параметр не задан, API выберет тип топонима автоматически.
||

||#### rspn |
Флаг, задающий ограничение поиска указанной областью. Область задается параметрами `ll` и `spn` либо `bbox`. Возможные значения:

* `0` — не ограничивать поиск,
* `1` — ограничивать поиск.

Значение по умолчению: `0`.

{% note info %}

Если в параметре `geocode` указаны координаты, то параметр `rspn` игнорируется.

{% endnote %}
||

||#### ll |
Долгота и широта центра области поиска. Протяженность области поиска задается параметром `spn`.
||

||#### spn |
Протяженность области поиска. Центр области задается параметром `ll`.
Задается двумя числами:

* первое обозначает разницу между максимальной и минимальной долготой области;
* второе обозначает разницу между максимальной и минимальной широтой области.

{% note info %}

Если в параметре `geocode` указаны координаты и параметр `kind` имеет значение `district`, параметр `spn` не учитывается.

{% endnote %}
||

||#### bbox |
Альтернативный способ задания области поиска.

Границы задаются в виде географических координат (в последовательности «долгота, широта») левого нижнего и правого верхнего углов области.

Формат записи: `bbox=x1,y1~x2,y2`

{% note info %}

При одновременном использовании параметров `bbox` и `ll+spn`, параметр `bbox` будет более приоритетным.

{% endnote %}


Игнорируется, если в параметре `geocode` указаны координаты.
||


||#### format |
Формат ответа геокодера: `json`
||


||#### results |
Максимальное количество возвращаемых объектов. Если указан параметр `skip`, то значение нужно задать явно.

Значение по умолчанию: `10`.

Максимальное допустимое значение: `50`.
||

||#### skip |
Количество пропускаемых объектов в ответе, начиная с первого. Если указано, нужно также задать значение `results`. Значение `skip` должно нацело делиться на значение `results`.
Значение по умолчанию: `0`.
||

||#### uri |
Дополнительная информация об объекте. Значение параметра возвращается в ответе Геосаджеста. Чтобы использовать его в запросе укажите значение вместо текста и координат.
||
|#
<!-- markdownlint-enable MD001 MD018 MD022 MD036 -->

## Формат географических координат в параметре geocode {#coords}

Географические координаты в параметре `geocode` задаются последовательно в одном из следующих форматов:

| **Формат записи** | **Порядок следования координат** | **Пример** |
| ----- | ----- | ----- |
|+-float, +-float | Долгота, широта | 134.854, -25.828|
|float \[direction\], float \[direction\]\* | Любой | E134.854, S25.828 134.854E, 25.828S 134.854в.д, 25.828ю.ш.|
|+-deg° mm' ss", +-deg° mm' ss" | Широта, долгота | -25°49′41.1″, 134°51′15.88″|
|deg° mm' ss" \[direction\], deg° mm' ss" \[direction\]\* | Любой | 25°49′41.1″S, 134°51′15.88″E|
|NMEA | Любой | 2549.67,S, 13451.26,E|

\* \[direction\] - буквенное обозначение одного из четырех направлений: N, E, W, S, или С, В, З, Ю, или "с.ш.", "в.д.", "з.д." и "ю.ш.". Между буквами и координатами допускаются пробелы.

Разделителем может быть пробел, запятая или точка с запятой. Слева и справа от символов-разделителей допускаются пробелы.

{% note info %}

Символ ";" нужно передавать в закодированном виде "%3B".

{% endnote %}