Examples

Search for companies

Limit search results

To limit the number of objects in the search results, use the following parameters:

page_size — the number of objects per page
page parameters — the page number.

https://catalog.api.2gis.com/3.0/items?q=Moscow cafe&type=branch&page_size=10&page=1&key=YOUR_KEY

Search by text parameter

https://catalog.api.2gis.com/3.0/items?q=Moscow cafe&type=branch&key=YOUR_KEY

For more accurate search without geographical restrictions you should specify the city (village, district, region) where the search should be performed in the text of the query.

Search within a radius

https://catalog.api.2gis.com/3.0/items?q=cafe&type=branch&point=37.416469%2C55.619325&radius=1000&key=YOUR_KEY

Search within a radius and sort by distance

https://catalog.api.2gis.com/3.0/items?q=cafe&point=37.545423%2C55.740693&radius=1000&sort_point=37.545423%2C55.740693&sort=distance&key=YOUR_KEY

Search with specifying a search point

https://catalog.api.2gis.com/3.0/items?q=cafe&sort_point=37.545423%2C55.740693&key=YOUR_KEY

Objects closest to the point will be displayed first. There is no need to specify a city in the query.

Search in a rectangular area

https://catalog.api.2gis.com/3.0/items?q=cafe&fields=items.point&point1=37.602631%2C55.764592&point2=37.648702%2C55.743089&key=YOUR_KEY

Search in an arbitrary area

https://catalog.api.2gis.com/3.0/items?q=cafe&fields=items.point&polygon=POLYGON((37.5930 55.7667,37.6494 55.7667,37.6494 55.7405,37.5930 55.7405,37.5930 55.7667))&key=YOUR_KEY

The search area should be defined in the WKT format.

Search in a specific city

Step 1. Identify the city_id for a city where the search is performed. Take the value from the id field (its part before the underscore "_" symbol).

Option 1. Find the city by a point:

https://catalog.api.2gis.com/3.0/items?lon=37.62143&lat=55.752966&type=adm_div.city&key=YOUR_KEY

Option 2. Find the city by its name:

https://catalog.api.2gis.com/3.0/items?q=Moscow&key=YOUR_KEY

Step 2. Pass the value from the id field (its part before the underscore "_" symbol) to the city_id field in your request.

https://catalog.api.2gis.com/3.0/items?q=cafe&fields=items.point&city_id=4504222397630173&key=YOUR_KEY

Search in a specific city and sort by rating

https://catalog.api.2gis.com/3.0/items?q=beauty&city_id=4504222397630173&sort=rating&key=YOUR_KEY

Search near a metro station

Option 1. Search with a station name in the request.

https://catalog.api.2gis.com/3.0/items?q=metro kosino beauty&city_id=4504222397630173&key=YOUR_KEY

Option 2. Search and filter by a metro station.

Step 1. Identify the id of the station. Take the value from the id field (its part before the underscore "_" symbol).

https://catalog.api.2gis.com/3.0/items?type=station.metro&q=kosino&fields=items.point&sort_point=37.617135%2C55.757705&key=YOUR_KEY

Step 2. Pass the value from the id field (its part before the underscore "_" symbol) to the subway field in your request, the city name can be omitted:

https://catalog.api.2gis.com/3.0/items?q=beauty&fields=items.point&subway=70030076180130124&sort_point=37.617135%2C55.757705&key=YOUR_KEY

Search and filter by working hours and website availability

https://catalog.api.2gis.com/3.0/items?q=beauty&city_id=4504222397630173&work_time=thu,09:00&has_site=true&key=YOUR_KEY

Search and filter by additional attributes

https://catalog.api.2gis.com/3.0/items?q=Eat out&city_id=4504222397630173&attr[food_service_business_lunch]=true&attr[food_service_capacity]=10,30&key=YOUR_KEY

List of organizations

List of organizations in a category

Step 1. Find the region you want to search in by a point or by its name. Take the value from the id field.

Find a region by its name:

https://catalog.api.2gis.com/2.0/region/search?q=Moscow&key=YOUR_KEY

Find a region by a point:

https://catalog.api.2gis.com/2.0/region/search?q=37.624186%2C55.754285&key=YOUR_KEY

Details about the territorial division of the map can be found in the Regions API overview.

Step 2. Find a category by which the list of branches will be expanded. The value from step 1 is passed to the region_id field. Take the values from the id field of the required categories.

https://catalog.api.2gis.com/2.0/catalog/rubric/search?region_id=32&q=supermarket&key=YOUR_KEY

Step 3: Perform a request for the /3.0/items method using retrieved id from the previous step (or several ids separated by commas) as rubric_id. Add a geographical restriction (point + radius / point1 + point2 / polygon / city_id).

