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

The Categories API is used with the Places API.

• Step 1. Get a category. 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 choosing the required category from the list:

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

• Step 2. Get the list of companies in the chosen category.

Request takes several category names separated by a comma.

Option 1. Search companies by text 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

1. Fill in the application form to get your key.
2. Read about the request and response formats.
3. Check the examples of the Categories API requests.