Searching for objects
You can search for objects (organizations, buildings, landmarks, public transport stops, parking lots, and others):
To search for organizations by standard parameters (name, address, categories, and others), specify the type=branch parameter in the request to the /3.0/items endpoint. Additionally, you can use endpoints for searching for organizations by unique attributes. Access to them (except for /3.0/items/byservicing) is available on demand and for an extra cost. To purchase access, contact the 2GIS sales team:
- /3.0/items/byservicing - search for organizations servicing a building by building ID
- /3.0/items/bysite - search for organizations by website
- /3.0/items/byphone - search for organizations by phone number
- /3.0/items/byitin - search for organizations by ITIN
- /3.0/items/bytradelicense - search for organizations by trade license
- /3.0/items/byfias - search for organizations by FIAS code
By text query
You can specify a text query in the q parameter: the object you want to find, for example "metro", "cafe", "pharmacy", and others. You can refine the query by specifying:
- a particular place (
Bolshoi Theatre) or organization name (Stars Coffee) - a category (
musical instrument stores) - a criterion (
restaurants with Italian cuisine) - other parameters
You can specify both the object and georestriction in the q parameter simultaneously, for example cafe in Tverskoy district Moscow. Only one q parameter can be specified in a request. If you do not specify georestriction in the q parameter, pass it using other methods to improve search accuracy, for example, using the location, city_id, region_id, and other parameters. For the full list, see the Search georestriction instruction.
To find an object, send a GET request to /3.0/items with the following parameters:
q- text query, for example "novaya tretyakovka".city_id- city ID, for examplecity_id=4504222397630173for Moscow. For more information on obtaining an ID, see the City ID section. You can specify georestriction in another way: for more information, see the Search georestriction instruction.
Request example:
https://catalog.api.2gis.com/3.0/items?q=novaya tretyakovka&city_id=4504222397630173&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.20949",
"code": 200,
"issue_date": "20260716"
},
"result": {
"items": [
{
"address_name": "улица Крымский Вал, 10",
"building_name": "Государственная Третьяковская галерея",
"full_name": "Москва, Государственная Третьяковская галерея",
"id": "4504127908465347",
"name": "Новая Третьяковка",
"purpose_name": "Музей",
"type": "branch"
},
{
"address_name": "1-й Голутвинский переулок, 16 ст1",
"id": "70000001110841368",
"name": "Новая Третьяковка",
"type": "branch"
},
{
"address_name": "переулок Васнецова, 13 ст1",
"id": "70000001115180780",
"name": "Новая Третьяковка",
"type": "branch"
}
],
"total": 3
}
}
By object type
Using the type parameter, you can search for objects of a particular type: organizations, buildings, streets, parking lots, stops, metro stations, landmarks, and others.
The type parameter can be specified for the following endpoints:
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 with the following parameters:
q- text query, for example "metro".point- coordinates of the search center point in thelongitude,latitudeformat, for examplepoint=37.630866,55.752256.radius- search radius in meters, for exampleradius=1000. You can specify georestriction in another way: for more information, see the Search georestriction instruction.type- object type, for exampletype=station.metroto search for metro stations.
Request example:
https://catalog.api.2gis.com/3.0/items?q=metro&point=37.630866,55.752256&radius=1000&type=station.metro&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.20949",
"code": 200,
"issue_date": "20260716"
},
"result": {
"items": [
{
"color": "#EA6A00",
"full_name": "Москва, Китай-город",
"id": "4504385606385733",
"name": "Китай-город",
"route_type": "metro",
"subtype": "metro",
"type": "station"
},
{
"color": "#E94282",
"full_name": "Москва, Курская",
"id": "4504385606390385",
"name": "Курская",
"route_type": "mcd",
"subtype": "railway",
"type": "station"
},
{
"color": "#3EA332",
"full_name": "Москва, Павелецкая",
"id": "4504385606385806",
"name": "Павелецкая",
"route_type": "metro",
"subtype": "metro",
"type": "station"
},
{
"color": "#E90101",
"full_name": "Москва, Чистые пруды",
"id": "4504385606385678",
"name": "Чистые пруды",
"route_type": "metro",
"subtype": "metro",
"type": "station"
},
{
"color": "#E90101",
"full_name": "Москва, Охотный Ряд",
"id": "4504385606385704",
"name": "Охотный Ряд",
"route_type": "metro",
"subtype": "metro",
"type": "station"
},
{
"color": "#0064AF",
"full_name": "Москва, Арбатская",
"id": "4504385606391042",
"name": "Арбатская",
"route_type": "metro",
"subtype": "metro",
"type": "station"
},
{
"color": "#912900",
"full_name": "Москва, Таганская",
"id": "4504385606391048",
"name": "Таганская",
"route_type": "metro",
"subtype": "metro",
"type": "station"
},
{
"color": "#3EA332",
"full_name": "Москва, Новокузнецкая",
"id": "4504385606385767",
"name": "Новокузнецкая",
"route_type": "metro",
"subtype": "metro",
"type": "station"
},
{
"color": "#E90101",
"full_name": "Москва, Лубянка",
"id": "4504385606388242",
"name": "Лубянка",
"route_type": "metro",
"subtype": "metro",
"type": "station"
},
{
"color": "#758190",
"full_name": "Москва, Цветной бульвар",
"id": "4504385606385980",
"name": "Цветной бульвар",
"route_type": "metro",
"subtype": "metro",
"type": "station"
}
],
"total": 38
}
}
By object ID
You can search for objects by their unique identifier (ID).
To find an object by its ID, send a GET request to /3.0/items/byid with the id parameter - object ID, for example id=70000001080081802. For more information on obtaining an ID, see the Obtaining object IDs instruction.
Request example:
https://catalog.api.2gis.com/3.0/items/byid?id=70000001080081802&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.20949",
"code": 200,
"issue_date": "20260703"
},
"result": {
"items": [
{
"address_name": "Театральная площадь, 2",
"id": "70000001080081802",
"name": "Большой театр России, касса",
"type": "branch"
}
],
"total": 1
}
}
By category ID
Using the rubric_id parameter, you can obtain a list of organizations in a particular category, for example, only cafes or only grocery stores.
To filter search results by organization category ID, send a GET request to /3.0/items with the following parameters:
q- text query, for example "coffee".location- search point coordinates in thelongitude,latitudeformat, for examplelocation=37.630866,55.752256. You can specify georestriction in another way: for more information, see the Search georestriction instruction.rubric_id- category ID, for examplerubric_id=161to obtain organizations in the "cafe" category. For more information on obtaining an ID, see the Category ID section.
Request example:
https://catalog.api.2gis.com/3.0/items?q=coffee&location=37.630866,55.752256&rubric_id=161&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.20926",
"code": 200,
"issue_date": "20260630"
},
"result": {
"items": [
{
"address_comment": "1 этаж",
"address_name": "Большой Спасоглинищевский переулок, 9/1 ст16",
"id": "70000001026155685",
"name": "Шоколадница, кофейня",
"type": "branch"
},
{
"address_comment": "-1 этаж",
"address_name": "площадь Революции, 2/3",
"id": "70000001027072965",
"name": "Шоколадница, кофейня",
"type": "branch"
},
{
"address_comment": "3 этаж",
"address_name": "Театральный проезд, 5 ст1",
"id": "70000001030845543",
"name": "Шоколадница, кофейня",
"type": "branch"
},
{
"address_comment": "вход со стороны бульвара Чистопрудный",
"address_name": "улица Макаренко, 2/21 ст3",
"id": "70000001094793829",
"name": "Рябчик, кафе",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Мясницкая улица, 13 ст24",
"id": "70000001059803455",
"name": "YourCoffeePlace, кофейня",
"type": "branch"
},
{
"address_comment": "1, мансардный этаж",
"address_name": "улица Кузнецкий Мост, 11 ст1",
"id": "4504128908695546",
"name": "Шоколадница, кофейня",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Серебрянический переулок, 6",
"id": "70000001087559992",
"name": "Флокс, кафе",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Чистопрудный бульвар, 1а",
"id": "4504128908438896",
"name": "Шоколадница, кофейня",
"type": "branch"
},
{
"address_comment": "-3 этаж; нижний уровень",
"address_name": "Манежная площадь, 1 ст2",
"id": "4504127908369683",
"name": "Кофе хауз, кофейня",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Калашный переулок, 4",
"id": "70000001105238772",
"name": "Зацепи кофе, кофейня",
"type": "branch"
}
],
"total": 100
}
}
By organization ID
Using the org_id parameter, you can obtain a list of all branches of a single organization, for example, only Russian Post branches. Organization IDs differ depending on the region.
To filter search results by organization ID, send a GET request to /3.0/items with the following parameters:
org_id- organization ID, for exampleorg_id=70000001087490185. For more information on obtaining an ID, see the Organization ID section.location- search point coordinates in thelongitude,latitudeformat, for examplelocation=37.630866,55.752256. You can specify georestriction in another way: for more information, see the Search georestriction instruction.
Request example:
https://catalog.api.2gis.com/3.0/items?org_id=70000001087490185&location=37.630866,55.752256&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.20926",
"code": 200,
"issue_date": "20260630"
},
"result": {
"items": [
{
"address_comment": "1 этаж; получение посылок со двора",
"address_name": "Никольская улица, 7-9 ст4",
"id": "4504127910758626",
"name": "Почта России, Отделение №109012",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Кадашёвская набережная, 36 ст1",
"id": "4504127908559993",
"name": "Почта России, отделение №115035",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Котельническая набережная, 1/15 к В",
"id": "4504127908550456",
"name": "Почта России, отделение №109240",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Мясницкая улица, 26а ст1",
"id": "4504127908535215",
"name": "Почта России, отделение №101000",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Варсонофьевский переулок, 4 ст1",
"id": "4504127908535893",
"name": "Почта России, отделение №107031",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Мясницкая улица, 26а ст1",
"id": "70000001077144940",
"name": "Почта России, отдел доставки",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Озерковский переулок, 13/19 ст1",
"id": "4504127908560137",
"name": "Почта России, отделение №115184",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "улица Большая Полянка, 3/9",
"id": "4504127908575819",
"name": "Почта России, отделение №119180",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "Тверская улица, 9 ст5",
"id": "4504127908593866",
"name": "Почта России, отделение №125009",
"type": "branch"
},
{
"address_comment": "1 этаж",
"address_name": "улица Большая Ордынка, 34-38",
"id": "4504127908575710",
"name": "Почта России, отделение №119017",
"type": "branch"
}
],
"total": 104
}
}
By brand ID
Using the brand_id parameter, you can obtain a list of all branches of a single organization that belong to a particular brand, for example, branches of a cinema chain.
To filter search results by organization brand ID, send a GET request to /3.0/items with the following parameters:
brand_id- brand ID, for examplebrand_id=70000001103777439. For more information on obtaining an ID, see the Brand ID section.location- search point coordinates in thelongitude,latitudeformat, for examplelocation=37.630866,55.752256. You can specify georestriction in another way: for more information, see the Search georestriction instruction.
Request example:
https://catalog.api.2gis.com/3.0/items?brand_id=70000001103777439&location=37.630866,55.752256&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.20949",
"code": 200,
"issue_date": "20260716"
},
"result": {
"items": [
{
"address_name": "улица Новый Арбат, 24",
"building_name": "Октябрь, кинотеатр",
"full_name": "Москва, Октябрь, кинотеатр",
"id": "4504127908582010",
"name": "Каро 11 Октябрь, кинотеатр",
"purpose_name": "Культурно-развлекательный комплекс",
"type": "branch"
},
{
"address_comment": "4 этаж",
"address_name": "улица Земляной Вал, 33",
"id": "70000001007350119",
"name": "Каро 7, кинотеатр",
"type": "branch"
},
{
"address_comment": "4 этаж",
"address_name": "Ходынский бульвар, 4",
"id": "70000001006919822",
"name": "Каро Sky 17, кинотеатр",
"type": "branch"
},
{
"address_comment": "3 этаж",
"address_name": "улица Юных Ленинцев, 52",
"id": "70000001059093722",
"name": "Каро 4 Высота, кинотеатр",
"type": "branch"
},
{
"address_comment": "4 этаж",
"address_name": "Сиреневый бульвар, 31",
"id": "70000001059093655",
"name": "Каро 10 София, кинотеатр",
"type": "branch"
},
{
"address_comment": "4 этаж",
"address_name": "Зелёный проспект, 81",
"id": "4504127908988906",
"name": "Каро, кинотеатр",
"type": "branch"
},
{
"address_comment": "6 этаж",
"address_name": "Щукинская улица, 42",
"id": "4504127908988914",
"name": "Каро 6, кинотеатр",
"type": "branch"
}
],
"total": 7
}
}
Searching for organizations
By building ID
You can obtain a list of organizations servicing a building:
- city service organizations: post office, clinic, housing services
- internet providers
To obtain a list of organizations servicing the building, send a GET request to /3.0/items/byservicing with the following parameters:
building_id- building ID, for examplebuilding_id=4504235282736775. For more information on obtaining an ID, see the Building ID section.servicing_group- servicing organization type, for exampleservicing_group=internetto search for internet providers. For the full list of servicing organization types, see the API Reference.
Request example:
https://catalog.api.2gis.com/3.0/items/byservicing?building_id=4504235282736775&servicing_group=internet&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260730"
},
"result": {
"items": [
{
"address_name": "Кудринская площадь, 1",
"full_name": "Москва, МТС",
"id": "70000001062946245",
"locale": "ru_RU",
"name": "МТС",
"name_ex": {
"primary": "МТС"
},
"org": {
"branch_count": 1872,
"id": "4504233727207446",
"name": "МТС"
},
"point": {
"lat": 55.758325,
"lon": 37.582394
},
"rubrics": [
{
"id": "164",
"kind": "primary",
"name": "Интернет-провайдер"
}
],
"type": "branch"
},
{
"address_name": "Кудринская площадь, 1",
"full_name": "Москва, Первые сети",
"id": "70000001072640517",
"locale": "ru_RU",
"name": "Первые сети",
"name_ex": {
"primary": "Первые сети"
},
"org": {
"branch_count": 1,
"id": "4504233727209134",
"name": "Первые сети"
},
"point": {
"lat": 55.758325,
"lon": 37.582394
},
"rubrics": [
{
"id": "164",
"kind": "primary",
"name": "Интернет-провайдер"
}
],
"type": "branch"
},
{
"address_name": "Кудринская площадь, 1",
"full_name": "Москва, Гиганет Телеком",
"id": "70000001053388243",
"locale": "ru_RU",
"name": "Гиганет Телеком",
"name_ex": {
"primary": "Гиганет Телеком"
},
"org": {
"branch_count": 1,
"id": "4504233727201837",
"name": "Гиганет Телеком"
},
"point": {
"lat": 55.758325,
"lon": 37.582394
},
"rubrics": [
{
"id": "164",
"kind": "primary",
"name": "Интернет-провайдер"
}
],
"type": "branch"
},
{
"address_name": "Кудринская площадь, 1",
"full_name": "Москва, Билайн",
"id": "4504136498294633",
"locale": "ru_RU",
"name": "Билайн",
"name_ex": {
"primary": "Билайн"
},
"org": {
"branch_count": 543,
"id": "4504233727198765",
"name": "Билайн"
},
"point": {
"lat": 55.758325,
"lon": 37.582394
},
"rubrics": [
{
"id": "164",
"kind": "primary",
"name": "Интернет-провайдер"
}
],
"type": "branch"
}
],
"total": 4
}
}
By website
To find an organization by its website address, send a GET request to /3.0/items/bysite with the site parameter - organization website address, for example site=2gis.ru.
Request example:
https://catalog.api.2gis.com/3.0/items/bysite?site=2gis.ru&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0",
"code": 200,
"issue_date": "20260703"
},
"result": {
"total": 1,
"items": [
{
"id": "70000001019528326",
"type": "branch",
"name_ex": {
"primary": "2ГИС",
"extension": "картографическая компания"
},
"org": {
"id": "70000001019528320",
"name": "2ГИС",
"branch_count": 42
},
"locale": "ru_RU",
"rubrics": [
{
"id": "4503",
"name": "Информационные технологии",
"kind": "primary"
},
{
"id": "4510",
"name": "Картография",
"kind": "additional"
}
],
"address_name": "Карла Маркса, 7",
"full_address_name": "Новосибирск, Карла Маркса, 7",
"point": {
"lon": 82.920430,
"lat": 55.028784
}
}
]
}
}
Using the fields=contact_groups parameter, you can obtain the contacts of the organization in the response. For more information, see the Additional information about objects instruction.
By phone number
To find an organization by its phone number, send a GET request to /3.0/items/byphone with the phone parameter - organization phone number, for example phone=+7(495)1234567.
Request example:
https://catalog.api.2gis.com/3.0/items/byphone?phone=+7(495)1234567&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0",
"code": 200,
"issue_date": "20260703"
},
"result": {
"total": 2,
"items": [
{
"id": "70000001062498741",
"type": "branch",
"name_ex": {
"primary": "Альфа-Банк",
"extension": "банкомат"
},
"org": {
"id": "70000001062498740",
"name": "Альфа-Банк",
"branch_count": 1523
},
"locale": "ru_RU",
"rubrics": [
{
"id": "2780",
"name": "Банки",
"kind": "primary"
},
{
"id": "2784",
"name": "Банкоматы",
"kind": "additional"
}
],
"address_name": "Тверская, 12",
"full_address_name": "Москва, Тверская, 12",
"point": {
"lon": 37.604152,
"lat": 55.764013
}
},
...
]
}
}
Using the fields=contact_groups parameter, you can obtain the contacts of the organization in the response. For more information, see the Additional information about objects instruction.
By ITIN
To find an organization by its individual taxpayer identification number (ITIN), send a GET request to /3.0/items/byitin with the itin parameter - individual taxpayer identification number of the organization, for example itin=123456789100.
Request example:
https://catalog.api.2gis.com/3.0/items/byitin?itin=123456789100&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0",
"code": 200,
"issue_date": "20260703"
},
"result": {
"total": 1,
"items": [
{
"id": "70000001041253891",
"type": "branch",
"name_ex": {
"primary": "Ромашка",
"extension": "продуктовый магазин",
"legal_name": "ООО Ромашка"
},
"org": {
"id": "70000001019528320",
"name": "Ромашка",
"branch_count": 5
},
"locale": "ru_RU",
"rubrics": [
{
"id": "2436",
"name": "Продуктовые магазины",
"kind": "primary"
}
],
"address_name": "Арбат, 36/2с1",
"full_address_name": "Москва, Арбат, 36/2с1",
"point": {
"lon": 37.589531,
"lat": 55.749204
},
"itin": "123456789100"
}
]
}
}
Using the fields=items.itin parameter, you can obtain the individual taxpayer identification number of the organization in the response. For more information, see the Additional information about objects instruction.
By trade license
To find an organization by its trade license number, send a GET request to /3.0/items/bytradelicense with the trade_license parameter - trade license number of the organization, for example trade_license=CN-1234567.
Request example:
https://catalog.api.2gis.com/3.0/items/bytradelicense?trade_license=CN-1234567&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0",
"code": 200,
"issue_date": "20260703"
},
"result": {
"total": 1,
"items": [
{
"id": "70000001058764219",
"type": "branch",
"name_ex": {
"primary": "Golden Palm Trading",
"extension": "trading company",
"legal_name": "Golden Palm Trading LLC"
},
"org": {
"id": "70000001058764200",
"name": "Golden Palm Trading",
"branch_count": 3
},
"locale": "en_AE",
"rubrics": [
{
"id": "5120",
"name": "Trading companies",
"kind": "primary"
},
{
"id": "5135",
"name": "Import and export",
"kind": "additional"
}
],
"trade_license": {
"license": "CN-1234567",
"type": "Commercial",
"type_description": "Active",
"legal_form": "Limited Liability Company",
"director_name": "Ahmed Al Maktoum",
"start_date": "2022-03-15",
"end_date": "2027-03-14"
},
"address_name": "Sheikh Zayed Road, 45",
"full_address_name": "Dubai, Sheikh Zayed Road, 45",
"point": {
"lon": 55.274288,
"lat": 25.197197
}
}
]
}
}
Using the fields=items.trade_license parameter, you can obtain the trade license number of the organization in the response. For more information, see the Additional information about objects instruction.
By FIAS code
To find an organization by its code in the Federal Information Address System (FIAS), send a GET request to /3.0/items/byfias with the fias_code parameter - code of the object in the Federal Information Address System, for example fias_code=a7f3b2c1-4d5e-6f78-9a0b-1c2d3e4f5a6b.
Request example:
https://catalog.api.2gis.com/3.0/items/byfias?fias_code=a7f3b2c1-4d5e-6f78-9a0b-1c2d3e4f5a6b&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0",
"code": 200,
"issue_date": "20260703"
},
"result": {
"total": 1,
"items": [
{
"id": "141265769342587",
"type": "building",
"caption": "ул. Тверская, 18к1",
"purpose_name": "Офисное здание",
"address_name": "Тверская, 18к1",
"full_address_name": "Москва, Тверская, 18к1",
"building_name": "Бизнес-центр Тверской",
"full_name": "Тверская, 18к1",
"locale": "ru_RU",
"point": {
"lon": 37.603856,
"lat": 55.763410
},
"address": {
"building_id": "141265769342587",
"postcode": "125009",
"components": [
{
"type": "street_number",
"street_id": "141265769336100",
"street": "Тверская",
"number": "18к1",
"fias_code": "b4e7c8d2-9f1a-4e3b-8d5c-6a2f7b9e0d1c"
}
]
},
"geometry": {
"centroid": "POINT(37.603856 55.763410)"
}
}
]
}
}
Using the fields=items.fias_code and fields=items.address.components.fias_code parameters, you can obtain the organization code in the Federal Information Address System in the response. For more information, see the Additional information about objects instruction.