Handling search results

You can handle search results:

sort them by parameters
obtain a particular page of search results
limit the number of results per page

Sorting results

Using the sort parameter, you can sort search results: by distance from the user, object rating, and other parameters. By default, results are sorted by relevance in descending order. For the full list of sorting parameters, see the API Reference.

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

q - text query with georestriction, for example "cafe pyatnitskaya street moscow". You can specify georestriction in another way: for more information, see the Search georestriction instruction.
sort - sorting parameter, for example sort=name to sort by object name.

Request example:

https://catalog.api.2gis.com/3.0/items?q=cafe pyatnitskaya street moscow&sort=name&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": "Серпуховская площадь, 36/71",
                "id": "70000001104901511",
                "name": "Cazaban bistro&bakery",
                "type": "branch"
            },
            {
                "address_comment": "2 этаж",
                "address_name": "Большой Овчинниковский переулок, 16",
                "id": "70000001105596086",
                "name": "Cheese&macaroni",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Пятницкая улица, 11/23 ст1",
                "id": "70000001066052537",
                "name": "Chiho, китайская закусочная",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Пятницкая улица, 2",
                "id": "70000001078904355",
                "name": "Cider, кафе-бар",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Садовническая улица, 8",
                "id": "70000001038242964",
                "name": "Coffee inn, кафе",
                "type": "branch"
            },
            {
                "address_name": "Большая Серпуховская улица, 8/7 ст2",
                "id": "70000001066136730",
                "name": "Curry, ресторан индийской кухни",
                "type": "branch"
            },
            {
                "address_comment": "2 этаж",
                "address_name": "Большой Овчинниковский переулок, 16",
                "id": "70000001103931318",
                "name": "Golden monkey, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Малая Ордынка, 19",
                "id": "70000001066325543",
                "name": "Holi yoga&cafe, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Пятницкая улица, 6/1 ст1",
                "id": "70000001084006818",
                "name": "J`pan, японское кафе",
                "type": "branch"
            },
            {
                "address_name": "Новокузнецкая улица, 1 ст2",
                "id": "70000001089184727",
                "name": "Joja coffee, кафе",
                "type": "branch"
            }
        ],
        "total": 79
    }
}

Obtaining results by pages

In response to an API request, search results are displayed paginated. By default, each page contains 20 results for the production key in a subscription and 10 results for the demo key.

By default, the first page is displayed. Using the page parameter, you can obtain a particular page of search results. The page parameter can be specified for the following endpoints:

To obtain a particular page of search results, send a GET request to /3.0/items with the following parameters:

q - text query with georestriction, for example "cafe pyatnitskaya street moscow". You can specify georestriction in another way: for more information, see the Search georestriction instruction.
page - page number with results, for example page=5 to obtain the fifth page. If you use a demo key to access the API, the maximum value is 5.

Request example:

https://catalog.api.2gis.com/3.0/items?q=cafe pyatnitskaya street moscow&page=5&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": "Садовническая улица, 8",
                "id": "70000001038242964",
                "name": "Coffee inn, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Пятницкая улица, 82/34 ст1",
                "id": "70000001019207730",
                "name": "Питчер паб",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Новокузнецкая улица, 13 ст1",
                "id": "70000001059349913",
                "name": "Шербет, ресторан",
                "type": "branch"
            },
            {
                "address_comment": "1-2 этаж",
                "address_name": "Климентовский переулок, 10 ст2",
                "id": "70000001083732657",
                "name": "Реберная №1, гриль-бар",
                "type": "branch"
            },
            {
                "address_name": "2-й Новокузнецкий переулок, 14 ст1",
                "id": "70000001095304138",
                "name": "Архив, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Малая Ордынка, 19",
                "id": "70000001066325543",
                "name": "Holi yoga&cafe, кафе",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Пятницкая улица, 6/1 ст1",
                "id": "70000001026501242",
                "name": "Есть хинкали&пить вино, ресторан",
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Пятницкая улица, 82/34 ст1",
                "id": "70000001030989592",
                "name": "Рамен-клаб, раменная",
                "type": "branch"
            },
            {
                "address_comment": "цокольный этаж",
                "address_name": "Средний Овчинниковский переулок, 3",
                "id": "70000001047508784",
                "name": "Буду поздно, бар",
                "type": "branch"
            },
            {
                "full_name": "Москва, Кафе, бар",
                "id": "70000001102399315",
                "name": "Ускюдар Донер",
                "purpose_name": "Кафе, бар",
                "type": "branch"
            }
        ],
        "total": 79
    }
}

Limiting the number of results per page

In response to an API request, search results are displayed paginated. By default, each page contains 20 results for the production key in a subscription and 10 results for the demo key.

Using the page_size parameter, you can change the number of results per page, from 1 to 50. For example, you can:

reduce the number of search results on the map to show nearby places without cluttering the interface
increase the number of results to get more results in a single search

The page_size parameter can be specified for the following endpoints:

To limit the number of search results per page, send a GET request to /3.0/items with the following parameters:

q - text query with georestriction, for example "cafe pyatnitskaya street moscow". You can specify georestriction in another way: for more information, see the Search georestriction instruction.
page_size - number of results per page, for example page_size=3 to obtain three results per page. If you use a demo key to access the API, the maximum value is 10.

Request example:

https://catalog.api.2gis.com/3.0/items?q=cafe pyatnitskaya street moscow&page_size=3&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": "Пятницкая улица, 3/4 ст1",
                "id": "70000001059479230",
                "name": "Хачапури и вино, кафе грузинской кухни",
                "type": "branch"
            },
            {
                "address_comment": "-1, 1 этаж",
                "address_name": "Пятницкая улица, 54 ст2",
                "id": "70000001048389948",
                "name": "Nicepricecafe, кафе",
                "type": "branch"
            },
            {
                "address_comment": "3 этаж",
                "address_name": "Пятницкая улица, 29",
                "id": "70000001089085648",
                "name": "True Cost, рестобар",
                "type": "branch"
            }
        ],
        "total": 79
    }
}

Sorting results​

Obtaining results by pages​

Limiting the number of results per page​

Sorting results

Obtaining results by pages

Limiting the number of results per page