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 ID of a city where the search is performed in one of the ways:

    • Find the 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

    • Find the city by its name:

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

  2. Copy the value from the id field (part before the underscore "_" symbol) and pass it to the city_id field:

    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

The information about the entrance is available in the response body:

  • Entrance ID: see the value of the items.context.entrance_id field.

    Example:

        ...
        items: [
            {
                "context": {
                    "entrance_id": "70030076156592791"
                },
            ...
            }
        ...
        ]

  • Сoordinates of the entrance: in items.links.database_entrances, inside the required block with the corresponding entrance ID (id), see the value of the geometry.points field. To access the items.links.database_entrances field, you need the additional permission for your key.

    Example:

        ...
        "links": {
            "database_entrances": [
                {
                    "entity_name": "2nd entrance",
                    "entity_number": "2",
                    "geometry": {
                        ...
                        "points": [
                            "POINT(37.602988 55.743127)"
                        ],
                        ...
                    },
                    "id": "70030076156592791",
                    ...
                },
                ...
            ]
        }

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 one point. To limit the number of objects in the search results, use the following parameters:

  • page_size - number of objects per page
  • page - 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