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&sort_point=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

Step 1. Identify the city_id to search in the city. Get this value from the id field (its part before the underscore ("_") symbol).

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

Option 2. Search for a city by name:

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

Step 2. Pass the value from the id field (its part before the underscore) 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&sort_point=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