Places API

The Places API performs a search for organizations, buildings and places.

You can search by:

company name (“Moos Hair Dressing”)
company's business area (“restaurants” or “music instrument stores”)
with geotags (“Al Mankhool flowers”)
attributes of goods and services (“Italian cuisine café” or “Sauna with a pool”)
telephone number or website (“97143017777” or “www.marinaviewhotel.com”)
without specifying a text query (in a building, in a category, in a city, search for all branches of one company)
makani (“12991 75289”)

Requests are made using the GET method, all required parameters should be passed in the query string. The response is returned in the JSON format.

Request format

Here is an example of a request:

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

Request takes the following parameters:

q=cafe — the search is performed for the “cafe” query
sort_point=37.630866,55.752256 — coordinates for a nearby cafe search
key=YOUR_KEY — your API key

Filtering the search result by object type

The type parameter is used to filter objects by type in the query. The search will be performed only among objects of the type specified in the query. Filtering is possible for these most frequently used types:

by location — for example, in a certain district, city, in a given area
by the type of response data — e.g., only companies or only buildings
by category — e.g., a search for cafes or grocery stores only
by organization — you can get the list of all branches of an organization
by working hours — e.g., only branches working around the clock
by availability or absence of data, e.g., photos, reviews, rating, website, tax identification number
by additional attributes — e.g., the availability of Wi-Fi, the ability to pay by card, etc

The complete list of filters and their corresponding parameters can be found in the API reference.

Filtering the search result by additional attributes

The list of available additional attributes for filtering is dynamic. You can see it by specifying the filters value in the fields parameter. In the answer, additional attributes will be listed in the field result.filter.attributes.

To filter the results by one or more additional attributes, each of them must be passed as a separate parameter attr[<code>]=<value>, where <code> is the code of an additional attribute, <value> is the value of an additional attribute. For additional attributes with the type flag - this is a Boolean value, for additional attributes with the type range - it is a range of two integers separated by commas. This method of filtering the result is relevant only for additional attributes with the types flag and range.

If you specify several additional attributes, filtering occurs by "AND", i.e. there will be objects in the output that meet both conditions.

Additional information about the object

The fields parameter is used to get more information about the object.

Sorting search results

You can enable sorting of the search result using the sort parameter in your query.

The search result is sorted by distance from the user's location, object rating and other parameters. Sorting types are defined in the API reference.

Search in an area on the map

You can search for objects in a specific area on a map. This type of search allows you to get relevant results. Search options for an area on the map are:

geographical criteria in the text request — for example, "Moscow cafe"
the point from which the search is performed
search in a radius
search in a rectangular area
search in an arbitrary area
search in the city

To search for objects in an area on the map, the query should contain coordinates of the points within which the objects are to be found or an identifier of the city in which you want to search for objects. You can find more detailed description of the fields in the API reference, examples of the use of geographic search restrictions can be found in the corresponding section.

Searching for information about an organization

You can find the organization by tax identification number, phone number, website address and trade license. Such a search does not take into account the location of the user. The result of this search is a list of organizations. Full description of all search methods and parameters can be found in the API reference.

Request response format

The request response is given in the JSON format:

{
    "meta": {
        "api_version": "3.0.448950",
        "code": 200,
        "issue_date": "20200626"
    },
    "result": {
        "items": [
            {
                "address_comment": "3, 5 floor",
                "address_name": "Nikolskaya, 25",
                "id": "70000001031668425",
                "name": "MCK, lounge bar chain",
                "type": "branch"
            }
        ],
        "total": 5926
    }
}

Request response parameters

Parameters that are passed in the response by default:

id — object identifier
name — object name
type — object type. Object types are defined in the API reference

Additional information about an object can be passed in the fields parameter. It is possible to get additional information on:

the point to which the object is bound
the object's address or location and its binding to administrative and territorial units
object geometry, visual center of geometry
the parent organization to which all company branches belong
working hours
contact info
objects related to the company or place: entry points, nearest stops and parking lots, service organizations, entrances to the building and others
detailed information about parking lots: capacity, cost, type of access, number of levels
detailed information about the building: number of storeys, building material

The full list of additional information is defined in the API reference.

Forming a search result

The search_type parameter is used to form the search result. The most commonly used algorithms for a search result generation are described below, the full list of algorithms can be found in the API reference.

Search with an expansion

In search results categories and organizations will be expanded to companies (branches of an organization). For example, a search for "Russian Post" will put all post offices in the search results. Category expansion works in a similar way — when searching for a "cafe", the result will contain companies from the "Cafe / Cafeteria" category rather than the category itself, which is also the subject of the catalog. This algorithm of result formation is used by default and matches the search_type=discovery parameter passed to the query.

A search with the only branch of an organization as a result

It is similar to a search with expansion, but also keeps only one branch for each organization. For example, the user wants to find an online store and to look at its site, and he does not need all the pick-up points in the result. To use this algorithm of forming the search result you need to pass search_type=one_branch to the query.

Search in a building

It is suitable for searching organizations in a building, for example, in a business center or a mall. You can also use it to autocomplete when searching in the building. To use this algorithm of forming the search result, you need to pass search_type=indoor to the query and specify the building id in the building_id parameter.

Getting Started

Fill in the application form to get your key.
Learn about the request and response formats.