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.
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&key=YOUR_KEY
The search result list will show objects closest to the point first. There's 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 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 quantity of objects in the output, you can use the page_size
and page
parameters that represent the number of objects on one page and the page number, respectively.
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&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