Формат ответа

Поиск топонимов

Пример запроса:

https://search-maps.yandex.ru/v1/?text=Dubai Marina&type=geo&lang=en_US&apikey=YOUR_API_KEY

В этом случае ответ будет выглядеть следующим образом (для обратного геокодирования формат ответа совпадает):

Ответ

{
  "type": "FeatureCollection",
  "properties": {
    "ResponseMetaData": {
      "SearchRequest": {
        "request": "Dubai Marina",
        "results": 10,
        "skip": 0,
        "boundedBy": [
          [
            53.426262,
            23.532086
          ],
          [
            56.114166,
            25.763073
          ]
        ]
      },
      "SearchResponse": {
        "found": 10,
        "Point": {
          "type": "Point",
          "coordinates": [
            54.702308,
            24.478121
          ]
        },
        "boundedBy": [
          [
            55.117113,
            25.064766
          ],
          [
            55.155328,
            25.104558
          ]
        ],
        "display": "single"
      }
    }
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "GeocoderMetaData": {
          "kind": "locality",
          "text": "United Arab Emirates, Dubai, Jumeira, Dubai Marina",
          "precision": "other"
        },
        "description": "Jumeira, Dubai, United Arab Emirates",
        "name": "Dubai Marina",
        "boundedBy": [
          [
            55.107187,
            25.047779
          ],
          [
            55.173069,
            25.107781
          ]
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          55.13667,
          25.080549
        ]
      }
    }
  ]
}

Важно

Мы гарантируем поддержку только тех полей, которые описаны в примере. Остальные поля, которые содержатся в ответе, но не описаны в документации, использовать не рекомендуется. В будущем поддержка таких полей не гарантируется.

Параметры ответа

type *

Всегда имеет значение FeatureCollection. Таким образом обеспечивается соответствие (частичное) с форматом GeoJSON.

properties *

Контейнер метаданных, описывающих запрос и ответ.

ResponseMetaData *

Метаданные, описывающие запрос и ответ.

SearchRequest *

Метаданные, описывающие запрос.

request *

Строка запроса.

results

Максимальное количество возвращаемых результатов.

skip

Количество пропускаемых результатов.

boundedBy

Границы области, в которой предположительно находятся искомые объекты.

Задается в виде координат левого верхнего и правого нижнего углов области. Координаты указываются в последовательности «широта, долгота».

Границы области определяются сервисом автоматически.

SearchResponse *

Метаданные, описывающие ответ.

found *

Количество найденных объектов.

Point *

Данный элемент используется для обеспечения соответствия с форматом GeoJSON.

type *: Тип геометрии.
coordinates *: Координаты объекта.

boundedBy

Границы области показа найденных объектов. Содержит координаты левого нижнего и правого верхнего углов области. Координаты указаны в последовательности «долгота, широта».

display

Рекомендации по отображению результатов поиска. Возможные значения:

single — рекомендуется отображать первый найденный объект;
multiple — рекомендуется отображать все найденные объекты.

features *

Контейнер результатов поиска.

type *

Всегда имеет значение Feature. Таким образом обеспечивается соответствие (частичное) с форматом GeoJSON.

properties *

Метаданные, описывающие найденный объект.

GeocoderMetaData *

Подробная информация о найденном объекте.

kind *

Вид топонима. Список возможных значений:

house — дом;
street — улица;
metro — станция метро;
district — район города;
locality — населенный пункт (город/поселок/деревня/село/...).

text *

Полный адрес объекта.

precision *

Точность соответствия между номером найденного дома и номером дома из запроса (см. подробнее).

description

Текст, который рекомендуется указывать в качестве подзаголовка при отображении найденного объекта.

name

Текст, который рекомендуется указывать в качестве заголовка при отображении найденного объекта.

boundedBy

Границы области, в которую входит организация. Содержит координаты левого нижнего и правого верхнего углов области. Координаты указаны в последовательности «долгота, широта».

uri

Идентификатор найденного объекта.

geometry *

Описание геометрии найденного объекта.

type *

Тип геометрии.

coordinates *: Координаты объекта.

Поиск организаций

API возвращает список организаций, наиболее подходящих запросу. Например, по запросу «pharmacy Dubai» в списке результатов отобразятся не все аптеки города, а наиболее подходящие запросу с точки зрения API.

Пример запроса:

https://search-maps.yandex.ru/v1/?text=Dubai,The Museum of The Future&type=biz&lang=en_US&results=1&apikey=YOUR_API_KEY

В этом случае ответ будет выглядеть следующим образом:

Ответ

{
  "type": "FeatureCollection",
  "properties": {
    "ResponseMetaData": {
      "SearchRequest": {
        "request": "Dubai,The Museum of The Future",
        "results": 1,
        "skip": 0,
        "boundedBy": [
          [
            53.426262,
            23.532086
          ],
          [
            56.114166,
            25.763073
          ]
        ]
      },
      "SearchResponse": {
        "found": 1,
        "display": "multiple"
      }
    }
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Museum of The Future",
        "description": "Trade Center Second, Dubai",
        "boundedBy": [
          [
            55.270869,
            25.201209
          ],
          [
            55.292509,
            25.229877
          ]
        ],
        "uri": "ymapsbm1://org?oid=171100494916",
        "CompanyMetaData": {
          "id": "171100494916",
          "name": "Museum of The Future",
          "address": "Trade Center Second, Dubai",
          "Address": {
            "country_code": "AE",
            "formatted": "Trade Center Second, Dubai",
            "postal_code": "",
            "additional_info": "",
            "Components": [
              {
                "kind": "country",
                "name": "United Arab Emirates"
              },
              {
                "kind": "province",
                "name": "Dubai"
              },
              {
                "kind": "area",
                "name": "Sector 3"
              },
              {
                "kind": "district",
                "name": "Trade Center Second"
              },
              {
                "kind": "district",
                "name": "Trade Center Second"
              }
            ]
          },
          "url": "http://museumofthefuture.ae/",
          "Categories": [
            {
              "class": "museum",
              "name": "Museum"
            },
            {
              "class": "landmark",
              "name": "Landmark, attraction"
            }
          ],
          "Hours": {
            "Availabilities": [
              {
                "Everyday": true,
                "Intervals": [
                  {
                    "from": "10:00:00",
                    "to": "21:30:00"
                  }
                ]
              }
            ],
            "text": "daily, 10:00 AM–9:30 PM"
          }
        }
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          55.282062,
          25.219302
        ]
      }
    }
  ]
}

