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

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

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

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": 10,
        "skip": 0,
        "boundedBy": [
          [
            53.426262,
            23.532086
          ],
          [
            56.114166,
            25.763073
          ]
        ]
      },
      "SearchResponse": {
        "found": 1,
        "boundedBy": [
          [
            55.270869,
            25.201209
          ],
          [
            55.292509,
            25.229877
          ]
        ],
        "display": "multiple"
      }
    }
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "CompanyMetaData": {
          "id": "171100494916",
          "name": "The Museum of The Future",
          "address": "Dubai, Zaabeel, Trade Center Second",
          "url": "http://museumofthefuture.ae/",
          "Categories": [
            {
              "class": "museum",
              "name": "Museum"
            }
          ],
          "Hours": {
            "Availabilities": [
              {
                "Everyday": true,
                "Intervals": [
                  {
                    "from":"10:00:00",
                    "to":"19:30:00"
                  }
                ]
              }
            ],
            "text": "daily, 10:00 AM–7:30 PM"
          }
        },
        "description": "Dubai, Zaabeel, Trade Center Second",
        "name": "The Museum of The Future"
      },
      "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

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

url

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

Categories

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

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

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

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

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

Availabilities

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

  • Weekdays | Weekend | Everyday | Sunday | Monday... — рабочие дни;
  • TwentyFourHours | Intervals — часы работы.
Everyday
Организация работает каждый день.
TwentyFourHours
Организация работает круглосуточно.
text *

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

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": 403, "error": "Forbidden", "message": "Invalid key"}

{"statusCode": 403, "error": "Forbidden", "message": "Key is required"}
Предыдущая
Формат запроса
Следующая
Примеры
В этой статье: