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
-
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
-
-
Pass the value from the
id
field (its part before the underscore) of the response body as thecity_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 theitems.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 theitems.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 pagepage
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