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 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 valueskind
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 valuesprecision
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 valueskind
andname
and are organized in descending order from the largest to the smallest (for example, from country to house).
Warning
The
AddressDetails
field is obsolete. TheAddress
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"
}