Формат ответа

Пример запроса:

https://geocode-maps.yandex.ru/1.x/?apikey=YOUR_API_KEY&geocode=Дубай, бульвар Мухаммед Бин Рашид, дом 1&format=json

В этом случае ответ геокодера будет выглядеть следующим образом:

Ответ
{
  "response": {
    "GeoObjectCollection": {
      "metaDataProperty": {
        "GeocoderResponseMetaData": {
          "request": "Дубай, бульвар Мухаммед Бин Рашид, дом 1",
          "found": "1",
          "results": "10"
        }
      },
      "featureMember": [
        {
          "GeoObject": {
            "metaDataProperty": {
              "GeocoderMetaData": {
                "kind": "house",
                "text": "ОАЭ, Дубай, бульвар Мухаммед Бин Рашид, дом 1",
                "precision": "exact",
                "Address": {
                  "country_code": "UAE",
                  "postal_code": "00000",
                  "formatted": "Дубай, бульвар Мухаммед Бин Рашид, 1",
                  "Components": [
                    {
                      "kind": "country",
                      "name": "ОАЭ"
                    },
                    {
                      "kind": "province",
                      "name": "эмират Дубай"
                    },
                    {
                      "kind": "province",
                      "name": "Дубай"
                    },
                    {
                      "kind": "locality",
                      "name": "Дубай"
                    },
                    {
                      "kind": "street",
                      "name": "бульвар Мухаммед Бин Рашид"
                    },
                    {
                      "kind": "house",
                      "name": "1"
                    }
                  ]
                },
                "AddressDetails": {
                  "Country": {
                    "AddressLine": "Дубай, бульвар Мухаммед Бин Рашид, 1",
                    "CountryNameCode": "UAE",
                    "CountryName": "Дубай",
                    "AdministrativeArea": {
                      "AdministrativeAreaName": "Дубай",
                      "Locality": {
                        "LocalityName": "Дубай",
                        "Thoroughfare": {
                          "ThoroughfareName": "бульвар Мухаммед Бин Рашид",
                          "Premise": {
                            "PremiseNumber": "1",
                            "PostalCode": {
                              "PostalCodeNumber": "00000"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "description": "ОАЭ, Дубай",
            "name": "бульвар Мухаммед Бин Рашид, 1",
            "boundedBy": {
              "Envelope": {
                "lowerCorner": "25.196563 55.274149",
                "upperCorner": "25.197612 55.274183"
              }
            },
            "Point": {
              "pos": "25.197300 55.274243"
            }
          }
        }
      ]
    }
  }
}

Параметры ответа

response

Ответ геокодера.

GeoObjectCollection

Корневая коллекция геообъектов.

metaDataProperty

Метаданные коллекции геообъектов.

GeocoderResponseMetaData

Информация о запросе и количестве найденных топонимов. Внутри могут быть поля:

  • fix – символ, исправленный сервисом исправления опечаток.
  • request – запрошенный адрес.
  • suggest – вариант запроса, исправленный сервисом исправления опечаток.
  • found – количество найденных топонимов.
  • results – количество затребованных результатов поиска.
  • skip – указывает сколько требуется пропустить результатов в ответе сервиса (от начала списка).
featureMember

Список геообъектов.

GeoObject

Геообъект коллекции. Внутри могут быть поля:

metaDataProperty

Метаданные геообъекта.

GeocoderMetaData

Подробная информация о найденном топониме. Внутри могут быть поля:

  • kind – вид найденного объекта.

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

    kind

    Вид найденного топонима

    Текстовое значение (пример)

    house

    отдельный дом

    ОАЭ, Дубай, бульвар Мухаммед Бин Рашид, 1

    street

    улица

    ОАЭ, Дубай, бульвар Мухаммед Бин Рашид

    metro

    станция метро

    ОАЭ, Дубай, Красная линия, метро Машрек

    district

    район города

    ОАЭ, Дубай, Бур-Дубай

    locality

    населённый пункт: город / поселок / деревня / село и т. п.

    ОАЭ, Дубай

    area

    район области

    ОАЭ, Абу-Даби, Аль-Айн

    province

    область

    ОАЭ, Абу-Даби

    country

    страна

    Великобритания

    region

    устаревший тип, не используется

    hydro

    река / озеро / ручей / водохранилище и т. п.

    ОАЭ, Аль-Кудра

    railway_station

    ж.д. станция

    ОАЭ, вокзал Дубай

    station

    станции, не относящиеся к железной дороге. Например, канатные станции.

    ОАЭ, Дубай, Рас-эль-Хайм

    route

    линия метро / шоссе / ж.д. линия

    ОАЭ, Дубай, Красная линия

    vegetation

    лес / парк / сад и т. п.

    ОАЭ, Дубай, Miracle Garden

    airport

    аэропорт

    ОАЭ, Дубай, Аль-Мактум

    entrance

    подъезд / вход

    ОАЭ, Дубай, бульвар Мухаммед Бин Рашид, 1, 5

    other

    прочее

    ОАЭ, Дубай, остров Палм-Джумейра

  • precision – точность соответствия дома в запросе и результате;

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

    precision

    № дома в запросе

    № дома в ответе

    Комментарий

    exact

    27 строение 1

    27с1

    Найден дом с указанным номером дома.

    number

    31 корпус 4

    31к2

    Найден дом с указанным номером, но с другим номером строения или корпуса.

    near

    16/3

    18

    Найден дом с номером, близким к запрошенному.

    range

    12

    12

    Найдены приблизительные координаты запрашиваемого дома.

    street

    18

    Найдена только улица.

    other

    22

    Не найдена улица, но найден, например, посёлок, район и т. п.

  • text – полный адрес объекта одной строкой текста.

  • Address – информация о найденном объекте. Внутри могут быть поля:

    • country_code — код страны в формате ISO 3166-1.
    • formatted — адрес топонима в одной строке
    • Components — разбитый на компоненты адрес топонима. Компоненты представлены парой значений kind и name и организованы по убыванию, от самого крупного к самому маленькому (например, от страны к дому).

    Важно

    Поле AddressDetails является устаревшим. Вместо него используется поле Address. Оно отображает полный адрес объекта в иерархическом порядке (страна, область, город, район, улица, дом, корпус).

name

Текст, который рекомендуется указывать в качестве заголовка при отображении найденного объекта.

description

Текст, который рекомендуется указывать в качестве подзаголовка при отображении найденного объекта.

boundedBy

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

uri

ID найденного объекта.

Point.pos

Координаты геообъекта.

Координаты запроса в ответе

Геокодер возвращает заданные координаты в поле metaDataProperty.GeocoderResponseMetaData.Point.pos. Координаты указаны в формате «[долгота] [широта]». Этот порядок не зависит от формата координат в запросе:

{
  "GeocoderResponseMetaData": {
    "request": "E134.854,S25.828",
    "found": "1",
    "results": "10",
    "Point": {
      "pos": "134.854412 -25.828084"
    }
  }
}

Порядок результатов

  • При прямом геокодировании результаты упорядочиваются по степени схожести с адресом или названием, указанном в запросе.
  • При обратном геокодировании результаты упорядочиваются по величине геометрической области, к которой относится объект, в обратном порядке (дом, улица, район, город, и т. д.).

Сообщения об ошибках

Code Description
400 В запросе отсутствует обязательный параметр или указано неверное значение параметра. Сообщение содержит дополнительную информацию об ошибке.
403 Запрос не содержит параметр apikey или указан неверный ключ.
429 Слишком много запросов за короткое время.

Если при обработке запроса происходит ошибка, API возвращает сообщение с описанием ошибки в поле message.

Примеры:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Parameter \"geocode\": \"geocode\" is not allowed to be empty"
}
{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "\"Request\" must contain at least one of [geocode, uri]"
}
{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Invalid key"
}
{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Key is required"
}
Предыдущая
Следующая