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