Перейти к основному содержимому

Настройки поиска

Вы можете управлять поведением поискового движка и логикой формирования результатов:

Тип поиска​

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

По умолчанию используется поиск с раскрытием (search_type=discovery). В результатах поиска категории и организации раскрываются до филиалов организации. Например, при поиске «почта России» в ответе будут все почтовые отделения. Аналогично работает раскрытие категории: при поиске «кафе» в результате будут организации в категории «Кафе / Кондитерские», а не сама категория, которая также является объектом справочника.

Вы можете использовать другие типы поиска, например, поиск с единственным филиалом или поиск внутри здания. Полный список типов поиска см. в справочнике API.

Поиск с единственным филиалом организации​

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

Чтобы использовать поиск с единственным филиалом, отправьте GET-запрос на /3.0/items со следующими параметрами:

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

https://catalog.api.2gis.com/3.0/items?q=кафе&location=37.630866,55.752256&search_type=one_branch&key=API_KEY

Пример ответа:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Варварка, 6 ст3",
                "id": "70000001029535674",
                "name": "Зарядье, гастрономический центр",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1/2",
                "id": "70000001032763462",
                "name": "The Black Swan Pub",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1/2 ст1",
                "id": "70000001093401978",
                "name": "Senti Menti",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Славянская площадь, 2/5",
                "id": "4504128908449647",
                "name": "True Cost, прожектор",
                "type": "branch"
            },
            {
                "address_comment": "цокольный этаж",
                "address_name": "Славянская площадь, 2/5/4 ст3",
                "id": "70000001007260074",
                "name": "Либерти, ночной клуб",
                "type": "branch"
            },
            {
                "address_comment": "цокольный этаж",
                "address_name": "Лубянский проезд, 25 ст1",
                "id": "4504127908781677",
                "name": "Китайский Лётчик Джао Да, кафе-клуб",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Новая площадь, 14",
                "id": "70000001109804763",
                "name": "Rusty Rat&Pizza",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1/2",
                "id": "70000001047225231",
                "name": "Хачапури и вино, кафе грузинской кухни",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1/2 ст1",
                "id": "70000001082439498",
                "name": "Chang, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1",
                "id": "70000001032240412",
                "name": "22 сантиметра, пиццерия",
                "type": "branch"
            }
        ],
        "total": 929
    }
}

Поиск внутри здания​

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

Чтобы использовать поиск внутри здания, отправьте GET-запрос на /3.0/items со следующими параметрами:

  • q — текстовый запрос, например «кафе».
  • search_type=indoor — поиск внутри здания.
  • building_id — ID здания, например building_id=4504235299048514. Можно использовать несколько ID, разделённых запятыми, например building_id=4504235299048514,4504235282736775. Подробнее о получении ID см. в разделе ID здания.

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

https://catalog.api.2gis.com/3.0/items?q=кафе&search_type=indoor&building_id=4504235299048514&key=API_KEY

Пример ответа:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "address_comment": "3 этаж",
                "address_name": "Кадашёвская набережная, 12",
                "id": "70000001114871525",
                "name": "Видовое кафе",
                "type": "branch"
            }
        ],
        "total": 1
    }
}

Поиск рядом с пользователем​

С помощью параметра search_nearby вы можете использовать режим поиска рядом с пользователем, чтобы повысить значимость расстояния от пользователя при ранжировании результатов. Поисковый движок учитывает местоположение пользователя и возвращает объекты, которые находятся ближе к нему.

Чтобы использовать поиск рядом с пользователем, отправьте GET-запрос на /3.0/items со следующими параметрами:

  • q — текстовый запрос, например «кафе».
  • point — координаты пользователя в формате долгота,широта, например point=37.630866,55.752256.
  • search_nearby=true — поиск рядом с пользователем.

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

https://catalog.api.2gis.com/3.0/items?q=кафе&point=37.630866,55.752256&search_nearby=true&key=API_KEY

Пример ответа:

response.json
{
    "meta": {
        "api_version": "3.0.20949",
        "code": 200,
        "issue_date": "20260715"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Варварка, 6 ст3",
                "id": "70000001029535674",
                "name": "Зарядье, гастрономический центр",
                "type": "branch"
            },
            {
                "address_name": "улица Варварка, 6 ст3",
                "id": "70000001082399693",
                "name": "Ешь и гуляй, кафе",
                "type": "branch"
            }
        ],
        "total": 2
    }
}

Область поиска​

С помощью параметра search_territory_of_interest вы можете указать предпочтительную область поиска объектов. Объекты внутри области будут ранжироваться в результатах выше, а объекты за её пределами — ниже, но не будут исключены. Этим параметр отличается от геоограничения в виде произвольной области, которое полностью исключает объекты за пределами заданного полигона.

Чтобы задать область поиска, отправьте GET-запрос на /3.0/items со следующими параметрами:

  • q — текстовый запрос, например «кафе».
  • search_territory_of_interest — область поиска в формате WKT.

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

https://catalog.api.2gis.com/3.0/items?q=кафе&search_territory_of_interest=MULTIPOLYGON (((37.6146002 55.761322, 37.6175267 55.7628083, 37.6184916 55.7615712, 37.6152171 55.7605209, 37.6146002 55.761322)))&key=API_KEY

Пример ответа:

