Examples | 2GIS Documentation
Geocoder API

Examples

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.

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.

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.

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.

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.

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

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.621034&lat=55.750994&fields=items.adm_div,items.address&key=YOUR_KEY
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

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