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

Обзор

Regions API используется для выбора региона, в границах которого выполняется поиск организаций, зданий и мест.

Регион (region_id) в поисковых API — это агломерация, включающая крупный город и ближайшие населённые пункты, а также города-спутники. Это территории с повышенной детализацией карты и подробным набором данных и атрибутов справочника. Территории за границами региона (населённые пункты, область в целом, край, республика и т. д.) называются сегментами (segment_id).

Обратите внимание, что регионы и сегменты отвечают только внутреннему формату хранения данных в 2ГИС и в общем случае никак не связаны с субъектами Российской Федерации.

Для работы с местами и компаниями за границами регионов используется поиск с геоограничениями.

Расширенные возможности

Изучите также возможности других API поиска и дополните ваши сценарии работы с объектами на карте.

Начало работы​

  1. Получите ключ доступа:

    1. Зарегистрируйтесь в личном кабинете Менеджер Платформы.

    2. Создайте демо-ключ или купите подписку для доступа к API. Подробнее о стоимости сервиса см. в разделе Тарифы.

    Подробнее о работе с ключами и подписками см. в документации личного кабинета.

  2. Изучите формат запроса и формат ответа.

  3. Изучите примеры запросов к Regions API и полный справочник API.

Формат запроса​

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

https://catalog.api.2gis.com/2.0/region/search?q=Москва&key=YOUR_KEY

В запросе используются следующие параметры:

  • q=Москва — поиск выполняется по запросу «Москва».
  • key=YOUR_KEY — ваш ключ API.

Формат ответа​

Ответ на запрос возвращается в формате JSON:

{
    "meta": {
        "api_version": "2.0.448950",
        "code": 200,
        "issue_date": "20200629"
    },
    "result": {
        "items": [
            {
                "id": "32",
                "name": "Москва",
                "type": "region"
            }
        ],
        "total": 1
    }
}

Примеры использования​

Определение области поиска​

https://catalog.api.2gis.com/2.0/region/search?q=Москва&key=YOUR_KEY

Поиск категории с указанием области поиска​

https://catalog.api.2gis.com/2.0/catalog/rubric/search?q=кафе&region_id=32&key=YOUR_KEY

Поиск филиалов в найденной рубрике​

https://catalog.api.2gis.com/3.0/items?rubric_id=162&sort_point=37.622161%2C55.751597&key=YOUR_KEY

Тарифы​

  • Стоимость сервиса рассчитывается исходя из количества успешных запросов в месяц. Успешным запросом к API считается запрос, который возвращает HTTP-код 200 в поле meta.code в теле ответа, например:

    {
        "meta": {
            "api_version": "3.0.17799",
            "code": 200,
            "issue_date": "20240524"
        },
        ...
    }

  • Актуальную стоимость и лимиты см. в разделе Тарифы.

Варианты размещения​

  • Облако: все методы Regions API доступны через публичные endpoint-ы 2ГИС.
  • On-Premise: все методы Regions API доступны при установке API-платформы 2ГИС в закрытом контуре. Подробнее см. в разделе API-платформа для сервера.

Помощь​

  • Если у вас возникли вопросы при работе с API, задайте их AI-ассистенту (в правом нижнем углу cайта), воспользуйтесь поиском по документации или отправьте электронное письмо на api@2gis.ru.

  • Если вы хотите обсудить возможности API или его интеграцию с вашим продуктом, обратитесь к менеджеру.