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": {
    "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 paramsResponse 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 responseCoordinates 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 resultsOrder 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 messagesError messages

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

Error codes

Error message example:

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