Places API
Places API выполняет поиск организаций, зданий и мест.
Поиск может осуществляться:
- по названию компании («ИП Голубёв»);
- по сфере деятельности («рестораны» или «магазины музыкальных инструментов»);
- с геокритерием («цветы у Бауманской»);
- с атрибутами услуг и товаров («кафе с итальянской кухней» или «русская баня на дровах с бассейном»);
- по телефону и сайту («667-02-99» или «grabli.ru»);
- по ИНН («5405276278»);
- по торговой лицензии;
- без указания текстового запроса (в здании, в категории, в городе, поиск всех филиалов одной компании).
Запросы осуществляются методом GET, все необходимые параметры передаются в строке запроса. Ответы формируются в формате JSON.
Формат запроса
В данном разделе приведён пример запроса
https://catalog.api.2gis.com/3.0/items?q=кафе&sort_point=37.630866,55.752256&key=YOUR_KEY
В запросе используются следующие параметры:
q=кафе
— поиск выполняется по запросу «кафе»;sort_point=37.630866,55.752256
— координаты точки, поблизости которой выполняется поиск кафе;key=YOUR_KEY
— ваш ключ API.
Фильтрация результата поиска по типу объекта
Параметр type
используется в запросе для фильтрации объектов по типу. Поиск будет выполняться только среди объектов указанного в запросе типа.
Наиболее используемый список признаков, по которым возможна фильтрация:
- по местоположению — например, в определённом районе, городе, в заданной области;
- по типу данных в ответе — например, когда нужны только компании или только здания;
- по категории — например, только кафе или только продуктовые магазины;
- по организации — можно получить список всех филиалов одной организации;
- по времени работы — например, только круглосуточно работающие филиалы;
- по наличию или отсутствию данных — например, фотографий, отзывов, рейтинга, сайта, ИНН.
Полный список фильтров и соответствующие им параметры можно изучить на странице описания API.
Дополнительная информация об объекте
Параметр fields
используется для получения дополнительной информации об объекте.
Сортировка результата поиска
Подключить сортировку результата поиска можно с помощью параметра sort
в запросе.
Результат поиска сортируется по удалённости от местоположения пользователя, рейтингу объекта и другим параметрам. Виды сортировки определены в описании API.
Поиск в области на карте
Объекты можно искать в области на карте. Данный вид поиска позволяет получить релевантные результаты. Варианты поиска в области на карте:
- геокритерий в текстовом запросе — запрос «Москва кафе»;
- точка, относительно которой выполняется поиск;
- поиск в радиусе;
- поиск в прямоугольной области;
- поиск в произвольной области;
- поиск в городе.
Для поиска объектов в области на карте в запросе передаются координаты точек, в границах которых будут найдены объекты, или идентификатор города, в котором будет выполняться поиск объектов. С подробным описанием полей можно ознакомиться на странице описания API, c примерами использования геоограчений — на соответствующей странице.
Поиск информации об организации
Организацию можно найти по ИНН, номеру телефона, адресу сайта и торговой лицензии. Такой поиск не учитывает местоположение пользователя. Результатом поиска является список организаций. Полное описание всех методов и параметров для поиска можно изучить на странице описания API.
Формат ответа на запрос
Ответ на запрос возвращается в формате JSON:
{
"meta": {
"api_version": "3.0.448950",
"code": 200,
"issue_date": "20200626"
},
"result": {
"items": [
{
"address_comment": "3, 5 этаж",
"address_name": "Никольская, 25",
"id": "70000001031668425",
"name": "МСК, сеть лаундж-баров",
"type": "branch"
}
],
"total": 5926
}
}
Параметры ответа на запрос
В ответе на запрос по умолчанию передаются параметры:
id
— идентификатор объекта;name
— название объекта;type
— тип объекта. Типы объектов определены в описании API.
Дополнительную информацию об объекте можно передать в параметре fields
.
Возможно получение дополнительной информации:
- точка, к которой привязан объект;
- адрес или местоположение объекта и его привязка к административно-территориальным единицам;
- информация о геометрии объекта, визуальный центр геометрии;
- информация о родительской организации, к которой относятся все филиалы компании;
- расписание работы;
- контактная информация;
- связанные с компанией или местом объекты — точки входа, ближайшие остановки и парковки, обслуживающие организации, подъезды в здании и другие;
- подробная информация о парковках — вместимость, стоимость, тип доступа, количество уровней;
- подробная информация о здании — этажность, материал здания.
Перечень дополнительной информации определён в описании API.
Формирование результата поиска
Параметр search_type
отвечает за формирование результата поиска. Ниже описаны самые используемые алгоритмы формирования результата. С полным списком алгоритмов можно ознакомиться в описании API.
Поиск с раскрытием
Поиск, при котором категории и организации будут раскрыты до компаний (филиалов организации). Например, при поиске «почта России» в ответе будут все почтовые отделения. Аналогично работает раскрытие категории — при поиске «кафе» в результате будут компании в категории «Кафе / Кондитерские», а не сама категория, которая также является объектом справочника.
Этот алгоритм формирования результата используется по умолчанию и соответствует переданному в запрос параметру search_type=discovery
.
Поиск с единственным филиалом одной организации в результате
Аналогичен поиску с раскрытием, но для каждой организации в результат выводится только один филиал. Например, пользователь хочет найти интернет-магазин и посмотреть его сайт, и ему не нужны все пункты выдачи, которые будут в результате.
Для изменения алгоритма формирования результата нужно передать в запрос search_type=one_branch
.
Поиск в здании
Подходит для поиска организаций в здании, например, в бизнес-центре или торгово-развлекательном центре. Также можно использовать для автодополнения при поиске в здании.
Для изменения алгоритма формирования результата нужно передать в запрос search_type=indoor
и указать id здания в параметре building_id
.
Как начать работать с API
- Получите ключ. Для этого заполните анкету.
- Изучите формат запроса и формат ответа.