Categories API

The Categories API provides information about categories – groups of companies that share the same business area.

Requests are made using the GET method, all required parameters should be passed in the query string. The responses are generated in the JSON format.

How it works

When users want to get detailed information about some specific company, they search it by name.

When users don’t know which company they need, they look at the companies’ list in the category they are interested in. In that case, the Categories API gives them information about categories.

Types of categories

There are two types of categories in the Categories API:

A common category is an object that corresponds to a general business area and contains links to its child categories. Child categories correspond to more specific areas.
A category is an object that corresponds to a business area.

Request format

Here is an example of a request

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

The request takes the following parameters:

q=cafe — the name of the category we are looking for is “cafe”;
region_id=32 — the id of the region limiting the search;
key=YOUR_KEY — your API key.

Response format

The response is returned in the JSON format:

{
    "meta": {
        "api_version": "2.0.448950",
        "code": 200,
        "issue_date": "20200629"
    },
    "result": {
        "items": [
            {
                "alias": "kafe_konditerskie_kofejjni",
                "branch_count": 3214,
                "caption": "Coffee and pastry shops",
                "id": "162",
                "keyword": "Coffee and pastry shops",
                "name": "Coffee and pastry shops",
                "org_count": 1665,
                "parent_id": "2",
                "title": "Coffee and pastry shops",
                "type": "rubric"
            }
        ],
        "total": 16
    }
}

How to use

For example, to get a list of companies in a specific category, you can use Categories API together with Places API:

Send a request to Categories API to cet a category ID:
- Option 1. Search by the category name:
```
https://catalog.api.2gis.com/2.0/catalog/rubric/search?q=cafe&region_id=32&key=YOUR_KEY
```
- Option 2. Retrieve the list of categories and select the required category from the list:
```
https://catalog.api.2gis.com/2.0/catalog/rubric/list?region_id=32&key=YOUR_KEY
```
Send a request to Places API to get a list of companies in the chosen category. Request can take several category names separated by a comma.
- Option 1. Search companies by keyword and filter them by category:
```
https://catalog.api.2gis.com/3.0/items?q=Boushe&rubric_id=162&sort_point=37.627798,55.755355&key=YOUR_KEY
```
- Option 2. Get the list of all companies in the category:
```
https://catalog.api.2gis.com/3.0/items?rubric_id=162&sort_point=37.627798%2C55.755355&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: see the Platform Manager section.
Read about the request and response formats.
Check the examples of the Categories API requests.