The geocoder response

The geocoder response can be returned in the following formats:

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

Both formats have the same structure, and the results returned are identical. For XML output, the results are shown as XML elements. For JSON, key:value pairs are used, contained in curly brackets, and groups using arrays are in square brackets. The name of the XML element is the same as the matching key in the JSON output.

If forward geocoding was performed (the coordinates were determined using the address and/or name), the results are sorted according to their similarity to the address or name that was specified in the request, and not by their geographical proximity to the first object found.

For reverse geocoding (the address was determined from the coordinates), results are sorted according to the size of the geometric area that the object belongs to, in reverse order (house number, street, district, city, and so on).

Note. If the daily request limit is exceeded, the service returns the status 429 instead of the geocoding results.

The response in XML format

By default, the geocoder response is returned in XML format. Let's look at the XML response from the service for a request with the address of the Sultanahmet Camii building 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">
  <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.976on>
</ymaps>

The geocoder response consists of a document in YMapsML format, which 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, while the GeocoderMetaData element contains the text of the request, the type of object found, information on how accurately the result matches the request, and a detailed mailing address of the object.

The Point element contains the coordinates of the center of the object, while the boundedBy element contains the boundary within which it is recommended to display the object on the map (a viewport). For most objects, the viewport is a rectangle around the object.

The response in JSON format

To get a response in JSON format, it is necessary to add the format parameter with 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 that the data is being returned to is passed the name of a function, and the results are returned as a JSON object, but as a parameter of the function with the specified name.

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

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

the JSON object from the previous example will be returned, but as an argument of the function my_function:

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

    ...

});