Response format

https://geocode-maps.yandex.ru/1.x/?apikey=YOUR_API_KEY&geocode=Dubai, Mohammed Bin Rashid Boulevard, 1&lang=en_US&format=json

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

Response
{
  "response": {
    "GeoObjectCollection": {
      "metaDataProperty": {
        "GeocoderResponseMetaData": {
          "request": "Dubai, Mohammed Bin Rashid Boulevard, 1",
          "found": "1",
          "results": "10"
        }
      },
      "featureMember": [
        {
          "GeoObject": {
            "metaDataProperty": {
              "GeocoderMetaData": {
                "kind": "house",
                "text": "UAE, Dubai, Mohammed Bin Rashid Boulevard, 1",
                "precision": "exact",
                "Address": {
                  "country_code": "UAE",
                  "postal_code": "00000",
                  "formatted": "Dubai, Mohammed Bin Rashid Boulevard, 1",
                  "Components": [
                    {
                      "kind": "country",
                      "name": "UAE"
                    },
                    {
                      "kind": "province",
                      "name": "Emirate of Dubai"
                    },
                    {
                      "kind": "province",
                      "name": "Dubai"
                    },
                    {
                      "kind": "locality",
                      "name": "Dubai"
                    },
                    {
                      "kind": "street",
                      "name": "Mohammed Bin Rashid Boulevard"
                    },
                    {
                      "kind": "house",
                      "name": "1"
                    }
                  ]
                },
                "AddressDetails": {
                  "Country": {
                    "AddressLine": "Dubai, Mohammed Bin Rashid Boulevard, 1",
                    "CountryNameCode": "UAE",
                    "CountryName": "Dubai",
                    "AdministrativeArea": {
                      "AdministrativeAreaName": "Dubai",
                      "Locality": {
                        "LocalityName": "Dubai",
                        "Thoroughfare": {
                          "ThoroughfareName": "Mohammed Bin Rashid Boulevard",
                          "Premise": {
                            "PremiseNumber": "1",
                            "PostalCode": {
                              "PostalCodeNumber": "00000"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "description": "UAE, Dubai",
            "name": "Mohammed Bin Rashid Boulevard, 1",
            "boundedBy": {
              "Envelope": {
                "lowerCorner": "25.196563 55.274149",
                "upperCorner": "25.197612 55.274183"
              }
            },
            "Point": {
              "pos": "25.197300 55.274243"
            }
          }
        }
      ]
    }
  }
}

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

    United Arab Emirates, Dubai, Mohammed Bin Rashid Boulevard, 1

    street

    street

    United Arab Emirates, Dubai, Mohammed Bin Rashid Boulevard

    metro

    subway station

    United Arab Emirates, Dubai, Rad Line, metro Mashreq

    district

    city district

    United Arab Emirates, Dubai, Bur Dubai

    locality

    locality: city, town, village, etc.

    United Arab Emirates, Dubai

    area

    regional district (oblast)

    United Arab Emirates, Abu Dhabi, Al Ain

    province

    oblast, region

    United Arab Emirates, Abu Dhabi

    country

    country

    Türkiye

    hydro

    river, lake, stream, reservoir, etc.

    United Arab Emirates, Al Qudra

    vegetation

    forest, park, orchard, etc.

    United Arab Emirates, Dubai, Miracle Garden

    airport

    airport

    United Arab Emirates, Dubai, Al Maktoum

    other

    other

    United Arab Emirates, Dubai, Palm Jumeirah Island

  • 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

Code Description
400 The request is missing a required parameter or an invalid parameter value is specified. The message contains additional information about the error.
403 The request doesn't contain the apikey parameter or an invalid key was specified.
429 There are too many requests in a short time.

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

Examples:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Parameter \"geocode\": \"geocode\" is not allowed to be empty"
}
{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "\"Request\" must contain at least one of [geocode, uri]"
}
{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Invalid key"
}
{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Key is required"
}
Previous