Skip to main content

Search settings

You can manage the behavior of the search engine and the logic for generating results:

Search type​

Using the search_type parameter, you can specify the search engine type: the algorithm and settings optimized for the search goal, as well as the logic for generating results.

By default, search with an expansion is used (search_type=discovery). In search results, categories and organizations are expanded to organization branches. For example, when you search for "Russian Post", the response contains all post offices. Category expansion works similarly: when you search for "cafe", the result contains organizations in the "Cafe / Pastry shops" category, not the category itself, which is also a directory object.

You can use other search types, for example, search with one branch or indoor search. For the full list of search types, see the API Reference.

Search with one organization branch​

Search with one organization branch in search results is similar to search with an expansion, but only one branch is returned for each organization in the results.

To use search with one branch, send a GET request to /3.0/items with the following parameters:

  • q - text query, for example "cafe".
  • location - search point coordinates in the longitude,latitude format, for example location=37.630866,55.752256. You can specify georestriction in another way: for more information, see the Search georestriction instruction.
  • search_type=one_branch - search with one branch.

Request example:

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

Response example:

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
    }
}

Indoor search​

Indoor search is suitable for searching for organizations inside a building, for example, in a business center or shopping mall. You can also use this type to autocomplete when searching inside the building.

To use indoor search, send a GET request to /3.0/items with the following parameters:

  • q - text query, for example "cafe".
  • search_type=indoor - indoor search.
  • building_id - building ID, for example building_id=4504235299048514. You can use multiple IDs separated by commas, for example building_id=4504235299048514,4504235282736775. For more information on obtaining an ID, see the Building ID section.

Request example:

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

Response example:

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 near the user​

Using the search_nearby parameter, you can enable the search mode near the user, which increases the importance of the distance from the user when ranking results. The search engine considers the user's location and returns objects that are closer to them.

To use search near the user, send a GET request to /3.0/items with the following parameters:

  • q - text query, for example "cafe".
  • point - user coordinates in the longitude,latitude format, for example point=37.630866,55.752256.
  • search_nearby=true - search near the user.

Request example:

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

Response example:

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 area​

Using the search_territory_of_interest parameter, you can specify the preferred search area for objects. Objects inside the area will be ranked higher in the results, while objects outside it will be ranked lower but will not be excluded. This differentiates the parameter from georestriction as an arbitrary area, which completely excludes objects outside the specified polygon.

To specify the search area, send a GET request to /3.0/items with the following parameters:

  • q - text query, for example "cafe".
  • search_territory_of_interest - search area in WKT format.

Request example:

https://catalog.api.2gis.com/3.0/items?q=cafe&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 example:

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
    }
}

Query input method​

Using the search_input_method parameter, you can specify the query input method, so the search engine can consider text input specifics. For example, if the user enters a query by voice, the search engine will account for possible speech recognition errors.

To specify the query input method, send a GET request to /3.0/items with the following parameters:

  • q - text query, for example "cafn" (with a typo).
  • location - search point coordinates in the longitude,latitude format, for example location=37.630866,55.752256. You can specify georestriction in another way: for more information, see the Search georestriction instruction.
  • search_input_method - query text input method, for example search_input_method=hardware_qwerty_keyboard for hardware keyboard input. For the full list of methods, see the API Reference.

Request example:

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

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "address_comment": "1 этаж",
                "address_name": "улица Покровка, 19",
                "id": "70000001052145044",
                "name": "Caffe Mandy`s, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Чистопрудный бульвар, 12 ст6",
                "id": "70000001088096113",
                "name": "Osteria by Mandy`s, ресторан",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Кузнецкий Мост, 19 ст1",
                "id": "70000001022846789",
                "name": "Mandy`s Apothecary, бар",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Уланский переулок, 19",
                "id": "70000001067673245",
                "name": "Can, парикмахерская",
                "type": "branch"
            },
            {
                "address_comment": "2 этаж",
                "address_name": "улица Покровка, 16",
                "id": "70000001080740075",
                "name": "StandUp Cafe, стендап-клуб",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Мясницкая улица, 47",
                "id": "70000001063185335",
                "name": "Nicepricecafe, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 линия; 1 этаж",
                "address_name": "Красная площадь, 3",
                "id": "70000001031085325",
                "name": "Bosco Cafe, ресторан",
                "type": "branch"
            },
            {
                "address_comment": "3 линия; 2 этаж",
                "address_name": "Красная площадь, 3",
                "id": "4504127913464453",
                "name": "Marc Cain, бутик премиальной женской одежды",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Петровка, 12 ст1",
                "id": "70000001082567555",
                "name": "Miss you cafe, кафе",
                "type": "branch"
            },
            {
                "address_comment": "-1, 1 этаж",
                "address_name": "Пятницкая улица, 54 ст2",
                "id": "70000001048389948",
                "name": "Nicepricecafe, кафе",
                "type": "branch"
            }
        ],
        "total": 37
    }
}

Input completion check​

Using the search_is_query_text_complete=true parameter, you can enable the completion check of query input to indicate to the search engine that the query is complete (the user pressed the submit button). In this case, search by prefix will be disabled: for example, a search for "bank" will not return banking services.

To enable the input completion check, send a GET request to /3.0/items with the following parameters:

  • q - text query, for example "bank".
  • location - search point coordinates in the longitude,latitude format, for example location=37.630866,55.752256. You can specify georestriction in another way: for more information, see the Search georestriction instruction.
  • search_is_query_text_complete=true - indication that the query is complete.

Request example:

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

Response example:

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
    }
}