Сервис возвращает административную иерархию для заданной точки на карте: страну, регион и населённый пункт. Полезен для получения структурированного контекста местоположения без полного адреса.
| Параметр | Тип | По умолчанию | Описание | Пример |
|---|---|---|---|---|
location |
string | — | Координаты точки lat,lon для определения иерархии. |
location=54.999903,73.402887 |
fields |
string | — | Поля ответа: address_details, pin, bbox, geometry, type, ref. |
fields=ref,pin |
radius |
integer (м) | — | Радиус поиска. | radius=1000 |
geometry |
enum | full |
Детализация геометрии: none, full, packed6. |
geometry=none |
format |
enum | default |
Формат ответа: default или geojson. |
format=geojson |
query_status |
boolean | false |
Включить статус внутренних запросов. | query_status=true |
verbose_debug |
boolean | false |
Расширенная отладочная информация. | |
extra |
boolean | false |
Доп. поля: ssid, location_id. |
| Поле | Тип | Описание |
|---|---|---|
request |
string | Строка исходного запроса |
results |
array | Массив объектов иерархии |
Каждый элемент results содержит ключи административной иерархии:
| Ключ | Описание |
|---|---|
country |
Страна |
region |
Регион / область |
locality |
Населённый пункт |
Каждый из них содержит:
| Поле | Тип | Описание |
|---|---|---|
ref |
string | ID объекта |
pin |
[lon, lat] | Координаты центра объекта |
locales |
object | Названия объекта на разных языках |
locales.{lang}.name |
string | Название |
locales.{lang}.official_name |
string | Официальное название |
locales.{lang}.address |
object | Адресные компоненты |
Запрос:
/api/hierarchy?location=54.999903,73.402887&fields=ref,pin,locales
Ответ:
{
"request": "/api/hierarchy?location=54.999903,73.402887&fields=ref,pin,locales",
"results": [
{
"country": {
"locales": {
"default": {
"address": { "country": "Россия" },
"name": "Россия",
"official_name": "Российская Федерация"
},
"en": {
"address": { "country": "Russia" },
"name": "Russia",
"official_name": "Russian Federation"
}
},
"pin": [97.745306, 64.686314],
"ref": "030000000000EB1D"
},
"region": {
"locales": {
"default": {
"address": { "region": "Омская область" },
"name": "Омская область"
}
},
"pin": [73.402887, 54.999903],
"ref": "..."
},
"locality": {
"locales": {
"default": {
"address": { "locality": "Омск" },
"name": "Омск"
}
},
"pin": [73.368212, 54.989342],
"ref": "..."
}
}
]
}
{
"openapi": "3.0.0",
"info": {
"title": "Геокодер — Hierarchy API",
"version": "5.0.0"
},
"paths": {
"/api/hierarchy": {
"get": {
"summary": "Иерархия локаций (v3)",
"description": "Возвращает административную иерархию (страна, регион, город) для заданной точки.",
"tags": ["Hierarchy"],
"parameters": [
{
"name": "location",
"in": "query",
"description": "Координаты точки lat,lon",
"schema": { "type": "string", "example": "54.999903,73.402887" }
},
{
"name": "fields",
"in": "query",
"description": "Поля ответа для каждого уровня иерархии",
"schema": {
"type": "string",
"example": "ref,pin,locales",
"enum": ["address_details", "address", "pin", "bbox", "geometry", "entrances", "type", "ref", "user_pin"]
}
},
{
"name": "radius",
"in": "query",
"schema": { "type": "integer", "example": 1000 }
},
{
"name": "geometry",
"in": "query",
"schema": { "type": "string", "enum": ["none", "full", "packed6"], "default": "full" }
},
{
"name": "format",
"in": "query",
"schema": { "type": "string", "enum": ["default", "geojson"], "default": "default" }
},
{
"name": "query_status",
"in": "query",
"schema": { "type": "boolean", "default": false }
},
{
"name": "verbose_debug",
"in": "query",
"schema": { "type": "boolean", "default": false }
},
{
"name": "extra",
"in": "query",
"schema": { "type": "boolean", "default": false }
}
],
"responses": {
"200": {
"description": "Иерархия административных объектов для точки",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"request": { "type": "string" },
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country": {
"type": "object",
"properties": {
"ref": { "type": "string" },
"pin": { "type": "array", "items": { "type": "number" } },
"locales": { "type": "object" }
}
},
"region": { "type": "object" },
"locality": { "type": "object" }
}
}
}
}
}
}
}
},
"400": { "description": "Некорректный запрос" }
}
}
},
"/api/hierarchy": {
"get": {
"summary": "Иерархия локаций (v5)",
"description": "Актуальная версия иерархии административных объектов.",
"tags": ["Hierarchy"],
"parameters": [
{ "name": "location", "in": "query", "schema": { "type": "string" } },
{ "name": "fields", "in": "query", "schema": { "type": "string" } },
{ "name": "radius", "in": "query", "schema": { "type": "integer" } },
{ "name": "geometry", "in": "query", "schema": { "type": "string", "enum": ["none", "full", "packed6"] } },
{ "name": "format", "in": "query", "schema": { "type": "string", "enum": ["default", "geojson"] } },
{ "name": "query_status", "in": "query", "schema": { "type": "boolean" } },
{ "name": "verbose_debug", "in": "query", "schema": { "type": "boolean" } },
{ "name": "extra", "in": "query", "schema": { "type": "boolean" } }
],
"responses": {
"200": { "description": "Иерархия административных объектов" },
"400": { "description": "Некорректный запрос" }
}
}
}
}
}