Сервис позволяет:
| Параметр | Тип | По умолчанию | Описание | Пример |
|---|---|---|---|---|
q |
string | — | Почтовый индекс, ref-идентификатор адреса или текстовый адрес. | q=117216 / q=0200000001904886 / q=Москва Арбат 1 |
addresses |
enum | short |
Формат поля addresses в ответе: short — краткое иерархическое представление. |
addresses=short |
isocode |
2-char | — | Код страны по ISO 3166-1 alpha-2. | isocode=RU |
fields |
string | — | Дополнительные поля: postoffice — информация об отделении Почты России. |
fields=postoffice |
| Поле | Тип | Описание |
|---|---|---|
results |
array | Массив найденных почтовых индексов |
Каждый элемент results:
| Поле | Тип | Описание |
|---|---|---|
postcode |
string | Почтовый индекс |
addresses |
object | Иерархический список адресов, использующих этот индекс |
addresses.country |
string | Страна |
addresses.region |
string | Регион |
addresses.subregion |
string | Административный район |
addresses.localities |
array | Список населённых пунктов |
addresses.localities[].name |
string | Название населённого пункта |
addresses.localities[].streets |
array | Улицы в этом населённом пункте с данным индексом |
addresses.localities[].streets[].name |
string | Название улицы |
addresses.localities[].streets[].buildings |
array | Список домов |
Поле postoffice (при fields=postoffice, только Россия):
| Поле | Тип | Описание |
|---|---|---|
ref |
string | ID отделения |
pin |
[lon, lat] | Координаты отделения |
address |
string | Адрес отделения |
Запрос:
/api/postcode?q=117216
Ответ:
{
"results": [
{
"addresses": {
"country": "Россия",
"localities": [
{
"name": "Москва",
"streets": [
{
"buildings": ["22 с1"],
"name": "Старокачаловская улица"
}
]
}
],
"region": "Москва",
"subregion": "Юго-Западный административный округ"
},
"postcode": "117216"
}
]
}
Запрос:
/api/postcode?q=Москва Старокачаловская 22&fields=postoffice
{
"openapi": "3.0.0",
"info": {
"title": "Геокодер — Postcode API",
"version": "1.0.0"
},
"paths": {
"/api/postcode": {
"get": {
"summary": "Поиск по почтовому индексу",
"description": "Позволяет найти адреса по индексу, определить индекс по адресу, а для России — получить данные отделения Почты России.",
"tags": ["Postcode"],
"parameters": [
{
"name": "q",
"in": "query",
"description": "Почтовый индекс, ref объекта или текстовый адрес",
"schema": { "type": "string", "example": "117216" }
},
{
"name": "addresses",
"in": "query",
"description": "Формат вывода адресов",
"schema": { "type": "string", "enum": ["short"], "default": "short" }
},
{
"name": "isocode",
"in": "query",
"description": "Код страны (ISO 3166-1 alpha-2)",
"schema": { "type": "string", "minLength": 2, "maxLength": 2, "example": "RU" }
},
{
"name": "fields",
"in": "query",
"description": "Дополнительные поля: postoffice — информация об отделении Почты России (только RU)",
"schema": { "type": "string", "example": "postoffice" }
}
],
"responses": {
"200": {
"description": "Результаты поиска почтового индекса",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"postcode": { "type": "string" },
"addresses": {
"type": "object",
"properties": {
"country": { "type": "string" },
"region": { "type": "string" },
"subregion": { "type": "string" },
"localities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"streets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"buildings": {
"type": "array",
"items": { "type": "string" }
}
}
}
}
}
}
}
}
},
"postoffice": {
"type": "object",
"description": "Информация об отделении Почты России (только при fields=postoffice)",
"properties": {
"ref": { "type": "string" },
"pin": { "type": "array", "items": { "type": "number" } },
"address": { "type": "string" }
}
}
}
}
}
}
},
"example": {
"results": [
{
"addresses": {
"country": "Россия",
"localities": [
{
"name": "Москва",
"streets": [
{ "buildings": ["22 с1"], "name": "Старокачаловская улица" }
]
}
],
"region": "Москва",
"subregion": "Юго-Западный административный округ"
},
"postcode": "117216"
}
]
}
}
}
},
"400": { "description": "Некорректный запрос" }
}
}
}
}
}