Skip to main content

Obtaining object IDs

Depending on the task, some requests may require the ID of an object: a building, organization, city, etc. To obtain the object ID, send a GET request to /3.0/items and specify the object type in the type parameter. For a full list of types, see the API Reference.

Below are request examples for obtaining IDs of different objects.

Category ID​

Category IDs differ across regions. To search for organizations in the required category, first obtain the region ID, then the category ID, and then filter the search results by the organization category. To send the request, the key needs access to the Regions API and the Categories API.

To obtain the category ID, send a GET request to Categories API to /2.0/catalog/rubric/search with the following parameters:

  • q - text query, for example q=cafe.
  • region_id - region ID, for example region_id=32. For more information on obtaining an ID, see the Region ID section.

Request example:

https://catalog.api.2gis.com/2.0/catalog/rubric/search?q=cafe&region_id=32&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "2.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "alias": "kafe",
                "branch_count": 6624,
                "caption": "Кафе",
                "id": "161",
                "keyword": "Кафе",
                "name": "Кафе",
                "org_count": 5321,
                "parent_id": "2",
                "title": "Кафе",
                "type": "rubric"
            },
            {
                "alias": "bystroe_pitanie",
                "branch_count": 14324,
                "caption": "Быстрое питание",
                "id": "165",
                "keyword": "Быстрое питание",
                "name": "Быстрое питание",
                "org_count": 8323,
                "parent_id": "2",
                "seo_name": "Кафе / рестораны быстрого питания (фаст-фуды)",
                "title": "Быстрое питание",
                "type": "rubric"
            },
            {
                "alias": "kofejjni",
                "branch_count": 3624,
                "caption": "Кофейни",
                "id": "162",
                "keyword": "Кофейни",
                "name": "Кофейни",
                "org_count": 2143,
                "parent_id": "2",
                "title": "Кофейни",
                "type": "rubric"
            },
            {
                "alias": "kafe_konditerskie",
                "branch_count": 485,
                "caption": "Кафе-кондитерские",
                "id": "112658",
                "keyword": "Кафе-кондитерские",
                "name": "Кафе-кондитерские",
                "org_count": 189,
                "parent_id": "2",
                "title": "Кафе-кондитерские",
                "type": "rubric"
            },
            {
                "alias": "zookafe",
                "branch_count": 38,
                "caption": "Зоокафе",
                "id": "113573",
                "keyword": "Зоокафе",
                "name": "Зоокафе",
                "org_count": 32,
                "parent_id": "2",
                "title": "Зоокафе",
                "type": "rubric"
            },
            {
                "alias": "keramicheskaya_plitka",
                "branch_count": 1310,
                "caption": "Керамическая плитка",
                "id": "538",
                "keyword": "Керамическая плитка",
                "name": "Керамическая плитка",
                "org_count": 972,
                "parent_id": "42867",
                "seo_name": "Керамическая / кафельная плитка",
                "title": "Керамическая плитка",
                "type": "rubric"
            },
            {
                "alias": "kompyuternye_kluby",
                "branch_count": 810,
                "caption": "Компьютерные клубы",
                "id": "178",
                "keyword": "Компьютерные клубы",
                "name": "Компьютерные клубы",
                "org_count": 372,
                "parent_id": "19532",
                "seo_name": "Интернет-кафе / Игровые, компьютерные клубы",
                "title": "Компьютерные клубы",
                "type": "rubric"
            },
            {
                "alias": "karaoke_zaly",
                "branch_count": 513,
                "caption": "Караоке",
                "id": "21387",
                "keyword": "Караоке-залы",
                "name": "Караоке-залы",
                "org_count": 468,
                "parent_id": "2",
                "seo_name": "Караоке-клубы / бары",
                "title": "Караоке",
                "type": "rubric"
            },
            {
                "alias": "centry_parovykh_koktejjlejj",
                "branch_count": 1144,
                "caption": "Паровые коктейли",
                "id": "110357",
                "keyword": "Центры паровых коктейлей",
                "name": "Центры паровых коктейлей",
                "org_count": 785,
                "parent_id": "2",
                "title": "Паровые коктейли",
                "type": "rubric"
            }
        ],
        "total": 9
    }
}

