Geocoder response

The geocoder response can be returned in the following formats:

  • XML
  • JSON (may be returned as a function argument — JSONP).

Both formats have the same structure, and the results returned are absolutely identical. For XML output, results are provided as XML elements. When using JSON, "key":"value" pairs are used inside curly brackets, and groups using arrays are inside square brackets. The name of the XML element matches the corresponding key in the JSON output.

If forward geocoding was performed (coordinates were detected from an address and/or name), the results are sorted by similarity with the address or name given in the request, and not by geographical proximity to the first object output.

For reverse geocoding (when the address was determined from coordinates), results are sorted by the size of the geometric region the object belongs to, in descending order (building, street, district, city, and so on).

Note. If you exceed the daily request limit, the geocoder returns the status 429 instead of the result.

XML response

The geocoder returns the response in XML format by default. Let's look at the XML response from the service for a request containing the address of the Sultanahmet Camii in Istanbul:

https://geocode-maps.yandex.ru/1.x/?geocode=Sultanahmet+Camii+İç+Yolları&lang=en-US

Response:

<?xml version="1.0" encoding="utf-8"?>
<ymaps xmlns="http://maps.yandex.ru/ymaps/1.x">
  <Attribution xmlns="http://maps.yandex.ru/attribution/1.x"/>
  <GeoObjectCollection>
    <metaDataProperty xmlns="http://www.opengis.net/gml">
      <GeocoderResponseMetaData xmlns="http://maps.yandex.ru/geocoder/1.x">
        <request xmlns:geo="http://maps.yandex.ru/geocoder/1.x">Sultanahmet Camii İç Yolları</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>street</kind>
            <text>Turkey, Istanbul, Eminönü, Sultanahmet, Sultanahmet Camii Iç Yollari</text>
            <precision>street</precision>
            <AddressDetails xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">
              <Country>
                <AddressLine xml:lang="en">Istanbul, Eminönü, Sultanahmet, Sultanahmet Camii Iç Yollari</AddressLine>
                <CountryNameCode>TR</CountryNameCode>
                <CountryName xml:lang="en">Turkey</CountryName>
                <AdministrativeArea>
                  <AdministrativeAreaName xml:lang="en">Istanbul</AdministrativeAreaName>
                  <SubAdministrativeArea>
                    <SubAdministrativeAreaName xml:lang="en">Eminönü</SubAdministrativeAreaName>
                    <Locality>
                      <LocalityName xml:lang="en">Sultanahmet</LocalityName>
                      <Thoroughfare>
                        <ThoroughfareName xml:lang="en">Sultanahmet Camii Iç Yollari</ThoroughfareName>
                      </Thoroughfare>
                    </Locality>
                  </SubAdministrativeArea>
                </AdministrativeArea>
              </Country>
            </AddressDetails>
          </GeocoderMetaData>
        </metaDataProperty>
        <description xmlns="http://www.opengis.net/gml">Turkey, Istanbul, Eminönü, Sultanahmet</description>
        <name xmlns="http://www.opengis.net/gml">Sultanahmet Camii Iç Yollari</name>
        <boundedBy xmlns="http://www.opengis.net/gml">
          <Envelope>
            <lowerCorner>28.975779 41.004937</lowerCorner>
            <upperCorner>28.977881 41.006761</upperCorner>
          </Envelope>
        </boundedBy>
        <Point xmlns="http://www.opengis.net/gml">
          <pos>28.976893 41.005808</pos>
        </Point>
      </GeoObject>
    </featureMember>
  </GeoObjectCollection>
</ymaps>

The geocoder response is a document in YMapsML format that conforms to the XML schema http://maps.yandex.ru/geocoder/1.x.

The GeocoderResponseMetaData element contains information about the request and the number of results found, and the GeocoderMetaData element contains the query text, the type of object found, how precisely the result matches the query, and the detailed mailing address of the object.

Coordinates of the center of the object are contained in the Point element, and the boundedBy element contains the boundaries of the recommended area for showing the object inside of on the map. For most objects, the viewport is set by a rectangle defined around the object.

JSON response

To get a response in JSON format, set the format parameter to the value json:

https://geocode-maps.yandex.ru/1.x/?format=json&geocode=Sultanahmet+Camii+İç+Yolları&lang=en-US

In this case, the geocoder response will look like this:

Response:

{
  "response": {
    "GeoObjectCollection":{
      "metaDataProperty": {
        "GeocoderResponseMetaData": {
          "request": "Sultanahmet Camii İç Yolları",
          "found": "1",
          "results": "10"
        }
      },
      "featureMember": [{
        "GeoObject": {
          "metaDataProperty": {
            "GeocoderMetaData": {
              "kind":"street",
              "text":"Turkey, Istanbul, Eminönü, Sultanahmet, Sultanahmet Camii Iç Yollari",
              "precision":"street",
              "AddressDetails": {
                "Country": {
                  "AddressLine": "Istanbul, Eminönü, Sultanahmet, Sultanahmet Camii Iç Yollari",
                  "CountryNameCode": "TR",
                  "CountryName": "Turkey",
                  "AdministrativeArea": {
                    "AdministrativeAreaName": "Istanbul",
                    "SubAdministrativeArea": {
                      "SubAdministrativeAreaName": "Eminönü",
                      "Locality": {
                        "LocalityName": "Sultanahmet",
                        "Thoroughfare": {
                          "ThoroughfareName": "Sultanahmet Camii Iç Yollari"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "description": "Turkey, Istanbul, Eminönü, Sultanahmet",
          "name":"Sultanahmet Camii Iç Yollari",
          "boundedBy": {
            "Envelope": {
              "lowerCorner": "28.975779 41.004937",
              "upperCorner":"28.977881 41.006761"
            }
          },
          "Point": {
            "pos":"28.976893 41.005808"
          }
        }
      }]
    }
  }
}

JSONP

The security policies of modern browsers do not allow web pages to load data from third-party servers. Third-party refers to a server whose domain name is different from the domain name of the server that the page is on. When making a page that requests geocoding results, use JSONP technology.

When using JSONP, the server returning the data is passed a function name, and the result is returned as a JSON object, but as a function parameter with the specified name.

To get search results in JSONP format, assign the callback parameter the name of the function that will process the results returned in JSON format.

So the request

https://geocode-maps.yandex.ru/1.x/?format=json&callback=my_function&geocode=Sultanahmet+Camii+İç+Yolları&lang=en-US

will return a JSON object from the previous example, but as an argument of my_function:

my_function({
  "response": {
    "GeoObjectCollection": {
      "metaDataProperty": {
        "GeocoderResponseMetaData": {
          "request": "Sultanahmet Camii İç Yolları",
          "found": "1",
          "results": "10"

    ...

});