Skip to main content

Overview

The Regions API is used to select a region that limits the searches for organizations, buildings, and places.

In terms of this API we use a word region (region_id) for an agglomeration that includes a large city ​​and its nearest settlements, as well as its satellite cities. These are territories with more detailed map and catalog data. Territories beyond the borders of the region — settlements, administrative divisions and so on — are called segments (segment_id).

In general, the regions and segments have nothing in common with the subjects of the Russian Federation and correspond to the 2GIS internal format of data storage only.

Outside the regions, the search for places and companies is geographically restricted.

Additional features

Learn about features of other search APIs to enrich your scenarios of working with objects on the map.

Getting started​

  1. Get an access key:

    1. Sign in to the Platform Manager.

    2. Create a demo key or purchase a subscription for using API. For details on service prices, see the Tariffs section.

    For more information on working with access keys and subscriptions, see the account documentation.

  2. Study the request format and response format.

  3. Study the examples of requests to the Regions API and the full API reference.

Request format​

An example of a request:

https://catalog.api.2gis.com/2.0/region/search?q=Moscow&key=YOUR_KEY

This request takes the following parameters:

  • q=Moscow — the search is performed for the “Moscow” query.
  • key=YOUR_KEY — your API key.

Response format​

The response to the request is returned in JSON format:

{
    "meta": {
        "api_version": "2.0.448950",
        "code": 200,
        "issue_date": "20200629"
    },
    "result": {
        "items": [
            {
                "id": "32",
                "name": "Moscow",
                "type": "region"
            }
        ],
        "total": 1
    }
}

Usage examples​

Determining a search area​

https://catalog.api.2gis.com/2.0/region/search?q=Moscow&key=YOUR_KEY

Search for a category within a specified region​

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

Search for branches in the found category​

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

Tariffs​

  • The service fee is calculated based on the number of successful requests per month. A successful API request is a request that returns an HTTP code of 200 in the meta.code field of the response. Example:
{
    "meta": {
        "api_version": "2.0.448950",
        "code": 200,
        "issue_date": "20200629"
    },
    ...
}
  • See current prices and rate limits in the Prices section.

Deployment options​

  • Cloud-based: all Regions API methods are available through public 2GIS endpoints.
  • On-Premise: all Regions API methods are available when the 2GIS API Platform is installed in a private network. For more information, see the API Platform for server.

Support​

  • If you have any questions while working with the API, ask AI assistant (in the lower-right corner of website), use the documentation search, or send an email to api@2gis.com.

  • If you would like to discuss the capabilities of the API or its integration with your product, please contact a manager.