Copy the category ID from the result.items.id field.

Organization ID​

To obtain the organization ID, send a GET request to /3.0/items with the following parameters:

  • q - text query, for example "russian post".
  • location - search point coordinates in the longitude,latitude format, for example location=37.630866,55.752256. You can specify georestriction in another way: for more information, see the Search georestriction instruction.
  • fields=items.org - includes the organization ID field in the response.
  • type=branch - search for objects with the "branch" type.

Request example:

https://catalog.api.2gis.com/3.0/items?q=russian post&location=37.630866,55.752256&fields=items.org&type=branch&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "address_name": "Ильинка улица, 9 ст1",
                "id": "4504127908543317",
                "name": "Почта России, отделение №103132",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            },
            {
                "address_comment": "1 этаж; получение посылок со двора",
                "address_name": "Никольская улица, 7-9 ст4",
                "id": "4504127910758626",
                "name": "Почта России, отделение №109012",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Кадашёвская набережная, 36 ст1",
                "id": "4504127908559993",
                "name": "Почта России, отделение №115035",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Котельническая набережная, 1/15 к В",
                "id": "4504127908550456",
                "name": "Почта России, отделение №109240",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Мясницкая улица, 26а ст1",
                "id": "4504127908535215",
                "name": "Почта России, отделение №101000",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Варсонофьевский переулок, 4 ст1",
                "id": "4504127908535893",
                "name": "Почта России, отделение №107045",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Мясницкая улица, 26а ст1",
                "id": "70000001077144940",
                "name": "Почта России, отделение №101000",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Озерковский переулок, 13/19 ст1",
                "id": "4504127908560137",
                "name": "Почта России, отделение №115184",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "Берсеневская набережная, 20/2",
                "id": "4504127908575769",
                "name": "Почта России, отделение №119072",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            },
            {
                "address_comment": "1 этаж",
                "address_name": "улица Большая Полянка, 3/9",
                "id": "4504127908575819",
                "name": "Почта России, отделение №119180",
                "org": {
                    "branch_count": 1208,
                    "id": "70000001087490185",
                    "name": "Почта России",
                    "primary": "Почта России"
                },
                "type": "branch"
            }
        ],
        "total": 87
    }
}

Copy the organization ID from the result.items.org.id field.

Brand ID​

To obtain the brand ID, send a GET request to /3.0/items with the following parameters:

  • q - text query, for example "karo cinema".
  • location - search point coordinates in the longitude,latitude format, for example location=37.630866,55.752256. You can specify georestriction in another way: for more information, see the Search georestriction instruction.
  • fields=items.brand - includes the brand ID field in the response.
  • type=branch - search for objects with the "branch" type.

Request example:

