Places API

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

You can search for one or more places by various criteria:

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

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 an access key for using API: see the Access keys instruction.

   Important

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

   To work with access keys, you can use the Platform Manager: for details, see the account documentation.

2. Learn about the request and response formats.

3. Check the examples of the Places API requests and the full API reference.

Additional information on demand

Getting 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 Urbi sales team.

• API methods:

  • /3.0/items/bysite - searching for organizations by a website address
  • /3.0/items/byphone - searching for organizations by a phone number
  • /3.0/items/byitin - searching for organizations by an individual tax identification number
  • /3.0/items/bytradelicense - searching for organizations by a trade license number
  • /3.0/items/byfias - searching for organizations by a code in the Federal Information Address System

• Fields (specified in the fields parameter):

  • items.contact_groups - detailed contact information of the organization
  • 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 of the organization
  • items.itin - individual tax identification number
  • items.trade_license - 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 - information about the building material
  • 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

Request format

Any request to Places API must contain the following components:

1. Object search request (what to search for?). This component is always required. You can provide this request in multiple ways:

   • As a text query (q parameter) with different levels of precision:

     • with a particular object name (“Moos Hair Dressing”)
     • with a category of interest (music instrument stores)
     • with criteria of interest (restaurant with italian cuisine) and more

   • As a filter by an attribute of interest (for example, by working hours). See more about attributes below.

   • By specifying an ID of a particular object or category.

   • By specifying a known attribute of a particular object: phone number, website address, tax identification number, or trade license.

2. Geographic restriction (where to search?). This component is required when searching for a list of objects by specific criteria (for example, all currently open cafes in Dubai). You can set this restriction in multiple ways:

   • In a text query (q parameter). You can specify a required region, city, district, street, subway station and more.

     You can combine an object search request and a geographic restriction in one text query (flower shops in Dubai). Only one q parameter must be used.

   • By specifying an ID of a required city, building, subway station, and more.

   • By specifying a search region:

     • within a radius around a point
     • in a rectangular area
     • in an arbitrary area

   Note

   You do not need to specify a geographic restriction if you search for a particular object by its unique attribute using the following methods:

   • /3.0/items/byid,
   • /3.0/items/bysite,
   • /3.0/items/byphone,
   • /3.0/items/byservicing,
   • /3.0/items/byitin,
   • /3.0/items/bytradelicense,
   • /3.0/items/byfias.

3. Your API key.

You can apply additional configurations to your search.

Request example

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

Request takes the following parameters:

• q=cafe - the search is performed for the “cafe” query
• location=37.630866,55.752256 - geographic restriction: coordinates for a nearby cafe search
• key=YOUR_KEY - your API key

See more request examples for solving various tasks.

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

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 configuration

You can additionally configure the search to get required data in a desired form, in particular:

• get additional information about an object
• configure the search type
• sort search results
• filter search results by additional attributes

Additional information

To get additional information in the response, use the fields parameter. For example, you can get the following data for an object:

• 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 floors, building material

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

Type of 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 for 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.

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.

Filtering the search result

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