https://catalog.api.2gis.com/3.0/items?rubric_id=350,12127&point=37.624186%2C55.754285&radius=1000&key=YOUR_KEY

List of branches for an organization

Step 1. Find branches for the organization, take the org_id value from the items->org->id field.

https://catalog.api.2gis.com/3.0/items?q=Moscow burger&fields=items.org&key=YOUR_KEY

Note that the company's org_id is unique for each region. Add a geographical restriction for precise search.

Step 2. Perform a request for the /3.0/items method, using retrieved id from the previous step as org_id. Add a geographical restriction (point + radius / point1 + point2 / polygon / city_id).

https://catalog.api.2gis.com/3.0/items?org_id=4504136499435533&city_id=4504222397630173&key=YOUR_KEY

List of organizations in a building

Step 1. Find the building and take the value from the id field (its part before the underscore "_" symbol).

https://catalog.api.2gis.com/3.0/items?q=Moskva Dovatora 6/6&type=building&key=YOUR_KEY

Step 2. Perform a request for the /3.0/items method, using retrieved id from the previous step as building_id.

https://catalog.api.2gis.com/3.0/items?building_id=4504235282582289&key=YOUR_KEY

List of service organizations for a building

Service organizations are companies that perform building maintenance works and provide various public services. For example, post offices, health clinics, housing and utilities services, internet providers, schools, police stations.

Step 1. Find the building and take the value from the id field (its part before the underscore "_" symbol).

https://catalog.api.2gis.com/3.0/items?q=Moskva Dovatora 9&key=YOUR_KEY

Step 2. Perform a request for the /3.0/items method, using retrieved id from the previous step as building_id.To retrieve service organizations, specify the parameter service=true.

Retrieving services for the building (post office, health clinic, housing and utilities):

https://catalog.api.2gis.com/2.0/catalog/branch/list?building_id=4504235282737147&servicing=true&servicing_group=default&key=YOUR_KEY

Retrieving internet providers for the building:

https://catalog.api.2gis.com/2.0/catalog/branch/list?building_id=4504235282737147&servicing=true&servicing_group=internet&key=YOUR_KEY

Retrieving both services and providers with a single query:

https://catalog.api.2gis.com/2.0/catalog/branch/list?building_id=4504235282737147&servicing=true&key=YOUR_KEY

Search for organizations by their information

Search by phone number

https://catalog.api.2gis.com/3.0/items/byphone?phone=88001000000&fields=items.org&key=YOUR_KEY

Search by website

https://catalog.api.2gis.com/3.0/items/bysite?site=www.ikea.ru&key=YOUR_KEY

Search by tax identification number

https://catalog.api.2gis.com/2.0/catalog/branch/list?itin=7724490000&key=YOUR_KEY

Search by trade license

https://catalog.api.2gis.com/2.0/catalog/branch/list?trade_licence=*&key=YOUR_KEY

Retrieving an organization by id

Retrieving an organization and its entrances

https://catalog.api.2gis.com/3.0/items/byid?id=141265769584430&fields=items.links.database_entrances&key=YOUR_KEY

Search for places

Search for parking lots within a specified radius

https://catalog.api.2gis.com/3.0/items?q=parking&type=parking&point=37.592004%2C55.737264&radius=1000&fields=items.capacity,items.point,items.level_count,items.purpose,items.is_paid&key=YOUR_KEY

Search for a building with more detailed information

https://catalog.api.2gis.com/3.0/items?q=Moskva Dovatora 9&fields=items.address,items.adm_div,items.floors,items.point,items.links,items.structure_info.apartments_count,items.structure_info.material,items.structure_info.porch_count&key=YOUR_KEY

Search for a public transport stop

Search for a metro station in Moscow:

https://catalog.api.2gis.com/3.0/items?q=Arbatskaya&type=station&city_id=4504222397630173&key=YOUR_KEY

Search for a bus stop in Moscow:

https://catalog.api.2gis.com/3.0/items?q=Red Square&type=station&city_id=4504222397630173&key=YOUR_KEY

Retrieving an object by identifier

Retrieving a house

https://catalog.api.2gis.com/3.0/items/byid?id=4504235282757081&key=YOUR_KEY

Retrieving a house and its entrances

Response may contain both entrances to the building and entrances to organizations.

https://catalog.api.2gis.com/3.0/items/byid?id=4504235282757081&fields=items.links.database_entrances&key=YOUR_KEY

Retrieving an organization

https://catalog.api.2gis.com/3.0/items/byid?id=4504127908435201&key=YOUR_KEY

Retrieving a metro station and its entrances

https://catalog.api.2gis.com/3.0/items/byid?id=4504385606385704&fields=items.links.database_entrances&key=YOUR_KEY