Examples | 2GIS Documentation
Places API

Examples

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


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

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

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.


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

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.


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

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

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.

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

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

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

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

  2. 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
    
  3. 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
    

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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.