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

Identify the city_id for a city where the search is performed in one of the following ways:

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

Find the city by its name:

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

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

You can perform the search in one of the following ways:

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

Search and filter by a metro station.

Identify the id of the station.

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

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

Find the region you want to search in by a point or by its name.
- 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.
Find a category by which the list of branches will be expanded. Copy the values from step 1 (from the id field of the required categories) and pass it to the region_id field.
```
https://catalog.api.2gis.com/2.0/catalog/rubric/search?region_id=32&q=supermarket&key=YOUR_KEY
```
Send a request to 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

Find branches for the organization.
```
https://catalog.api.2gis.com/3.0/items?q=Moscow burger&fields=items.org&key=YOUR_KEY
```
Copy the org_id value from the items->org->id field.

Note that the company's org_id is unique for each region. Add a geographical restriction for precise search.
Send a request to the /3.0/items method, using the 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

Find the required building.
```
https://catalog.api.2gis.com/3.0/items?q=Moskva Dovatora 6/6&type=building&key=YOUR_KEY
```
Copy the value from the id field (its part before the underscore "_" symbol).
Send a request to the /3.0/items method, using the 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.

Find the required building.
```
https://catalog.api.2gis.com/3.0/items?q=Moskva Dovatora 9&key=YOUR_KEY
```
Copy the value from the id field (its part before the underscore "_" symbol).

Send a request to the /3.0/items method, using the 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 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

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

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

Retrieving the nearest parkings and stops

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

You can find the following data in the response:

links.nearest_stations — information on the nearest public transport stops. Transport types are prioritized as follows:
- If an object is located near the metro (within a radius of 1.5-2 km), a list of the nearest transport stops will contain only metro stations (including light metro and MCC).
- If an object is located far from the metro or a searched city does not have a metro, one nearest (within a radius of 1 km) transport stop is returned. Suburban train has the lowest priority.
- If no metro station or public transport stop is found within the search radius, the nearest (within a radius of 3 km) train station is returned.
links.nearest_parking — IDs of the nearest parking lots.