Skip to main content

Overview

The Places API allows you to search for various objects: organizations, buildings, landmarks, public transport stops, parking lots, and more.

Main features​

You can search for objects by:

  • organization name ("Ivanov")
  • category or business area ("restaurants" or "musical instrument stores")
  • service and product attributes ("cafe with Italian cuisine" or "Russian bathhouse with a wood-fired stove and pool")
  • address ("Baumanskaya street, 32")
  • geographic criterion in a text query ("flowers near Baumanskaya") or within a radius of a point, district, building, city, etc.
  • coordinates ("37.630866,55.752256")
  • object type (parking lots, stops, buildings, streets, and others)
  • object ID ("70000001029535674")
  • website ("2gis.ru")
  • phone number ("667-02-99")
  • ITIN ("5405276278")
  • trade license
  • FIAS code
  • brand, working hours, opening date, and other parameters

You can also sort search results and configure the search engine settings. For details about each parameter, see the API Reference and the Examples section.

Additional features

Learn about features of other search APIs to enrich your scenarios of working with objects on the map. For example, to provide suggestions when searching for objects, use the Suggest API. If you want to create a search widget on the map, check out the ready-made example of integrating search APIs into a web application.

Additional information on demand​

Obtaining certain information about objects is only available on demand and for an extra cost. To purchase access to the methods and fields below, contact the 2GIS sales team.

  • API methods:

  • Fields (specified using the fields parameter):

    • items.contact_groups - organization contacts
    • items.floors - number of floors
    • items.floor_plans - floor plans
    • items.links.database_entrances.apartments_info - information about apartments in the building
    • items.employees_org_count - number of employees in the organization
    • items.itin - individual taxpayer identification number
    • items.trade_license - branch trade license
    • items.fias_code - code of streets or administrative territories in the Federal Information Address System
    • items.address.components.fias_code - code of buildings in the Federal Information Address System
    • items.fns_code - Federal Tax Service code of administrative territories
    • items.okato - code of streets and administrative territories in the National Classifier of Administrative Territorial Entities
    • items.address.components.okato - code of buildings in the National Classifier of Administrative Territorial Entities
    • items.oktmo - code of streets and administrative territories in the National Classification of Territories of Municipal Formations
    • items.address.components.oktmo - code of buildings in the National Classification of Territories of Municipal Formations
    • items.structure_info.material - building material data
    • items.structure_info.apartments_count - number of apartments in the building
    • items.structure_info.porch_count - number of entrances in the building
    • items.structure_info.floor_type - floor type in the building
    • items.structure_info.gas_type - type of gas supply in the building
    • items.structure_info.year_of_construction - year of building construction
    • items.structure_info.elevators_count - number of elevators in the building
    • items.structure_info.is_in_emergency_state - whether the building is considered to be in emergency state
    • items.structure_info.project_type - series or a project of building construction
    • items.structure_info.chs_name - name of the cultural heritage site
    • items.structure_info.chs_category - category of the cultural heritage site

Getting started​

Follow the steps below to become familiar with Places API features and send a request to search for cafes near a point on the map.

Getting 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.

    Data on demand

    To obtain certain information about objects, an additional permission is required. Check the list of methods and fields for obtaining additional information on demand.

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

Request example​

A request to the Places API must contain:

  1. The object to search for. You can search for buildings, organizations, public transport stops, parking lots, landmarks, and other objects. For more information, see the Searching for objects and Filtering by attributes instructions.
  2. Search georestriction: where to search for the object. For more information, see the Search georestriction instruction.
  3. Your API key.

You can also obtain additional information about objects, process search results, configure the search algorithm, etc.


To find cafes near a point on the map, send a GET request to /3.0/items:

https://catalog.api.2gis.com/3.0/items?q=cafe&location=37.630866,55.752256&key=API_KEY

In the request, specify:

  • q=cafe - text query for searching an object: "cafe".
  • location=37.630866,55.752256 - georestriction: coordinates of the point near which to search.
  • key=API_KEY - API key value.

Response example​

Responses to requests are returned in JSON format.

Short response example:

{
    "meta": {
        "api_version": "3.0.20949",
        "code": 200,
        "issue_date": "20260703"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Варварка, 6 ст3",
                "id": "70000001029535674",
                "name": "Зарядье, гастрономический центр",
                "type": "branch"
            },
            ...
        ],
        "total": 1289
    }
}

Where:

  • result.items - array of objects matching the query. Each object contains:

    • address_name - object address.
    • id - object ID.
    • name - object name.
    • type - object type.

  • result.total - total number of objects matching the query.

To receive additional fields in the response, specify them in the fields request parameter. For more information, see the Additional information about objects instruction.

For details about each parameter, see the API Reference.

Tariffs and limits​

  • 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"
    },
    ...
}
  • For demo keys and keys created in a subscription, service usage limits apply.
  • See current prices and limits in the Prices instruction.

Deployment options​

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

Methods labeled as deprecated are not supported in any deployment options.

Support​

  • If you have any questions while working with the API, ask the AI assistant (in the lower-right corner of the 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.

What's next?​