Response format

https://geocode-maps.yandex.ru/1.x/?apikey=YOUR_API_KEY&geocode=Moscow, Novy Arbat Street, 24&lang=en_US&format=json

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

Response
{
  "response": {
    "GeoObjectCollection": {
      "metaDataProperty": {
        "GeocoderResponseMetaData": {
          "request": "Moscow, Novy Arbat Street, 24",
          "found": "1",
          "results": "10"
        }
      },
      "featureMember": [
        {
          "GeoObject": {
            "metaDataProperty": {
              "GeocoderMetaData": {
                "kind": "house",
                "text": "Russia, Moscow, Novy Arbat Street, 24",
                "precision": "exact",
                "Address": {
                  "country_code": "RU",
                  "postal_code": "119019",
                  "formatted": "Moscow, Novy Arbat Street, 24",
                  "Components": [
                    {
                      "kind": "country",
                      "name": "Russia"
                    },
                    {
                      "kind": "province",
                      "name": "Central Federal District"
                    },
                    {
                      "kind": "province",
                      "name": "Moscow"
                    },
                    {
                      "kind": "locality",
                      "name": "Moscow"
                    },
                    {
                      "kind": "street",
                      "name": "Novy Arbat Street"
                    },
                    {
                      "kind": "house",
                      "name": "24"
                    }
                  ]
                },
                "AddressDetails": {
                  "Country": {
                    "AddressLine": "Moscow, Novy Arbat Street, 24",
                    "CountryNameCode": "RU",
                    "CountryName": "Russia",
                    "AdministrativeArea": {
                      "AdministrativeAreaName": "Moscow",
                      "Locality": {
                        "LocalityName": "Moscow",
                        "Thoroughfare": {
                          "ThoroughfareName": "Novy Arbat Street",
                          "Premise": {
                            "PremiseNumber": "24",
                            "PostalCode": {
                              "PostalCodeNumber": "119019"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "description": "Moscow, Russia",
            "name": "Novy Arbat Street, 24",
            "boundedBy": {
              "Envelope": {
                "lowerCorner": "37.583508 55.750768",
                "upperCorner": "37.591719 55.755398"
              }
            },
            "Point": {
              "pos": "37.587614 55.753083"
            }
          }
        }
      ]
    }
  }
}

Response params

response

Geocoder's response.

GeoObjectCollection

Main collection of geo objects.

metaDataProperty

Metadata of the collection of geo objects.

GeocoderResponseMetaData

Information about the request and the number of toponyms found. Inside this object there can be fields:

  • fix – a character corrected by the spelling service.
  • request – requested address.
  • suggest – variant of response corrected by the correction service.
  • found – number of toponyms found.
  • results – number of requested search results.
  • skip – shows how many results to skip in the service response (from the beginning of the list).
featureMember

List of geo objects.

GeoObject

The geo object collection.

metaDataProperty

Geo object metadata.

GeocoderMetaData
Detailed information about the toponym found. There can be fields inside:
  • kind – type of toponym found.

    Possible values

    kind

    The type of toponym found

    The text value (an example)

    house

    a detached house

    house: Türkiye, İstanbul, Kartal, Esentepe, Aydos Sokak, 32

    street

    street

    Türkiye, İstanbul, Kartal, Esentepe, Aydos Sokak

    metro

    subway station

    Türkiye, İstanbul, Metro Fuar Merkezi

    district

    city district

    Türkiye, İstanbul, Kadıköy, Bostancı Mh

    locality

    locality: city, town, village, etc.

    Türkiye, Antalya, Antalya

    area

    regional district (oblast)

    Türkiye, İstanbul, Şişli

    province

    oblast, region

    Türkiye, İstanbul, Şişli

    country

    country

    Türkiye

    hydro

    river, lake, stream, reservoir, etc.

    Türkiye, Istanbul, Ömerli Barajı

    vegetation

    forest, park, orchard, etc.

    Türkiye, Istanbul, Saip Molla Özel Ormanı

    airport

    airport

    United States, Norfolk, Airport-Norfolk International

    other

    other

    Istanbul, Pendik, Havaalanı Iç Yolları

  • precision – house match precision in request and response.

    Possible values

    precision

    The house number in the request

    The house number in the response

    Comment

    exact

    27, unit 1

    27c1

    A found building has the specified house number.

    number

    31, building 4

    31/2

    A found building has the specified house number, but a different building or unit number.

    near

    16/3

    18

    A found building has a house number close to the requested address.

    range

    12

    12

    Found approximate coordinates of the requested building.

    street

    18

    Only the street was found.

    other

    22

    The street name does not match, but a village, district, etc. matches.

  • text – full address of the object in one line of text.

  • Address – information about the found object. There can be fields inside:

    • country_code — country code in the format ISO 3166-1.
    • formatted — the address of a toponym in one line.
    • Components — the address of a toponym divided into components. The components are represented by a pair of values kind and name and are organized in descending order from the largest to the smallest (for example, from country to house).

    Warning

    The AddressDetails field is obsolete. The Address field is used instead. It displays the complete address of the object in hierarchical order (country, region, city, district, street, house, building).

name

The text that is recommended to be specified as a title when displaying the found object.

description

The text that is recommended to be specified as a subtitle when displaying the found object.

boundedBy

The boundaries of the area in which the company belongs. Contains the coordinates of the lower left and upper right corners of the area. The coordinates are listed in the sequence "longitude, latitude".

uri

ID of the found object.

Point.pos

Coordinates of the geo object.

Coordinates of the request in the geocoder's response

The geocoder returns the given coordinates in the metaDataProperty.GeocoderResponseMetaData.Point.pos field. Coordinates are displayed in the format "[longitude] [latitude]":

 {
  GeocoderResponseMetaData:
  {
    "request": "E134.854,S25.828",
    "found": "1",
    "results": "10",
    "Point":
      {
        "pos": "134.854412 -25.828084",
      }
  }
 }

Order of results

  • For direct geocoding (the coordinates are determined using the address and/or name), the results are sorted according to their similarity to the address or name specified in the request.
  • For reverse geocoding (the address is determined from the coordinates), the 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).

Error messages

If an error occurs while processing a request, the geocoder returns a message with the error description in the message field.

Error codes

Code Description
400 (Bad Request) The request contains an invalid parameter or value. Details are provided in the message.
403 (Forbidden) The request uses an invalid API key. Makes sure you're using a valid API key. You can check if the key is valid in the Developer's Dashboard.

Error message example:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Parameter \"geocode\": \"geocode\" is required"
}
Previous