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. To provide hints when searching for objects use Suggest API.
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” querysort_point=37.630866,55.752256
— coordinates for a nearby cafe searchkey=YOUR_KEY
— your API key
Search with geographic restrictions
For all requests, it is obligatory to specify the search geography restrictions. The following options are available:
- 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
See also:
Filtering the search result by object type
Filtering is possible for these most frequently used types:
- by object type — for example, only among attractions
- 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
Additional attributes contain reference information about organizations: the availability of Wi-Fi, the average check, whether they have delivery, what product range and types of services they offer, whether there is coffee-to-go, and so on.
The list of available additional attributes for filtering is dynamic. To see it, specify the &fields=filters
parameter in the request. In the response, additional attributes will be listed in the result.filters.attributes
field.
To filter the results by one or more additional attributes, pass each of them as a separate parameter attr[<code>]=<value>
.
Where:
-
<code>
— is the code of an additional attribute. -
<value>
— is the value of the additional attribute. The value type depends on the attribute type:Attribute type Value type Example flag
Boolean attr[food_service_business_lunch]=true
range
Range of two comma-separated integers attr[food_service_capacity]=10,30
Filtering by attributes with type filter
:
Attribute tag | Destination | Value type | Example |
---|---|---|---|
has_site |
Filter by site availability | Boolean | has_site=true |
has_photos |
Filter by photo availability | Boolean | has_photos=true |
bound |
Filter by rectangular area | String (see the format of the point1 and point2 fields in API description) |
point1=82.921663,55.030195&point2=82.921663,55.030195 |
Filtering by other attributes:
Attribute tag | Destination | Value type | Example |
---|---|---|---|
district |
Filter by district | Integer (district ID) | district_id=141347373711435 |
worktime |
Filter by working time | String (see format for worktime parameter in [API description].(/ru/api/search/places/reference/3.0/items)) |
worktime=now |
subway |
Filter by metro station | Integer (subway station ID) | subway=141523467371731 |
If you specify several additional attributes, only those objects that meet all conditions will be returned in the response.
The sort
attributes in the filters
block output are used to sort search results
Additional information about the object
The fields
parameter is used to get more information about the object. The available fields are listed in the API reference.
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.
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 identifiername
— object nametype
— 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 in a particular segment of the map.
- 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.
Type of a search
The search_type
parameter defines the algorithm and the settings optimized for a specific search goal, as well as for the logic for generating search results.
The most commonly used search types are described below. The full list of search types 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
-
Get your API key:
- Sign in to the Platform Manager.
- Create a demo key (if you have not used Urbi products before) or request a production key: follow the link to contact a manager on the API Keys tab.
In the Platform Manager, you can also:
- See information on your current keys: which services are enabled, which limit is set for each, when a key will be deactivated, and more.
- Set restrictions for a key by HTTP headers or by IP and subnet.
- Check the statistics of request distribution for each key.
-
Learn about the request and response formats.
-
Check the examples of the Places API requests.