Важно

Параметры ответа

type *

Всегда имеет значение FeatureCollection. Таким образом обеспечивается соответствие (частичное) с форматом GeoJSON.

properties

Контейнер метаданных, описывающих запрос и ответ.

ResponseMetaData *

Метаданные, описывающие запрос и ответ.

SearchRequest *

Метаданные, описывающие запрос.

request *

Строка запроса.

results

Максимальное количество возвращаемых результатов.

skip

Количество пропускаемых результатов.

boundedBy

Границы области, в которой предположительно находятся искомые объекты. Границы задаются в виде координат левого верхнего и правого нижнего углов области. Координаты указаны в последовательности «долгота, широта».

Границы области определяются сервисом автоматически.

SearchResponse *

Метаданные, описывающие ответ. Обязательное поле

found *

Количество найденных объектов.

boundedBy

display

Рекомендации по отображению результатов поиска. Возможные значения:

«single» — рекомендуется отображать первый найденный объект;
«multiple» — рекомендуется отображать все найденные объекты.

features *

Контейнер результатов поиска.

type *

Всегда имеет значение Feature. Таким образом обеспечивается соответствие (частичное) с форматом GeoJSON.

properties *

Информация о найденном объекте.

CompanyMetaData

Содержит сведения об отдельной организации: адрес, контактную информацию, режим работы, вид деятельности и др.

id *

Идентификатор организации.

name *

Название организации.

address

Адрес организации.

Address

Объект адреса.

formatted *: Полный адрес объекта.
country_code: Код страны в формате ISO 3166-1.
postal_code: Почтовый индекс.
Components: Разбитый на компоненты адрес организации. Компоненты представлены парой значений kind и name и организованы по убыванию, от самого крупного к самому маленькому (например, от страны к дому).
additional_info: Дополнительная информация об адресе.
indoor_level_id: Идентификатор этажа.

url

Сайт организации.

Categories

Список категорий, в которые входит организация (например, салон красоты, отель или магазин).

class: Класс категории.
name *: Название категории.

Phones

Список телефонных номеров организации и другая контактная информация.

type: Тип контактной информации (например, телефон или факс).
formatted *: Полный номер телефона (или факса) с кодом страны и кодом города.

Hours

Режим работы организации.

Availabilities

Описание режима. Может содержать поля:

Weekdays | Weekend | Everyday | Sunday | Monday... — рабочие дни;
TwentyFourHours | Intervals — часы работы.

Everyday: Организация работает каждый день.
TwentyFourHours: Организация работает круглосуточно.

text *

Описание режима работы в виде произвольного текста.

Features

Особенности организации (например, доступность для людей с ограниченными возможностями).

id *

Идентификатор особенности. Список возможных значений:

parking_disabled — парковка для людей с инвалидностью;
wheelchair_access — доступность входа на инвалидной коляске;
automatic_door — автоматическая дверь
toilet_for_disabled — туалет для людей с инвалидностью;
call_button — кнопка вызова персонала;
elevator_wheelchair_accessible - лифт;
ramp - пандус;
wheelchair_accessible_vocabulary - доступность помещения на инвалидной коляске;
facilities for disabled people - удобства для людей с ограниченными возможностями;
rooms_for_people_with_limited_mobility - номера для маломобильных групп населения;

value *

Указывает, имеется ли данная особенность в организации.

type *

Формат значения value (например, enum | text | bool).

name

Название особенности.

description

Текст, который рекомендуется указывать в качестве подзаголовка при отображении найденной организации.

name

Текст, который рекомендуется указывать в качестве заголовка при отображении найденной организации.

geometry *

Описание геометрии найденного объекта.

type *

Тип геометрии.

coordinates *

Координаты организации в последовательности «долгота, широта».

Сообщения об ошибках

Code	Description
`400`	В запросе отсутствует обязательный параметр или указано неверное значение параметра. Сообщение содержит дополнительную информацию об ошибке.
`403`	В запросе указан неверный `apikey`.
`429`	Слишком много запросов за короткое время.

Если при обработке запроса происходит ошибка, API возвращает сообщение с описанием ошибки в поле message.

Примеры:

{"statusCode": 400, "error": "Bad Request", "message": "Parameter \"text\": \"text\" is not allowed to be empty"}

{"statusCode": 400, "error": "Bad Request", "message": "\"Request\" must contain at least one of [text, uri]"}

{"statusCode": 400, "error": "Bad Request", "message": "Missing apikey"}

{"statusCode": 403, "error": "Forbidden", "message": "Invalid apikey"}

Формат ответа

Поиск топонимовПоиск топонимов

Параметры ответаПараметры ответа

Поиск организацийПоиск организаций

Параметры ответаПараметры ответа

Сообщения об ошибкахСообщения об ошибках

Поиск топонимов

Параметры ответа

Поиск организаций

Параметры ответа

Сообщения об ошибках