Skip to main content

Search by address (direct geocoding)

To search for an object by address, specify the address in the q parameter in a GET request to /3.0/items/geocode: for details, see the Search by address in text query section. To obtain object coordinates in the response, specify the fields=items.point,items.geometry.centroid parameter in the request.

You can also search by address for:

Search by address in text query​

You can specify in the q parameter an address with a locality name: a city, town, and others. For example, "ulitsa Karetny Ryad, 3, Moskva", "Prospekt Mira, 26 st1, Moskva", etc.

If you do not specify a locality, to restrict the search area, specify a georestriction. Otherwise, the search may return no results even if an object with the specified address exists.

For small localities (such as villages), it is recommended to specify its name with the region name and other administrative units it belongs to (such as a rural or urban settlement).

To obtain object coordinates, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address that includes a locality, for example "ulitsa Karetny Ryad, 3, Moskva".
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3, Moskva&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 3 ст1",
                "full_name": "Москва, улица Каретный Ряд, 3 ст1",
                "geometry": {
                    "centroid": "POINT(37.609256 55.770784)"
                },
                "id": "4504235282731438",
                "name": "улица Каретный Ряд, 3 ст1",
                "point": {
                    "lat": 55.770784,
                    "lon": 37.609256
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Search with georestriction​

You can specify a georestriction in the form of:

You cannot simultaneously specify georestrictions by radius, arbitrary area, and rectangular area (the point, polygon, and point1/point2 parameters).

Point coordinates​

Using the location parameter, you can restrict the search by point coordinates. The closest objects to the point will be listed first in the response. The locality name can be omitted from the text query.

To specify a point as the search area, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "ulitsa Karetny Ryad, 3".
  • location - search point coordinates in the longitude,latitude format, for example location=37.623056,55.752344.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3&location=37.623056,55.752344&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 3 ст1",
                "full_name": "Москва, улица Каретный Ряд, 3 ст1",
                "geometry": {
                    "centroid": "POINT(37.609256 55.770784)"
                },
                "id": "4504235282731438",
                "name": "улица Каретный Ряд, 3 ст1",
                "point": {
                    "lat": 55.770784,
                    "lon": 37.609256
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Radius around a point​

Using the radius parameter, you can limit search results to a radius around a point. The point can be specified using the point parameter or a pair of lon and lat parameters. The locality name can be omitted from the text query.

The maximum radius is 2,000 m. If the address is specified in the request as a text query (q parameter), the maximum radius is 50,000 m (see the request example for reverse geocoding).

To specify a search radius, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "ulitsa Karetny Ryad, 3".
  • point - coordinates of the search center point in the longitude,latitude format, for example point=37.623056,55.752344.
  • radius - search radius in meters, for example radius=10000.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3&point=37.623056,55.752344&radius=10000&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 3 ст1",
                "full_name": "Москва, улица Каретный Ряд, 3 ст1",
                "geometry": {
                    "centroid": "POINT(37.609256 55.770784)"
                },
                "id": "4504235282731438",
                "name": "улица Каретный Ряд, 3 ст1",
                "point": {
                    "lat": 55.770784,
                    "lon": 37.609256
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Rectangular area​

Using the point1 and point2 parameters, you can limit search results to a rectangular area by specifying the coordinates of the top-left and bottom-right corners. The maximum distance between points is two kilometers. The locality name can be omitted from the text query.

To specify a rectangular search area, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "ulitsa Karetny Ryad, 3".
  • point1 - coordinates of the top-left corner of the rectangular area in the longitude,latitude format, for example 37.606789,55.771235.
  • point2 - coordinates of the bottom-right corner of the rectangular area in the longitude,latitude format, for example 37.611516,55.769179.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3&point1=37.606789,55.771235&point2=37.611516,55.769179&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 3 ст1",
                "full_name": "Москва, улица Каретный Ряд, 3 ст1",
                "geometry": {
                    "centroid": "POINT(37.609256 55.770784)"
                },
                "id": "4504235282731438",
                "name": "улица Каретный Ряд, 3 ст1",
                "point": {
                    "lat": 55.770784,
                    "lon": 37.609256
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Arbitrary area​

Using the polygon parameter, you can limit search results to an arbitrary area by specifying the coordinates of the polygon vertices. The locality name can be omitted from the text query.

To specify an arbitrary search area (polygon), send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "ulitsa Karetny Ryad, 3".
  • polygon - coordinates of the polygon vertices in WKT format.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3&polygon=POLYGON((37.604943 55.772081, 37.609896 55.773073, 37.612378 55.770239, 37.605307 55.76913, 37.604943 55.772081))&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260810"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 3 ст1",
                "full_name": "Москва, улица Каретный Ряд, 3 ст1",
                "geometry": {
                    "centroid": "POINT(37.609256 55.770784)"
                },
                "id": "4504235282731438",
                "name": "улица Каретный Ряд, 3 ст1",
                "point": {
                    "lat": 55.770784,
                    "lon": 37.609256
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Viewport​

Using the viewpoint1 and viewpoint2 parameters, you can limit search results by viewport (a rectangular map area). Unlike the rectangular area georestriction, the viewport affects the ranking of results, but does not strictly limit the search to the specified boundaries. The locality name can be omitted from the text query.

To specify a viewport, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "ulitsa Karetny Ryad, 3".
  • viewpoint1 - coordinates of the top-left corner of the rectangular area in the longitude,latitude format, for example 37.606789,55.771235.
  • viewpoint2 - coordinates of the bottom-right corner of the rectangular area in the longitude,latitude format, for example 37.611516,55.769179.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3&viewpoint1=37.606789,55.771235&viewpoint2=37.611516,55.769179&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 3 ст1",
                "full_name": "Москва, улица Каретный Ряд, 3 ст1",
                "geometry": {
                    "centroid": "POINT(37.609256 55.770784)"
                },
                "id": "4504235282731438",
                "name": "улица Каретный Ряд, 3 ст1",
                "point": {
                    "lat": 55.770784,
                    "lon": 37.609256
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Region​

Using the region_id parameter, you can limit search results to a region by specifying its identifier. The maximum number of regions in a request is 50. The locality name can be omitted from the text query.

To specify a region as the search area, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "ulitsa Karetny Ryad, 3".
  • region_id - region ID, for example region_id=32. Region IDs are not linked to the codes of subjects of the Russian Federation. For more information on obtaining an ID, see the Region ID section.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3&region_id=32&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 3 ст1",
                "full_name": "Москва, улица Каретный Ряд, 3 ст1",
                "geometry": {
                    "centroid": "POINT(37.609256 55.770784)"
                },
                "id": "4504235282731438",
                "name": "улица Каретный Ряд, 3 ст1",
                "point": {
                    "lat": 55.770784,
                    "lon": 37.609256
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

City​

Using the city_id parameter, you can limit search results to a city by specifying its identifier. The maximum number of cities in a request is 50. The locality name can be omitted from the text query.

To specify a city as the search area, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "ulitsa Karetny Ryad, 3".
  • city_id - city ID, for example city_id=4504222397630173. You can use multiple IDs separated by commas, for example city_id=4504222397630173,4504222397630174. For more information on obtaining an ID, see the City ID section.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3&city_id=4504222397630173&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 3 ст1",
                "full_name": "Москва, улица Каретный Ряд, 3 ст1",
                "geometry": {
                    "centroid": "POINT(37.609256 55.770784)"
                },
                "id": "4504235282731438",
                "name": "улица Каретный Ряд, 3 ст1",
                "point": {
                    "lat": 55.770784,
                    "lon": 37.609256
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Place​

Using the place_id parameter, you can limit search results to a place by specifying its identifier. Places are area objects: parks, beaches, resort areas, lakes, and other locations. The maximum number of places in a request is 50. The locality name can be omitted from the text query.

To specify a place as the search area, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "Prospekt Mira, 119 st23".
  • place_id - place ID, for example place_id=4504286822138302. You can use multiple IDs separated by commas, for example place_id=4504286822138302,4504127908543952. For more information on obtaining an ID, see the Place ID section.
  • location - search point coordinates in the longitude,latitude format, for example location=37.637635,55.826241.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=Prospekt Mira, 119 st23&place_id=4504286822138302&location=37.637635,55.826241&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "проспект Мира, 119 ст23",
                "building_name": "Москвариум, центр океанографии и морской биологии",
                "full_name": "Москва, Москвариум, центр океанографии и морской биологии",
                "geometry": {
                    "centroid": "POINT(37.618523 55.832969)"
                },
                "id": "4504235290763063",
                "name": "Москвариум, центр океанографии и морской биологии",
                "point": {
                    "lat": 55.832969,
                    "lon": 37.618523
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Metro station​

Using the subway parameter, you can restrict the search by metro station. The maximum number of stations in a request is 50. The locality name can be omitted from the text query.

To specify a metro station near which to search, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "ulitsa Karetny Ryad, 3".
  • subway - metro station ID, for example subway=4504385606388578. You can use multiple IDs separated by commas, for example subway=4504385606388578,4504385606390686. For more information on obtaining an ID, see the Metro station ID section.
  • location - search point coordinates in the longitude,latitude format, for example location=37.623056,55.752344. For example, you can specify the coordinates of any point in a city.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3&subway=4504385606388578&location=37.623056,55.752344&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 3 ст1",
                "full_name": "Москва, улица Каретный Ряд, 3 ст1",
                "geometry": {
                    "centroid": "POINT(37.609256 55.770784)"
                },
                "id": "4504235282731438",
                "name": "улица Каретный Ряд, 3 ст1",
                "point": {
                    "lat": 55.770784,
                    "lon": 37.609256
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Search for building entrance​

To obtain the coordinates of a building entrance, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address and entrance number, for example "Moskva, Sadovaya-Karetnaya ulitsa, 10, pod'ezd 2".

  • fields - list of fields to return in the response:

    • items.context - building entrance ID.
    • items.point, items.geometry.centroid - object coordinates.
    • items.links.database_entrances - coordinates of the building entrance (requires additional key permission).

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=Moskva, Sadovaya-Karetnaya ulitsa, 10, pod'ezd 2&fields=items.context,items.point,items.geometry.centroid,items.links.database_entrances&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 5/10 ст2 / Садовая-Каретная улица, 10",
                "context": {
                    "entrance_id": "70030076156473891"
                },
                "full_name": "Москва, улица Каретный Ряд, 5/10 ст2 / Садовая-Каретная улица, 10",
                "geometry": {
                    "centroid": "POINT(37.609082 55.772469)"
                },
                "id": "4504235282731036",
                "links": {
                    "database_entrances": [
                        {
                           "entity_name": "2 подъезд",
                           "entity_number": "2",
                           "geometry": {
                              "points": [
                                 "POINT(37.609389 55.772308)"
                              ],
                           },
                           "id": "70030076156473891",
                           "is_primary": false,
                        }
                    ]
                },
                "name": "улица Каретный Ряд, 5/10 ст2 / Садовая-Каретная улица, 10",
                "point": {
                    "lat": 55.772469,
                    "lon": 37.609082
                },
                "purpose_name": "Жилой дом",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Search by object type​

Using the type parameter, you can search for objects of a particular type: buildings, streets, parking lots, stops, landmarks, and others. For the full list of object types, see the API reference.

To find objects of a particular type, send a GET request to /3.0/items/geocode with the following parameters:

  • q - text query with an address, for example "Moskva, ulitsa Karetny Ryad, 3". Instead of the locality in a text query, you can specify a georestriction: for more information, see the Search with georestriction section.
  • type - object type, for example type=street to search for streets.
  • fields=items.point,items.geometry.centroid - includes fields with object coordinates in the response.

Request example:

https://catalog.api.2gis.com/3.0/items/geocode?q=Moskva, ulitsa Karetny Ryad, 3&type=street&fields=items.point,items.geometry.centroid&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260807"
    },
    "result": {
        "items": [
            {
                "full_name": "Москва, улица Каретный Ряд",
                "geometry": {
                    "centroid": "POINT(37.610131 55.771827)"
                },
                "id": "4504338361748615",
                "name": "улица Каретный Ряд",
                "point": {
                    "lat": 55.771827,
                    "lon": 37.610131
                },
                "type": "street"
            }
        ],
        "total": 1
    }
}