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 your API key:
1. Sign in to the Platform Manager.
2. Create a demo key (if you have not used Urbi products before) or request a production key: follow the link to contact a manager on the API Keys tab.
In the Platform Manager, you can also:
- See information on your current keys: which services are enabled, which limit is set for each, when a key will be deactivated, and more.
- Set restrictions for a key by HTTP headers or by IP and subnet.
- Check the statistics of request distribution for each key.
Read about the request and response formats.
Check the examples of the Categories API requests.