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

Обработка результатов поиска

Вы можете обрабатывать результаты поиска:

Сортировка результатов​

С помощью параметра sort вы можете сортировать результаты поиска по удалённости от пользователя и другим параметрам. По умолчанию результаты сортируются по убыванию релевантности. Полный список параметров сортировки см. в справочнике API.

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

  • q — текстовый запрос с адресом, например «Москва, Садовая улица».
  • sort — параметр сортировки, например sort=name для сортировки по названию объекта.

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

https://catalog.api.2gis.com/3.0/items/geocode?q=Москва, Садовая улица&sort=name&key=API_KEY

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

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260806"
    },
    "result": {
        "items": [
            {
                "full_name": "Московский, 1-я Садовая улица",
                "id": "70030077102596595",
                "name": "1-я Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Николо-Хованское, 1-я Садовая улица",
                "id": "70030076625195996",
                "name": "1-я Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Столбово, 1-я Садовая улица",
                "id": "70030076415177293",
                "name": "1-я Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Соколово, 1-я Садовая улица",
                "id": "70030076324808258",
                "name": "1-я Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Рассудово, 1-я Садовая улица",
                "id": "70030076200659822",
                "name": "1-я Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Москва, 1-я Садовая улица",
                "id": "70030076161647419",
                "name": "1-я Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Москва, 10-я Садовая улица",
                "id": "70030076161655120",
                "name": "10-я Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Москва, 11-я Садовая улица",
                "id": "70030076161655145",
                "name": "11-я Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Москва, 12-я Садовая улица",
                "id": "70030076161655176",
                "name": "12-я Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Москва, 13-я Садовая улица",
                "id": "70030076161655198",
                "name": "13-я Садовая улица",
                "type": "street"
            }
        ],
        "total": 115
    }
}

Получение результатов по страницам​

В ответе на запрос к API результаты поиска выводятся постранично. По умолчанию каждая страница содержит 20 результатов для основного ключа в подписке и 10 результатов для демо-ключа.

По умолчанию выводится первая страница. С помощью параметра page вы можете получить определённую страницу результатов поиска.

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

  • q — текстовый запрос с адресом, например «Москва, Садовая улица».
  • page — номер страницы с результатами, например page=5 для получения пятой страницы. Если вы используете демо-ключ для доступа к API, максимальное значение — 5.

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

https://catalog.api.2gis.com/3.0/items/geocode?q=Москва, Садовая улица&page=5&key=API_KEY

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

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260806"
    },
    "result": {
        "items": [
            {
                "full_name": "Марушкино, Садовая улица",
                "id": "4504338361771242",
                "name": "Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Грибки, Садовая улица",
                "id": "70030076126415853",
                "name": "Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Марушкино, Садовая улица",
                "id": "70030076198234378",
                "name": "Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Тарычево, Садовая улица",
                "id": "70030076449591834",
                "name": "Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Городище, Садовая линия",
                "id": "4504338361759638",
                "name": "Садовая линия",
                "type": "street"
            },
            {
                "full_name": "Зименки, Садовая улица",
                "id": "4504338361762982",
                "name": "Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Крекшино, Садовая улица",
                "id": "4504338361770181",
                "name": "Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Зеленоград, Садовая улица",
                "id": "4504338361776459",
                "name": "Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Зименки, Садовая улица",
                "id": "70030076184149318",
                "name": "Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Киевский, Садовая улица",
                "id": "70030076196182140",
                "name": "Садовая улица",
                "type": "street"
            }
        ],
        "total": 115
    }
}

Ограничение количества результатов на странице​

В ответе на запрос к API результаты поиска выводятся постранично. По умолчанию каждая страница содержит 20 результатов для основного ключа в подписке и 10 результатов для демо-ключа.

С помощью параметра page_size вы можете изменить количество результатов на странице — от 1 до 50. Например, вы можете:

  • сократить количество результатов при поиске на карте, чтобы показать ближайшие места без перегрузки интерфейса;
  • увеличить количество результатов, чтобы отправить меньшее количество запросов.

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

  • q — текстовый запрос с адресом, например «Москва, Садовая улица».
  • page_size — количество результатов на странице, например page_size=3 для получения трёх результатов на странице. Если вы используете демо-ключ для доступа к API, максимальное значение — 10.

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

https://catalog.api.2gis.com/3.0/items/geocode?q=Москва, Садовая улица&page_size=3&key=API_KEY

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

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260806"
    },
    "result": {
        "items": [
            {
                "full_name": "Москва, Большая Садовая улица",
                "id": "4504338361749631",
                "name": "Большая Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Москва, Садовая улица",
                "id": "4504338361806057",
                "name": "Садовая улица",
                "type": "street"
            },
            {
                "full_name": "Москва, Садовая улица",
                "id": "70030077106144545",
                "name": "Садовая улица",
                "type": "street"
            }
        ],
        "total": 74
    }
}