Формат ответа
Пример запроса:
https://geocode-maps.yandex.ru/1.x/?apikey=YOUR_API_KEY&geocode=Дубай, бульвар Мухаммед Бин Рашид, дом 1&format=json
В этом случае ответ геокодера будет выглядеть следующим образом:
{
"response": {
"GeoObjectCollection": {
"metaDataProperty": {
"GeocoderResponseMetaData": {
"request": "Дубай, бульвар Мухаммед Бин Рашид, дом 1",
"found": "1",
"results": "10"
}
},
"featureMember": [
{
"GeoObject": {
"metaDataProperty": {
"GeocoderMetaData": {
"kind": "house",
"text": "ОАЭ, Дубай, бульвар Мухаммед Бин Рашид, дом 1",
"precision": "exact",
"Address": {
"country_code": "UAE",
"postal_code": "00000",
"formatted": "Дубай, бульвар Мухаммед Бин Рашид, 1",
"Components": [
{
"kind": "country",
"name": "ОАЭ"
},
{
"kind": "province",
"name": "эмират Дубай"
},
{
"kind": "province",
"name": "Дубай"
},
{
"kind": "locality",
"name": "Дубай"
},
{
"kind": "street",
"name": "бульвар Мухаммед Бин Рашид"
},
{
"kind": "house",
"name": "1"
}
]
},
"AddressDetails": {
"Country": {
"AddressLine": "Дубай, бульвар Мухаммед Бин Рашид, 1",
"CountryNameCode": "UAE",
"CountryName": "Дубай",
"AdministrativeArea": {
"AdministrativeAreaName": "Дубай",
"Locality": {
"LocalityName": "Дубай",
"Thoroughfare": {
"ThoroughfareName": "бульвар Мухаммед Бин Рашид",
"Premise": {
"PremiseNumber": "1",
"PostalCode": {
"PostalCodeNumber": "00000"
}
}
}
}
}
}
}
}
},
"description": "ОАЭ, Дубай",
"name": "бульвар Мухаммед Бин Рашид, 1",
"boundedBy": {
"Envelope": {
"lowerCorner": "25.196563 55.274149",
"upperCorner": "25.197612 55.274183"
}
},
"Point": {
"pos": "25.197300 55.274243"
}
}
}
]
}
}
}
Параметры ответа
response
-
Ответ геокодера.
GeoObjectCollection
-
Корневая коллекция геообъектов.
metaDataProperty
-
Метаданные коллекции геообъектов.
GeocoderResponseMetaData
-
Информация о запросе и количестве найденных топонимов. Внутри могут быть поля:
fix
– символ, исправленный сервисом исправления опечаток.request
– запрошенный адрес.suggest
– вариант запроса, исправленный сервисом исправления опечаток.found
– количество найденных топонимов.results
– количество затребованных результатов поиска.skip
– указывает сколько требуется пропустить результатов в ответе сервиса (от начала списка).
featureMember
-
Список геообъектов.
GeoObject
-
Геообъект коллекции. Внутри могут быть поля:
metaDataProperty
-
Метаданные геообъекта.
GeocoderMetaData
-
Подробная информация о найденном топониме. Внутри могут быть поля:
-
kind
– вид найденного объекта.Возможные значенияkind
Вид найденного топонима
Текстовое значение (пример)
house
отдельный дом
ОАЭ, Дубай, бульвар Мухаммед Бин Рашид, 1
street
улица
ОАЭ, Дубай, бульвар Мухаммед Бин Рашид
metro
станция метро
ОАЭ, Дубай, Красная линия, метро Машрек
district
район города
ОАЭ, Дубай, Бур-Дубай
locality
населённый пункт: город / поселок / деревня / село и т. п.
ОАЭ, Дубай
area
район области
ОАЭ, Абу-Даби, Аль-Айн
province
область
ОАЭ, Абу-Даби
country
страна
Великобритания
region
устаревший тип, не используется
hydro
река / озеро / ручей / водохранилище и т. п.
ОАЭ, Аль-Кудра
railway_station
ж.д. станция
ОАЭ, вокзал Дубай
station
станции, не относящиеся к железной дороге. Например, канатные станции.
ОАЭ, Дубай, Рас-эль-Хайм
route
линия метро / шоссе / ж.д. линия
ОАЭ, Дубай, Красная линия
vegetation
лес / парк / сад и т. п.
ОАЭ, Дубай, Miracle Garden
airport
аэропорт
ОАЭ, Дубай, Аль-Мактум
entrance
подъезд / вход
ОАЭ, Дубай, бульвар Мухаммед Бин Рашид, 1, 5
other
прочее
ОАЭ, Дубай, остров Палм-Джумейра
-
precision
– точность соответствия дома в запросе и результате;Возможные значенияprecision
№ дома в запросе
№ дома в ответе
Комментарий
exact
27 строение 1
27с1
Найден дом с указанным номером дома.
number
31 корпус 4
31к2
Найден дом с указанным номером, но с другим номером строения или корпуса.
near
16/3
18
Найден дом с номером, близким к запрошенному.
range
12
12
Найдены приблизительные координаты запрашиваемого дома.
street
18
–
Найдена только улица.
other
22
–
Не найдена улица, но найден, например, посёлок, район и т. п.
-
text
– полный адрес объекта одной строкой текста. -
Address
– информация о найденном объекте. Внутри могут быть поля:country_code
— код страны в формате ISO 3166-1.formatted
— адрес топонима в одной строкеComponents
— разбитый на компоненты адрес топонима. Компоненты представлены парой значенийkind
иname
и организованы по убыванию, от самого крупного к самому маленькому (например, от страны к дому).
Важно
Поле
AddressDetails
является устаревшим. Вместо него используется полеAddress
. Оно отображает полный адрес объекта в иерархическом порядке (страна, область, город, район, улица, дом, корпус).
-
name
-
Текст, который рекомендуется указывать в качестве заголовка при отображении найденного объекта.
description
-
Текст, который рекомендуется указывать в качестве подзаголовка при отображении найденного объекта.
boundedBy
-
Границы области, в которую входит организация. Содержит координаты левого нижнего и правого верхнего углов области. Координаты указаны в последовательности «долгота, широта».
uri
-
ID найденного объекта.
Point.pos
-
Координаты геообъекта.
Координаты запроса в ответе
Геокодер возвращает заданные координаты в поле metaDataProperty.GeocoderResponseMetaData.Point.pos
. Координаты указаны в формате «[долгота] [широта]». Этот порядок не зависит от формата координат в запросе:
{
"GeocoderResponseMetaData": {
"request": "E134.854,S25.828",
"found": "1",
"results": "10",
"Point": {
"pos": "134.854412 -25.828084"
}
}
}
Порядок результатов
- При прямом геокодировании результаты упорядочиваются по степени схожести с адресом или названием, указанном в запросе.
- При обратном геокодировании результаты упорядочиваются по величине геометрической области, к которой относится объект, в обратном порядке (дом, улица, район, город, и т. д.).
Сообщения об ошибках
Code | Description |
---|---|
400 |
В запросе отсутствует обязательный параметр или указано неверное значение параметра. Сообщение содержит дополнительную информацию об ошибке. |
403 |
Запрос не содержит параметр apikey или указан неверный ключ. |
429 |
Слишком много запросов за короткое время. |
Если при обработке запроса происходит ошибка, API возвращает сообщение с описанием ошибки в поле message
.
Примеры:
{
"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"
}