Skip to main content

Examples

Search by address​

Simple search by address​

https://catalog.api.2gis.com/3.0/items/geocode?q=Moscow, Nikitsky pereulok, 3&fields=items.point,items.geometry.centroid&key=YOUR_KEY

For a more accurate search, specify the city (village, district, region) where the search should be performed. The locality name should be specified along with the name of the region.

Search with specifying a search point​

https://catalog.api.2gis.com/3.0/items/geocode?q=Nikitsky pereulok, 3&fields=items.point,items.geometry.centroid&location=37.62143%2C55.752966&sort=distance&key=YOUR_KEY

When sorted by ascending distance (sort = distance), the search result list will show objects closest to the point first. There is no need to specify a city in the query.

Search with specifying a search point and a radius​

https://catalog.api.2gis.com/3.0/items/geocode?q=Nikitsky pereulok, 3&fields=items.point,items.geometry.centroid&point=37.62143%2C55.752966&radius=1000&key=YOUR_KEY

There is no need to specify the city in the query.

Search in a rectangular area​

https://catalog.api.2gis.com/3.0/items/geocode?q=Nikitsky pereulok, 3&fields=items.point,items.geometry.centroid&point1=37.604977%2C55.7604&point2=37.646514%2C55.743983&key=YOUR_KEY

There is no need to specify the city in the query.

Search in an arbitrary area​

https://catalog.api.2gis.com/3.0/items/geocode?q=Nikitsky pereulok, 3&fields=items.point,items.geometry.centroid&polygon=POLYGON((37.5930%2055.7667,37.6494%2055.7667,37.6494%2055.7405,37.5930%2055.7405,37.5930%2055.7667))&key=YOUR_KEY

There is no need to specify the city in the query.

Search in a specific city​

  1. Identify the city_id to search in the city in one of the following ways:

    • Search for a city by a point:

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

    • Search for a city by name:

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

  2. Pass the value from the id field (its part before the underscore) of the response body as the city_id field in your request. No need to specify the city name in the query.

    https://catalog.api.2gis.com/3.0/items/geocode?q=Nikitsky pereulok, 3&fields=items.point,items.geometry.centroid&city_id=4504222397630173&key=YOUR_KEY

Search by address with indicating the entrance​

https://catalog.api.2gis.com/3.0/items/geocode?q=Obydenskiy 1st pereulok, 12 bld1, 2nd entrance&location=37.62143,55.752966&fields=items.context,items.links.database_entrances&key=YOUR_KEY

To get the coordinates of the entrance:

  • determine the entrance id: take the value from the items.context.entrance_id field
    ...
    items: [
        {
            "context": {
                "entrance_id": "70030076156592791"
            },
        ...
        }
    ...
    ]
  • determine the coordinates of the entrance: find the block with data about the required entrance by its entrance_id in the items.links.database_entrances block
    ...
    "links": {
        "database_entrances": [
            {
                "entity_name": "2nd entrance",
                "entity_number": "2",
                "geometry": {
                    ...
                    "points": [
                        "POINT(37.602988 55.743127)"
                    ],
                    ...
                },
                "id": "70030076156592791",
                ...
            },
            ...
        ]
    }

To access the items.links.database_entrances field, you need additional permission for your key.

Search by coordinates​

Simple search by coordinates​

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.621034&lat=55.750994&fields=items.adm_div,items.address&key=YOUR_KEY

Search by coordinates, specifying a radius​

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.614757&lat=55.755124&radius=50&fields=items.adm_div,items.address&key=YOUR_KEY

Limiting the number of search results​

There can be several objects at a point. 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/geocode?lon=37.614757&lat=55.755124&radius=50&fields=items.adm_div,items.address&page_size=1&page=1&key=YOUR_KEY

Search with indicating the type of the object​

Search for a building at the point:

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.618947&lat=55.752954&type=building&key=YOUR_KEY

Getting a city at the point:

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.613399&lat=55.755143&fields=items.adm_div,items.address&type=adm_div.city&key=YOUR_KEY

Search for a street at the point:

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.611915&lat=55.754061&fields=items.adm_div,items.address&type=street&key=YOUR_KEY