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

Ответ API геокодера доступен в следующих форматах XML, JSON и JSONP. Нужный формат ответа указывается параметром format в запросе. Информация в ответе не зависит от выбранного формата.

  1. Содержимое ответа
  2. Ответ в формате XML
  3. Ответ в формате JSON
  4. Ответ в формате JSONP

Содержимое ответа

Ключевые элементы
  • Элемент GeocoderResponseMetaData содержит информацию о запросе и количество найденных результатов.
  • Элемент GeocoderMetaData содержит текст запроса, тип найденного объекта, точность соответствия результата запросу и адрес объекта.
  • Элемент Address содержит компонентный адрес. Компоненты адреса организованы в иерархическом порядке. В ответе может быть насколько ответов в одинаковым типом (kind).
  • Элемент Point содержит координаты центра объекта.
  • Элемент boundedBy содержит границы области, внутри которой объект рекомендуется показать на карте. Для большинства объектов область показа задается прямоугольником, описанным вокруг объекта.
Порядок результатов
  • При прямом геокодировании (определение координат по адресу и/или названию) результаты упорядочиваются по степени схожести с адресом или названием, указанном в запросе.
  • При обратном геокодировании (определение адреса по координатам) результаты упорядочиваются по величине геометрической области, к которой относится объект, в обратном порядке (дом, улица, район, город, и т. д.).
Порядок координат

В ответе геокодера координаты возвращаются в последовательности «долгота широта». Этот порядок не зависит от формата координат в запросе.

Пространства имен
  • Корневой элемент расположен в пространстве имён ymaps. Кроме этого, в нём же располагаются элементы ymaps:GeoObjectCollection и ymaps:GeoObject.
  • Элементы с метаданными (GeocoderResponseMetaData, GeocoderMetaData) и все вложенные в них элементы, кроме AddressDetails расположены собственном пространстве имен геокодера yg.
  • Адрес находится элементе Address, расположенном в пространстве имен a.
  • Также в ответе используются стандартные элементы GML: gml:featureMember, gml:metaDataProperty, gml:Point и gml:boundedBy.

Подробнее о пространствах имен можно узнать на странице Используемые пространства имен.

Ответ в формате XML

По умолчанию, геокодер возвращает ответ в формате XML. Ниже приведен ответ на запрос с адресом здания московского кинотеатра Октябрь на Новом Арбате:

https://geocode-maps.yandex.ru/1.x/?apikey=<Ваш API-ключ>&geocode=Москва, улица Новый Арбат, дом 24
Ответ:
<ymaps xmlns="http://maps.yandex.ru/ymaps/1.x" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="     http://maps.yandex.ru/business/1.x http://maps.yandex.ru/schemas/business/1.x/business.xsd     http://maps.yandex.ru/geocoder/1.x http://maps.yandex.ru/schemas/geocoder/1.x/geocoder.xsd     http://maps.yandex.ru/psearch/1.x http://maps.yandex.ru/schemas/psearch/1.x/psearch.xsd     http://maps.yandex.ru/search/1.x http://maps.yandex.ru/schemas/search/1.x/search.xsd     http://maps.yandex.ru/web/1.x http://maps.yandex.ru/schemas/web/1.x/web.xsd     http://maps.yandex.ru/search/internal/1.x http://maps.yandex.ru/schemas/search/internal/1.x/internal.xsd">
  <GeoObjectCollection>
    <metaDataProperty xmlns="http://www.opengis.net/gml">
      <GeocoderResponseMetaData xmlns="http://maps.yandex.ru/geocoder/1.x">
        <request>Москва, улица Новый Арбат, дом 24</request>
        <found>1</found>
        <results>10</results>
      </GeocoderResponseMetaData>
    </metaDataProperty>
    <featureMember xmlns="http://www.opengis.net/gml">
      <GeoObject xmlns="http://maps.yandex.ru/ymaps/1.x" xmlns:gml="http://www.opengis.net/gml" gml:id="1">
        <metaDataProperty xmlns="http://www.opengis.net/gml">
          <GeocoderMetaData xmlns="http://maps.yandex.ru/geocoder/1.x">
            <kind>house</kind>
            <text>Россия, Москва, улица Новый Арбат, 24</text>
            <precision>exact</precision>
            <Address xmlns="http://maps.yandex.ru/address/1.x">
              <country_code>RU</country_code>
              <postal_code>119019</postal_code>
              <formatted>Москва, улица Новый Арбат, 24</formatted>
              <Component>
                <kind>country</kind>
                <name>Россия</name>
              </Component>
              <Component>
                <kind>province</kind>
                <name>Центральный федеральный округ</name>
              </Component>
              <Component>
                <kind>province</kind>
                <name>Москва</name>
              </Component>
              <Component>
                <kind>locality</kind>
                <name>Москва</name>
              </Component>
              <Component>
                <kind>street</kind>
                <name>улица Новый Арбат</name>
              </Component>
              <Component>
                <kind>house</kind>
                <name>24</name>
              </Component>
            </Address>
            <AddressDetails xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">
              <Country>
                <AddressLine>Москва, улица Новый Арбат, 24</AddressLine>
                <CountryNameCode>RU</CountryNameCode>
                <CountryName>Россия</CountryName>
                <AdministrativeArea>
                  <AdministrativeAreaName>Москва</AdministrativeAreaName>
                  <Locality>
                    <LocalityName>Москва</LocalityName>
                    <Thoroughfare>
                      <ThoroughfareName>улица Новый Арбат</ThoroughfareName>
                      <Premise>
                        <PremiseNumber>24</PremiseNumber>
                        <PostalCode>
                          <PostalCodeNumber>119019</PostalCodeNumber>
                        </PostalCode>
                      </Premise>
                    </Thoroughfare>
                  </Locality>
                </AdministrativeArea>
              </Country>
            </AddressDetails>
          </GeocoderMetaData>
        </metaDataProperty>
        <description xmlns="http://www.opengis.net/gml">Москва, Россия</description>
        <name xmlns="http://www.opengis.net/gml">улица Новый Арбат, 24</name>
        <boundedBy xmlns="http://www.opengis.net/gml">
          <Envelope>
            <lowerCorner>37.583508 55.750768</lowerCorner>
            <upperCorner>37.591719 55.755398</upperCorner>
          </Envelope>
        </boundedBy>
        <Point xmlns="http://www.opengis.net/gml">
          <pos>37.587614 55.753083</pos>
        </Point>
      </GeoObject>
    </featureMember>
  </GeoObjectCollection>