response.json
{
    "meta": {
        "api_version": "3.0.20949",
        "code": 200,
        "issue_date": "20260715"
    },
    "result": {
        "items": [
            {
                "address_comment": "1 этаж",
                "address_name": "улица Большая Дмитровка, 10/2 ст4",
                "id": "70000001094146856",
                "name": "J`pan, японское кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Большая Дмитровка, 7/5 ст5",
                "id": "4504128908372099",
                "name": "Moloko, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Большая Дмитровка, 12/1",
                "id": "70000001100859771",
                "name": "Хачапури и вино, кафе грузинской кухни",
                "type": "branch"
            }
        ],
        "total": 3
    }
}

Способ ввода запроса​

С помощью параметра search_input_method вы можете указать способ ввода запроса, чтобы поисковый движок учитывал особенности ввода текста. Например, если пользователь вводит запрос голосом, поисковый движок будет учитывать возможные ошибки распознавания речи.

Чтобы указать способ ввода запроса, отправьте GET-запрос на /3.0/items со следующими параметрами:

  • q — текстовый запрос, например «кафн» (с опечаткой).
  • location — координаты точки поиска в формате долгота,широта, например location=37.630866,55.752256. Вы можете указать геоограничение другим способом: подробнее см. в инструкции Геоограничение поиска.
  • search_input_method — способ ввода текста запроса, например search_input_method=hardware_qwerty_keyboard для ввода с аппаратной клавиатуры. Полный список способов см. в справочнике API.

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

https://catalog.api.2gis.com/3.0/items?q=кафн&location=37.630866,55.752256&search_input_method=hardware_qwerty_keyboard&key=API_KEY

Пример ответа:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Варварка, 6 ст3",
                "id": "70000001029535674",
                "name": "Зарядье, гастрономический центр",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1/2",
                "id": "70000001032763462",
                "name": "The Black Swan Pub",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1/2 ст1",
                "id": "70000001093401978",
                "name": "Senti Menti",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Славянская площадь, 2/5",
                "id": "4504128908449647",
                "name": "True Cost, прожектор",
                "type": "branch"
            },
            {
                "address_comment": "цокольный этаж",
                "address_name": "Славянская площадь, 2/5/4 ст3",
                "id": "70000001007260074",
                "name": "Либерти, ночной клуб",
                "type": "branch"
            },
            {
                "address_comment": "цокольный этаж",
                "address_name": "Лубянский проезд, 25 ст1",
                "id": "4504127908781677",
                "name": "Китайский Лётчик Джао Да, кафе-клуб",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Новая площадь, 14",
                "id": "70000001109804763",
                "name": "Rusty Rat&Pizza",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1/2",
                "id": "70000001047225231",
                "name": "Хачапури и вино, кафе грузинской кухни",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1/2 ст1",
                "id": "70000001082439498",
                "name": "Chang, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 1",
                "id": "70000001032240412",
                "name": "22 сантиметра, пиццерия",
                "type": "branch"
            }
        ],
        "total": 1282
    }
}

Проверка завершения ввода​

С помощью параметра search_is_query_text_complete=true вы можете включить проверку завершения ввода запроса и указать поисковому движку, что запрос является законченным (пользователь нажал на кнопку завершения ввода). В этом случае будет отключен поиск по префиксу: например, по запросу «банк» не будет выполняться поиск банкоматов.

Чтобы включить проверку завершения ввода, отправьте GET-запрос на /3.0/items со следующими параметрами:

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

https://catalog.api.2gis.com/3.0/items?q=банк&location=37.630866,55.752256&search_is_query_text_complete=true&key=API_KEY

Пример ответа:

response.json
{
    "meta": {
        "api_version": "3.0.20949",
        "code": 200,
        "issue_date": "20260716"
    },
    "result": {
        "items": [
            {
                "address_comment": "1 этаж",
                "address_name": "Лубянский проезд, 17",
                "id": "4504127908693076",
                "name": "СберБанк",
                "type": "branch"
            },
            {
                "address_comment": "3 линия; 3 этаж",
                "address_name": "Красная площадь, 3",
                "id": "4504128908805846",
                "name": "Банк ВТБ, дополнительный офис ГУМ",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Китайгородский проезд, 5",
                "id": "4504127908681639",
                "name": "Банк ПСБ, дополнительный офис",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Китайгородский проезд, 5",
                "id": "70000001052401193",
                "name": "Банк ПСБ",
                "type": "branch"
            },
            {
                "address_comment": "2 этаж",
                "address_name": "Славянская площадь, 2/5/4 ст3",
                "id": "70000001020301597",
                "name": "Металлинвестбанк, дополнительный офис Китай-город",
                "type": "branch"
            },
            {
                "address_name": "улица Балчуг, 7",
                "id": "70000001089652821",
                "name": "Банк ПСБ",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Лубянский проезд, 19 ст1",
                "id": "70000001044579870",
                "name": "СДМ-Банк",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Лубянский проезд, 11/1 ст1",
                "id": "70000001006336654",
                "name": "Чайна констракшн банк",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 13/3 ст1",
                "id": "70000001033374547",
                "name": "Банк Зенит, банк",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Солянка, 3 ст3",
                "id": "4504127911584290",
                "name": "Энерготрансбанк, коммерческий банк",
                "type": "branch"
            }
        ],
        "total": 797
    }
}