Markers API

The Markers API searches for organizations, buildings, and places to display markers on the map. A marker is a representation of an object on the map, so the marker can only be an object with coordinates.

You can search for one or more places:

• by company name (“Moos Hair Dressing”)
• by company's business area (“restaurants” or “music instrument stores”)
• with geotags (“Al Mankhool flowers”)
• with attributes of goods and services (“Italian cuisine café” or “Sauna with a pool”)
• by telephone number or website (“97143017777” or “www.marinaviewhotel.com”)
• without specifying a text query (in a building, in a city)
• by 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.

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.

   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 Markers API requests and the full API reference.

Request format

Requests to the Markers API must contain the following components:

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

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

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 a text query (q parameter): for example, by specifying a 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 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

3. Your API key.

You can apply additional configurations to your search.

Request example

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

The request takes the following parameters:

• q=cafe - 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 response is returned in the JSON format:

{
    "meta": {
        "api_version": "3.0.448950",
        "code": 200,
        "issue_date": "20200626"
    },
    "result": {
        "items": [
            {
                "id": "70000001041443567",
                "type": "branch",
                "lat": 55.433435,
                "lon": 37.728608,
                "is_advertising": false
            }
        ],
        "total": 5926
    }
}

Parameters that are passed in the response by default:

• id - object identifier
• type - object type (see the full list in the API reference)
• lat - latitude
• lon - longitude
• is_advertising - flag that indicates the advertiser

---

Additional configuration

You can additionally configure the search to get data in a required form, for example:

• 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 categories of the object
• the floor ID on which the object is located
• the name of the object
• the branch license

See the full list of additional information in the API reference.

Type of search

The search_type parameter defines the search type: the algorithm and settings optimized for the search goal, as well as the logic for forming results.

The most commonly used search types are described below. See the full list in the search_type parameter description.

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 forming search results is used by default and matches the search_type=discovery parameter to the query.

Search with the only branch of an organization in a result

It is similar to a search with an 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 change the algorithm of forming search results, pass the search_type=one_branch parameter 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 change the algorithm of forming search results, pass the search_type=indoor parameter to the query and specify the building ID in the building_id field.

Sorting search results

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

The search result is sorted by a distance from the user, object rating, and other parameters. See sorting types in the API reference.

Filtering search results

You can filter search results:

• 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

See the complete list of filters and the corresponding parameters in the API reference.

An example of filtering by attributes:

Attribute tag	Purpose	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 the API reference)	point1=82.921663,55.030195&point2=82.921663,55.030195
district	Filter by district, can only be used when searching for organizations (type=branch)	Integer (district ID)	district_id=141347373711435
worktime	Filter by working time	String (see the format for the work_time parameter in the API reference)	work_time=now ID
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 attributes with the sort type in the filters block output are used to sort search results.

Tariffs

• The service fee is calculated based on the number of requests per month.
• To find out the current prices for services, contact the manager.