</ymaps>

Ответ геокодера представляет собой документ в формате YMapsML, удовлетворяющий XML-схеме http://maps.yandex.ru/geocoder/1.x.

Ответ в формате JSON

Чтобы получить ответ в формате JSON, необходимо присвоить параметру format значение json:

https://geocode-maps.yandex.ru/1.x/?format=json&apikey=<Ваш API-ключ>&geocode=Москва, улица Новый Арбат, дом 24

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

Ответ:
{
  "response": {
    "GeoObjectCollection": {
      "metaDataProperty": {
        "GeocoderResponseMetaData": {
          "request": "Москва, улица Новый Арбат, дом 24",
          "found": "1",
          "results": "10"
        }
      },
      "featureMember": [
        {
          "GeoObject": {
            "metaDataProperty": {
              "GeocoderMetaData": {
                "kind": "house",
                "text": "Россия, Москва, улица Новый Арбат, 24",
                "precision": "exact",
                "Address": {
                  "country_code": "RU",
                  "postal_code": "119019",
                  "formatted": "Москва, улица Новый Арбат, 24",
                  "Components": [
                    {
                      "kind": "country",
                      "name": "Россия"
                    },
                    {
                      "kind": "province",
                      "name": "Центральный федеральный округ"
                    },
                    {
                      "kind": "province",
                      "name": "Москва"
                    },
                    {
                      "kind": "locality",
                      "name": "Москва"
                    },
                    {
                      "kind": "street",
                      "name": "улица Новый Арбат"
                    },
                    {
                      "kind": "house",
                      "name": "24"
                    }
                  ]
                },
                "AddressDetails": {
                  "Country": {
                    "AddressLine": "Москва, улица Новый Арбат, 24",
                    "CountryNameCode": "RU",
                    "CountryName": "Россия",
                    "AdministrativeArea": {
                      "AdministrativeAreaName": "Москва",
                      "Locality": {
                        "LocalityName": "Москва",
                        "Thoroughfare": {
                          "ThoroughfareName": "улица Новый Арбат",
                          "Premise": {
                            "PremiseNumber": "24",
                            "PostalCode": {
                              "PostalCodeNumber": "119019"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "description": "Москва, Россия",
            "name": "улица Новый Арбат, 24",
            "boundedBy": {
              "Envelope": {
                "lowerCorner": "37.583508 55.750768",
                "upperCorner": "37.591719 55.755398"
              }
            },
            "Point": {
              "pos": "37.587614 55.753083"
            }
          }
        }
      ]
    }
  }
}
Примечание. Элемент AddressDetails является устаревшим. Вместо него используется элемент Address. Он отображает полный адрес объекта в иерархическом порядке (страна, область, город, район, улица, дом, корпус).

Ответ в формате JSONP

Чтобы получить ответ в формате JSONP, необходимо задать параметру format значение json, и параметру callback название функции, которая будет обрабатывать результаты. При использовании JSONP результат возвращается в качестве параметра функции с указанным именем.

Рассмотрим запрос из примера выше, но с добавленным параметром callback:
https://geocode-maps.yandex.ru/1.x/?format=json&callback=my_function&geocode=Москва, улица Новый Арбат, дом 24

В ответе будет JSON-объект из предыдущего примера, но в виде аргумента функции my_function:

my_function({
  "response": {
    "GeoObjectCollection": {
      "metaDataProperty": {
        "GeocoderResponseMetaData": {
          "request": "Москва, улица Новый Арбат, дом 24",
          "found": "1",
          "results": "10"

    ...

});