API Яндекс.Карт. Геокодирование: Ответ геокодера

Ответ геокодера может быть возвращен в следующих форматах:

XML;
JSON (может быть возвращен в качестве аргумента функции — JSONP).

Оба формата имеют одинаковую структуру, а возвращаемые результаты абсолютно одинаковы. В случае XML-выдачи результаты представлены в виде XML-элементов. При использовании JSON используются пары «ключ»:«значение», заключенные в фигурные скобки, и группировка с помощью массивов — квадратные скобки. Название XML-элемента совпадает с соответствующем ключом в JSON-выдаче.

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

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

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

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

http://geocode-maps.yandex.ru/1.x/?geocode=Москва, улица Новый Арбат, дом 24&key=API-ключ

Ответ:

<?xml version="1.0" encoding="utf-8"?>
<ymaps xmlns="http://maps.yandex.ru/ymaps/1.x" xmlns:x="http://www.yandex.ru/xscript">
  <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">
        <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>
            <AddressDetails xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">
              <Country>
                <CountryNameCode>RU</CountryNameCode>
                <CountryName>Россия</CountryName>
                <Locality>
                  <LocalityName>Москва</LocalityName>
                  <Thoroughfare>
                    <ThoroughfareName>улица Новый Арбат</ThoroughfareName>
                    <Premise>
                      <PremiseNumber>24</PremiseNumber>
                    </Premise>
                  </Thoroughfare>
                </Locality>
              </Country>
            </AddressDetails>
          </GeocoderMetaData>
        </metaDataProperty>
        <name xmlns="http://www.opengis.net/gml">новый арбат, 24</name>
        <boundedBy xmlns="http://www.opengis.net/gml">
          <Envelope>
            <lowerCorner>37.583490 55.750778</lowerCorner>
            <upperCorner>37.591701 55.755409</upperCorner>
          </Envelope>
        </boundedBy>
        <Point xmlns="http://www.opengis.net/gml">
          <pos>37.587596 55.753093</pos>
        </Point>
      </GeoObject>
    </featureMember>
  </GeoObjectCollection>
</ymaps>

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

В элементе GeocoderResponseMetaData содержится информация о запросе и количестве найденных результатов, а в элементе GeocoderMetaData - текст запроса, тип найденного объекта, точность соответствия результата запросу и подробный почтовый адрес объекта.

Координаты центра объекта содержатся в элементе Point, а в элементе boundedBy – границы области, внутри которой объект рекомендуется показать на карте. Для большинства объектов область показа задается прямоугольником, описанным вокруг объекта.

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

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

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

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

Ответ:

{
  "response": {
    "GeoObjectCollection": {
      "metaDataProperty": {
        "GeocoderResponseMetaData": {
          "request": "Москва, улица Новый Арбат, дом 24",
          "found": "1",
          "results": "10"
        }
      },
      "featureMember": [
        {
          "GeoObject": {
            "metaDataProperty": {
              "GeocoderMetaData": {
                "kind": "house",
                "text": "Россия, Москва, улица Новый Арбат, 24",
                "precision": "exact",
                "AddressDetails": {
                  "Country": {
                    "CountryNameCode": "RU",
                    "CountryName": "Россия",
                    "Locality": {
                      "LocalityName": "Москва",
                      "Thoroughfare": {
                        "ThoroughfareName": "улица Новый Арбат",
                        "Premise": {
                          "PremiseNumber": "24"
                        }
                      }
                    }
                  }
                }
              }
            },
            "name": "новый арбат, 24",
            "boundedBy": {
              "Envelope": {
                "lowerCorner": "37.583490 55.750778",
                "upperCorner": "37.591701 55.755409"
              }
            },
            "Point": {
              "pos": "37.587596 55.753093"
            }
          }
        }
      ]
    }
  }
}

JSONP

Политика безопасности современных браузеров не позволяет веб-страницам загружать данные со сторонних серверов. Под сторонним подразумевается сервер, доменное имя которого отличается от доменного имени сервера, на котором находится страница. Если необходимо сформировать страницу, запрашивающую результаты геокодирования, следует воспользоваться технологией JSONP.

При использовании JSONP серверу, возвращающему данные, передается имя функции, и результат возвращается в виде объекта JSON, но в качестве параметра функции с указанным именем.

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

Так, по запросу

http://geocode-maps.yandex.ru/1.x/?format=json&callback=my_function&geocode=Москва, улица Новый Арбат, дом 24&key=API-ключ

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

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

    ...

});

API Карт:

Общие сведения

JavaScript API 2.x

Static API 1.x

Поиск по карте

YMapsML 1.x

Глоссарий

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

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

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

JSONP