Handling search results
You can handle search results:
- sort them by parameters
- obtain a particular page of search results
- limit the number of results per page
Sorting results
Using the sort parameter, you can sort search results by distance from the user and other parameters. By default, results are sorted by relevance in descending order. For the full list of sorting parameters, see the API Reference.
To sort search results, send a GET request to /3.0/items/geocode with the following parameters:
q- text query with address, for example "Moskva, Sadovaya ulitsa".sort- sorting parameter, for examplesort=nameto sort by object name.
Request example:
https://catalog.api.2gis.com/3.0/items/geocode?q=Moskva, Sadovaya ulitsa&sort=name&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"full_name": "Московский, 1-я Садовая улица",
"id": "70030077102596595",
"name": "1-я Садовая улица",
"type": "street"
},
{
"full_name": "Николо-Хованское, 1-я Садовая улица",
"id": "70030076625195996",
"name": "1-я Садовая улица",
"type": "street"
},
{
"full_name": "Столбово, 1-я Садовая улица",
"id": "70030076415177293",
"name": "1-я Садовая улица",
"type": "street"
},
{
"full_name": "Соколово, 1-я Садовая улица",
"id": "70030076324808258",
"name": "1-я Садовая улица",
"type": "street"
},
{
"full_name": "Рассудово, 1-я Садовая улица",
"id": "70030076200659822",
"name": "1-я Садовая улица",
"type": "street"
},
{
"full_name": "Москва, 1-я Садовая улица",
"id": "70030076161647419",
"name": "1-я Садовая улица",
"type": "street"
},
{
"full_name": "Москва, 10-я Садовая улица",
"id": "70030076161655120",
"name": "10-я Садовая улица",
"type": "street"
},
{
"full_name": "Москва, 11-я Садовая улица",
"id": "70030076161655145",
"name": "11-я Садовая улица",
"type": "street"
},
{
"full_name": "Москва, 12-я Садовая улица",
"id": "70030076161655176",
"name": "12-я Садовая улица",
"type": "street"
},
{
"full_name": "Москва, 13-я Садовая улица",
"id": "70030076161655198",
"name": "13-я Садовая улица",
"type": "street"
}
],
"total": 115
}
}
Obtaining results by pages
In response to an API request, search results are displayed paginated. By default, each page contains 20 results for the production key in a subscription and 10 results for the demo key.
By default, the first page is displayed. Using the page parameter, you can obtain a particular page of search results.
To obtain a particular page of search results, send a GET request to /3.0/items/geocode with the following parameters:
q- text query with address, for example "Moskva, Sadovaya ulitsa".page- page number with results, for examplepage=5to obtain the fifth page. If you use a demo key to access the API, the maximum value is 5.
Request example:
https://catalog.api.2gis.com/3.0/items/geocode?q=Moskva, Sadovaya ulitsa&page=5&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"full_name": "Марушкино, Садовая улица",
"id": "4504338361771242",
"name": "Садовая улица",
"type": "street"
},
{
"full_name": "Грибки, Садовая улица",
"id": "70030076126415853",
"name": "Садовая улица",
"type": "street"
},
{
"full_name": "Марушкино, Садовая улица",
"id": "70030076198234378",
"name": "Садовая улица",
"type": "street"
},
{
"full_name": "Тарычево, Садовая улица",
"id": "70030076449591834",
"name": "Садовая улица",
"type": "street"
},
{
"full_name": "Городище, Садовая линия",
"id": "4504338361759638",
"name": "Садовая линия",
"type": "street"
},
{
"full_name": "Зименки, Садовая улица",
"id": "4504338361762982",
"name": "Садовая улица",
"type": "street"
},
{
"full_name": "Крекшино, Садовая улица",
"id": "4504338361770181",
"name": "Садовая улица",
"type": "street"
},
{
"full_name": "Зеленоград, Садовая улица",
"id": "4504338361776459",
"name": "Садовая улица",
"type": "street"
},
{
"full_name": "Зименки, Садовая улица",
"id": "70030076184149318",
"name": "Садовая улица",
"type": "street"
},
{
"full_name": "Киевский, Садовая улица",
"id": "70030076196182140",
"name": "Садовая улица",
"type": "street"
}
],
"total": 115
}
}
Limiting the number of results per page
In response to an API request, search results are displayed paginated. By default, each page contains 20 results for the production key in a subscription and 10 results for the demo key.
Using the page_size parameter, you can change the number of results per page, from 1 to 50. For example, you can:
- reduce the number of search results on the map to show nearby places without cluttering the interface
- increase the number of results to send fewer requests
To limit the number of search results per page, send a GET request to /3.0/items/geocode with the following parameters:
q- text query with address, for example "Moskva, Sadovaya ulitsa".page_size- number of results per page, for examplepage_size=3to obtain three results per page. If you use a demo key to access the API, the maximum value is 10.
Request example:
https://catalog.api.2gis.com/3.0/items/geocode?q=Moskva, Sadovaya ulitsa&page_size=3&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"full_name": "Москва, Большая Садовая улица",
"id": "4504338361749631",
"name": "Большая Садовая улица",
"type": "street"
},
{
"full_name": "Москва, Садовая улица",
"id": "4504338361806057",
"name": "Садовая улица",
"type": "street"
},
{
"full_name": "Москва, Садовая улица",
"id": "70030077106144545",
"name": "Садовая улица",
"type": "street"
}
],
"total": 74
}
}