https://catalog.api.2gis.com/3.0/items?q=karo cinema&location=37.630866,55.752256&fields=items.brand&type=branch&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Новый Арбат, 24",
                "brand": {
                    "branch_count": 14,
                    "extension": "кинотеатр",
                    "id": "70000001103777439",
                    "name": "Каро"
                },
                "building_name": "Октябрь, кинотеатр",
                "full_name": "Москва, Октябрь, кинотеатр",
                "id": "4504127908582010",
                "name": "Каро 11 Октябрь, кинотеатр",
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "branch"
            },
            {
                "address_comment": "4 этаж",
                "address_name": "улица Земляной Вал, 33",
                "brand": {
                    "branch_count": 14,
                    "extension": "кинотеатр",
                    "id": "70000001103777439",
                    "name": "Каро"
                },
                "id": "70000001007350119",
                "name": "Каро 7, кинотеатр",
                "type": "branch"
            },
            {
                "address_comment": "4 этаж",
                "address_name": "Ходынский бульвар, 4",
                "brand": {
                    "branch_count": 14,
                    "extension": "кинотеатр",
                    "id": "70000001103777439",
                    "name": "Каро"
                },
                "id": "70000001006919822",
                "name": "Каро Sky 17, кинотеатр",
                "type": "branch"
            },
            {
                "address_comment": "3 этаж",
                "address_name": "улица Юных Ленинцев, 52",
                "brand": {
                    "branch_count": 14,
                    "extension": "кинотеатр",
                    "id": "70000001103777439",
                    "name": "Каро"
                },
                "id": "70000001059093722",
                "name": "Каро 4 Высота, кинотеатр",
                "type": "branch"
            },
            {
                "address_comment": "4 этаж",
                "address_name": "Сиреневый бульвар, 31",
                "brand": {
                    "branch_count": 14,
                    "extension": "кинотеатр",
                    "id": "70000001103777439",
                    "name": "Каро"
                },
                "id": "70000001059093655",
                "name": "Каро 10 София, кинотеатр",
                "type": "branch"
            },
            {
                "address_comment": "4 этаж",
                "address_name": "Зелёный проспект, 81",
                "brand": {
                    "branch_count": 14,
                    "extension": "кинотеатр",
                    "id": "70000001103777439",
                    "name": "Каро"
                },
                "id": "4504127908988906",
                "name": "Каро, кинотеатр",
                "type": "branch"
            },
            {
                "address_comment": "6 этаж",
                "address_name": "Щукинская улица, 42",
                "brand": {
                    "branch_count": 14,
                    "extension": "кинотеатр",
                    "id": "70000001103777439",
                    "name": "Каро"
                },
                "id": "4504127908988914",
                "name": "Каро 6, кинотеатр",
                "type": "branch"
            }
        ],
        "total": 7
    }
}

Copy the brand ID from the result.items.brand.id field.

Building ID​

To obtain the building ID, send a GET request to /3.0/items with the following parameters:

  • q - text query with georestriction, for example "kadashevskaya naberezhnaya 12 moscow". You can specify georestriction in another way: for more information, see the Search georestriction instruction.
  • type=building - search for objects with the "building" type.

Request example:

https://catalog.api.2gis.com/3.0/items?q=kadashevskaya naberezhnaya 12 moscow&type=building&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "address_name": "Кадашёвская набережная, 12",
                "full_name": "Москва, Кадашёвская набережная, 12",
                "id": "4504235299048514",
                "name": "Кадашёвская набережная, 12",
                "purpose_name": "Музей",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Copy the building ID from the result.items.id field.

Parking lot ID​

To obtain the parking lot ID, send a GET request to /3.0/items with the following parameters:

Request example:

https://catalog.api.2gis.com/3.0/items?q=okhotny ryad moscow&type=parking&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "address_name": "площадь Революции, 3",
                "full_name": "Москва, Парковка ТЦ Охотный ряд",
                "id": "4504656201068202",
                "name": "Парковка ТЦ Охотный ряд",
                "subtype": "underground",
                "type": "parking"
            }
        ],
        "total": 1
    }
}

Copy the parking ID from the result.items.id field.

Metro station ID​

To obtain the metro station ID, send a GET request to /3.0/items with the following parameters:

  • q - text query, for example "universitet".
  • location - search point coordinates in the longitude,latitude format, for example location=37.630866,55.752256. You can specify georestriction in another way: for more information, see the Search georestriction instruction.
  • type=station.metro - search for objects with "metro station" type.

Request example:

https://catalog.api.2gis.com/3.0/items?q=universitet&location=37.630866,55.752256&type=station.metro&key=API_KEY

Response example:

response.json
{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260730"
    },
    "result": {
        "items": [
            {
                "color": "#E90101",
                "full_name": "Москва, Университет",
                "id": "4504385606390686",
                "name": "Университет",
                "route_type": "metro",
                "subtype": "metro",
                "type": "station"
            }
        ],
        "total": 1
    }
}

