Regions API

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.

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

Request format

This section presents 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

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

How to use

An example of using the Regions API is given below.

Determining a search area from a user query, e.g. “Moscow”:

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

Getting Started

Get an access key:
1. Sign in to the Platform Manager.
2. Create a demo key or purchase an access key for using API: see the Access keys instruction.
To work with access keys, you can use the Platform Manager: for details, see the account documentation.
Learn about the request and response formats.
Check the examples of the Regions API requests.