Examples
Before working with categories, you need to get the ID of the region you're interested in — it's passed in the region_id parameter in all subsequent requests.
Get the region ID
:::note [Access] Using the /2.0/region/search method (Regions API) requires a separate API key.
:::
Send a GET request to /2.0/region/search:
q- name of the city or region, for exampleq=Moscow.locale(optional) - search and response language, for examplelocale=en_RU. Defaults to the region's language.key- your API key.
Request example
https://catalog.api.2gis.com/2.0/region/search?q=Moscow&locale=en_RU&key=API_KEY
Example response:
response.json
{
"meta": {
"api_version": "2.0.21656",
"code": 200,
"issue_date": "20260925"
},
"result": {
"items": [
{
"id": "32",
"name": "Moscow",
"type": "region"
}
],
"total": 1
}
}
Copy the region ID from the result.items.id field.
Search for a category by name
To find a category by keyword, send a GET request to /2.0/catalog/rubric/search:
q- category name, for exampleq=cafe.region_id- region ID from step 1, for exampleregion_id=32.page(optional) - page number, defaults to1.page_size(optional) - number of results per page: 1 to 50 (default20).locale(optional) - search and response language, for examplelocale=en_RU. Defaults to the region's language.key- your API key.
Request example
https://catalog.api.2gis.com/2.0/catalog/rubric/search?q=cafe®ion_id=32&locale=en_RU&key=API_KEY
Response example
response.json
{
"meta": {
"api_version": "2.0.21656",
"code": 200,
"issue_date": "20260927"
},
"result": {
"items": [
{
"alias": "kafe",
"branch_count": 6539,
"caption": "Кафе",
"id": "161",
"keyword": "Кафе",
"name": "Кафе",
"org_count": 5262,
"parent_id": "2",
"title": "Кафе",
"type": "rubric"
},
...
],
"total": 9
}
}
Response parameters:
result.items- list of categories found:alias- category alias.id- category ID.keyword- category keywords.name,caption,title- category name.org_count- number of organizations in the category.parent_id- parent category ID.type- category type:rubric(regular) orgeneral_rubric(parent).
result.total- total number of categories found.
For a full list of parameters, see the API Reference.
Get the list of categories
To get the full catalog of categories in the selected region, send a GET request to /2.0/catalog/rubric/list:
region_id- region ID, for exampleregion_id=32.sort(optional) - sort order:name(alphabetical, default) orpopularity.page_size(optional) - number of results per page: 1 to 10000 (default10000).locale(optional) - search and response language, for examplelocale=en_RU. Defaults to the region's language.key- your API key.
Request example
https://catalog.api.2gis.com/2.0/catalog/rubric/list?region_id=32&locale=en_RU&key=API_KEY
Response example
response.json
{
"meta": {
"api_version": "2.0.21656",
"code": 200,
"issue_date": "20260927"
},
"result": {
"items": [
{
"alias": "avarijjnye_spravochnye_ehkstrennye_sluzhby",
"branch_count": 1942,
"id": "5419",
"name": "Аварийные / справочные / экстренные службы",
"org_count": 1530,
"type": "general_rubric"
},
...
],
"total": 28
}
}
Response parameters:
result.items- list of categories:alias- category alias.branch_count- number of branches in the category.id- category ID.name- category name.org_count- number of organizations in the category.type- category type:rubric(regular) orgeneral_rubric(parent).
result.total- total number of categories.
For a full list of parameters, see the API Reference.
Get the list of child categories
Used to get the list of child categories within a parent category.
Using the parent category ID
Get the parent category ID and send a GET request to /2.0/catalog/rubric/list:
parent_id- parent category ID, for exampleparent_id=2.region_id- region ID, for exampleregion_id=32.locale(optional) - search and response language, for examplelocale=en_RU. Defaults to the region's language.key- your API key.
Request example
https://catalog.api.2gis.com/2.0/catalog/rubric/list?parent_id=2®ion_id=32&locale=en_RU&key=API_KEY
Response example
response.json
{
"meta": {
"api_version": "2.0.21656",
"code": 200,
"issue_date": "20260927"
},
"result": {
"items": [
{
"alias": "ehkskursii",
"branch_count": 232,
"caption": "Экскурсии",
"id": "9281",
"name": "Экскурсии",
"org_count": 199,
"parent_id": "2",
"seo_name": "Экскурсии",
"title": "Экскурсии",
"type": "rubric"
},
...
],
"total": 97
}
}
Response parameters:
result.items- list of categories:alias- category alias.branch_count- number of branches in the category.id- category ID.name- category name.org_count- number of organizations in the category.type- category type:rubric(regular) orgeneral_rubric(parent).
result.total- total number of categories.
For a full list of parameters, see the API Reference.
Using the fields parameter
You can also get the list of parent and child categories using the fields parameter. To do this, send a GET request to /2.0/catalog/rubric/list:
region_id- region ID, for exampleregion_id=32.fields- additional fields. To get child categories, passfields=items.rubrics.locale(optional) - search and response language, for examplelocale=en_RU. Defaults to the region's language.key- your API key.
Request example
https://catalog.api.2gis.com/2.0/catalog/rubric/list?region_id=32&fields=items.rubrics&locale=en_RU&key=API_KEY
Response example
response.json
{
"meta": {
"api_version": "2.0.21656",
"code": 200,
"issue_date": "20260927"
},
"result": {
"items": [
{
"alias": "avarijjnye_spravochnye_ehkstrennye_sluzhby",
"branch_count": 1942,
"id": "5419",
"name": "Аварийные / справочные / экстренные службы",
"org_count": 1530,
"rubrics": [
{
"alias": "avarijjnye_komissary",
"branch_count": 23,
"caption": "Аварийные комиссары",
"id": "16182",
"name": "Аварийные комиссары",
"org_count": 14,
"parent_id": "5419",
"seo_name": "Аварийные комиссары (аваркомы)",
"title": "Аварийные комиссары",
"type": "rubric"
},
{
"alias": "avarijjnye_sluzhby",
"branch_count": 145,
"caption": "Аварийные службы",
"id": "122",
"name": "Аварийные службы",
"org_count": 121,
"parent_id": "5419",
"seo_name": "Аварийные (аварийно-диспетчерские) службы",
"title": "Аварийные службы",
"type": "rubric"
}
],
"type": "general_rubric"
},
...
],
"total": 28
}
}
Response parameters:
result.items- array of parent categories.result.items.rubrics- array of child categories (returned whenfields=items.rubricsis passed):alias- child category alias.branch_count- number of branches in the category.id- child category ID.name,caption,title- child category name.org_count- number of organizations in the category.parent_id- parent category ID.seo_name- SEO title of the category.type- category type:rubric(regular) orgeneral_rubric(parent).
result.total- total number of categories.
For a full list of parameters, see the API Reference.