Copy the metro station ID from the result.items.id field.

Place ID​

Places are area objects: parks, beaches, recreational areas, lakes, and other locations.

To obtain the place ID, send a GET request to /3.0/items using one of the following methods:

  • specify the place name, for example q=vdnh moscow:

    https://catalog.api.2gis.com/3.0/items?q=vdnh moscow&type=adm_div.place&key=API_KEY

  • specify the longitude and latitude of a point, for example lon=37.637635&lat=55.826241:

    https://catalog.api.2gis.com/3.0/items?lon=37.637635&lat=55.826241&type=adm_div.place&key=API_KEY

Specify type=adm_div.place in the request to search for objects with the "place" type.

Response example:

response.json
{
   "meta": {
      "api_version": "3.0.20949",
      "code": 200,
      "issue_date": "20260716"
   },
   "result": {
      "items": [
            {
               "full_name": "Москва, Выставка достижений народного хозяйства",
               "id": "4504286822138302",
               "name": "Выставка достижений народного хозяйства",
               "subtype": "place",
               "type": "adm_div"
            }
      ],
      "total": 1
   }
}

Copy the place ID from the result.items.id field.

District ID​

To obtain the district ID, send a GET request to /3.0/items using one of the following methods:

  • specify the district name, for example q=moscow yakimanka:

    https://catalog.api.2gis.com/3.0/items?q=moscow yakimanka&type=adm_div.district&key=API_KEY

  • specify the longitude and latitude of a point, for example lon=37.606357&lat=55.735467:

    https://catalog.api.2gis.com/3.0/items?lon=37.606357&lat=55.735467&type=adm_div.district&key=API_KEY

Specify type=adm_div.district in the request to search for objects with the "district" type.

Response example:

response.json
{
   "meta": {
      "api_version": "3.0.20926",
      "code": 200,
      "issue_date": "20260701"
   },
   "result": {
      "items": [
            {
               "full_name": "Москва, Якиманка",
               "id": "4504209512726534",
               "name": "Якиманка",
               "subtype": "district",
               "type": "adm_div"
            }
      ],
      "total": 1
   }
}

Copy the district ID from the result.items.id field.

City ID​

To obtain the city ID, send a GET request to /3.0/items using one of the following methods:

  • specify the city name, for example q=Moscow:

    https://catalog.api.2gis.com/3.0/items?q=Moscow&type=adm_div.city&key=API_KEY

  • specify the longitude and latitude of a point, for example lon=37.630866&lat=55.752256:

    https://catalog.api.2gis.com/3.0/items?lon=37.630866&lat=55.752256&type=adm_div.city&key=API_KEY

Specify type=adm_div.city in the request to search for objects with the "city" type.

Response example:

response.json
{
   "meta": {
      "api_version": "3.0.20926",
      "code": 200,
      "issue_date": "20260701"
   },
   "result": {
      "items": [
            {
               "full_name": "Москва",
               "id": "4504222397630173",
               "name": "Москва",
               "subtype": "city",
               "type": "adm_div"
            }
      ],
      "total": 1
   }
}

Copy the city ID from the result.items.id field.

Region ID​

To send the request, the key needs access to the Regions API.

To obtain the region ID, send a GET request to Regions API to /2.0/region/search using one of the following methods:

  • specify the region name, for example q=Moscow:

    https://catalog.api.2gis.com/2.0/region/search?q=Moscow&key=API_KEY

  • specify the point coordinates, for example q=37.630866,55.752256:

    https://catalog.api.2gis.com/2.0/region/search?q=37.630866,55.752256&key=API_KEY

Response example:

response.json
{
   "meta": {
      "api_version": "2.0.20926",
      "code": 200,
      "issue_date": "20260630"
   },
   "result": {
      "items": [
            {
               "id": "32",
               "name": "Москва",
               "type": "region"
            }
      ],
      "total": 1
   }
}

Copy the region ID from the result.items.id field.