Skip to main content

Overview

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

When users want to get detailed information about some specific company, they search it by name. When users do not 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.

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.
Additional features

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

Getting started​

  1. Get an access key:

    1. Sign in to the Platform Manager.

    2. Create a demo key or purchase a subscription for using API. For details on service prices, see the Tariffs section.

    For more information on working with access keys and subscriptions, see the account documentation.

  2. Study the request format and response format.

  3. Study the examples of responses to the Categories API and the full API Reference.

Request format​

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

Where:

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

Usage example​

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

  1. Send a request to the Categories API to get 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

  2. Send a request to the Places API to get a list of companies in the chosen category. The request can take several categories 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

Tariffs​

  • The service fee is calculated based on the number of successful requests per month. A successful API request is a request that returns an HTTP code of 200 in the meta.code field of the response. Example:
{
   "meta": {
      "api_version": "2.0.448950",
      "code": 200,
      "issue_date": "20200629"
   },
   ...
}
  • See current prices and rate limits in the Prices section.

Deployment options​

  • Cloud-based: all Categories API methods are available through public 2GIS endpoints.
  • On-Premise: all Categories API methods are available when the 2GIS API Platform is installed in a private network. For more information, see the API Platform for server.

Support​

  • If you have any questions while working with the API, ask AI assistant (in the lower-right corner of website), use the documentation search, or send an email to api@2gis.com.

  • If you would like to discuss the capabilities of the API or its integration with your product, please contact a manager.