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

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

https://geocode-maps.yandex.ru/v1/?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"
    }
  }
}

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

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

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

Если при обработке запроса происходит ошибка, 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": 400,
    "error": "Bad Request",
    "message": "Missing apikey"
}

{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Invalid apikey"
}