Партнёрский API «Моего участка»
Один запрос по кадастровому номеру земельного участка. Ответ в JSON содержит доступные характеристики, контур в WGS 84 и координаты в МСК с отметкой калибровки.
Выдадим адрес API, логин и токен по запросу через Telegram-бот.
Запросить доступ в Telegram1. Как получить доступ
Откройте Telegram-бот «Мой участок», нажмите «Старт» и напишите «Нужен доступ к API». Укажите компанию, задачу интеграции и ожидаемое число запросов.
После согласования команда выдаёт адрес API, логин и токен и сообщает лимиты. Доступ действует в согласованном диапазоне дат. Последний день включён целиком по Москве. При перевыпуске старый токен перестаёт принимать новые запросы, а даты доступа сохраняются.
2. Запрос участка
Метод GET. Адрес API v1 выдадим по запросу.
Шаблон адреса https://ХХХ.ХХХ.ХХХ.ХХХ/moj_uchastok/api/partners/v1/parcel.
Единственный параметр cad содержит кадастровый номер. Передавайте его строкой с двоеточиями и ведущими нулями. Четыре части содержат соответственно от 1 до 2, от 1 до 2, от 1 до 7 и от 1 до 12 цифр. Один запрос относится к одному участку.
Авторизация — HTTP Basic поверх HTTPS. Передайте один заголовок Authorization. Логин используется как имя пользователя, токен — как пароль. Пример ниже запрашивает токен интерактивно.
При ручной сборке запроса формат заголовка Authorization: Basic BASE64(логин:токен). Библиотека HTTP Basic обычно формирует его из пары логин и пароль.
API_URL='https://ХХХ.ХХХ.ХХХ.ХХХ/moj_uchastok/api/partners/v1/parcel'
curl --user "$PARTNER_LOGIN" --get \
--data-urlencode 'cad=69:44:0000000:1' \
-H 'Accept: application/json' \
"$API_URL"
Перед запуском примера подставьте в API_URL выданный HTTPS-адрес операции без query-параметров, а в PARTNER_LOGIN — выданный логин. Замените демонстрационный кадастровый номер на нужный. Токен передавайте в заголовке авторизации и храните в секретах серверного приложения.
3. Успешный ответ
HTTP 200 возвращает объект data. Ниже демонстрационный пример структуры. Значения участка приведены для иллюстрации.
{
"data": {
"cadastralNumber": "69:44:0000000:1",
"address": "Тестовый адрес",
"registeredAreaM2": 900,
"cadastralValueRub": 175000,
"cadastralValueRecordedOn": null,
"cadastralQuarter": "69:44:0000000",
"registrationStatus": null,
"registeredOn": null,
"landCategory": null,
"permittedUse": null,
"boundaryStatus": "available",
"wgs84": {
"type": "Polygon",
"coordinates": [[
[32.77742469442311, 56.209083630936256],
[32.77746367497291, 56.209102488403204],
[32.777701713358425, 56.20918993719917],
[32.77742469442311, 56.209083630936256]
]]
},
"msk": {
"status": "ready",
"zoneId": "69:1",
"system": "МСК-69",
"zone": 1,
"calibrated": true,
"polygons": [[[
{"northing": 219095.92, "easting": 1268372.68},
{"northing": 219098.03, "easting": 1268375.09},
{"northing": 219107.83, "easting": 1268389.82},
{"northing": 219095.92, "easting": 1268372.68}
]]]
},
"stale": false
}
}
| Поле | Тип и значение |
|---|---|
cadastralNumber | Строка. Кадастровый номер из запроса. |
cadastralQuarter, address | Строка или null. Номер квартала и адрес либо описание местоположения. |
registeredAreaM2 | Число или null. Учётная площадь в м². |
cadastralValueRub | Число или null. Кадастровая стоимость в рублях. |
cadastralValueRecordedOn, registeredOn | Строка в формате источника или null. Дата внесения стоимости и дата постановки на учёт. |
registrationStatus, landCategory, permittedUse | Строка или null. Статус объекта, категория земель и разрешённое использование. |
boundaryStatus | available или unavailable. Доступность границы. |
wgs84 | Объект GeoJSON Polygon, MultiPolygon или null. |
msk | Объект со статусом пересчёта и отметкой калибровки. Поля координат доступны при status: "ready". |
stale | Булево значение. true, если источник явно отметил, что данные не удалось обновить при временном сбое. |
Если источник подтвердил отсутствие контура, ответ может содержать доступные атрибуты при 200, boundaryStatus: "unavailable" и wgs84: null.
4. Координаты и калибровка МСК
- WGS 84 в градусах. GeoJSON хранит позицию как
[долгота, широта]. ДляPolygonструктураcoordinates[ring][vertex], дляMultiPolygon—coordinates[polygon][ring][vertex]. - В МСК
northing— X (север),easting— Y (восток). Значения в метрах округлены до 0,01 м. Структура всегдаmsk.polygons[polygon][ring][vertex]. - В каждом полигоне первое кольцо внешнее, остальные описывают отверстия. Кольца замкнуты повтором первой вершины. При доступности обеих систем порядок колец и вершин совпадает.
| Статус | Что получает клиент |
|---|---|
ready | system — название системы, zone — номер зоны, zoneId — идентификатор вида 69:1, calibrated — true для калиброванной зоны или false для расчёта по базовым параметрам, polygons — координаты. |
boundary_unavailable | Контур недоступен. calibrated: null. |
zone_unavailable | WGS 84 доступна, пересчёт для зоны недоступен. calibrated: null. |
Отметка калибровки описывает параметры зоны. Точность исходной геометрии зависит от сведений источника.
5. Ошибки, лимиты и повторы
Ошибка имеет структуру {"error":{"code":"invalid_credentials"}}. В обработчике клиента используйте HTTP-статус вместе с error.code.
| HTTP | Код | Действие |
|---|---|---|
| 400 | invalid_cadastral_number | Проверьте номер и убедитесь, что параметр cad передан один раз. |
| 401 | invalid_credentials | Проверьте логин, токен, статус и даты доступа. |
| 404 | parcel_not_returned, route_not_found | Для первого кода уточните номер или наличие сведений. Для второго проверьте выданный URL. |
| 405 | method_not_allowed | Используйте GET. |
| 429 | partner_limit, partner_busy, source_busy, edge_limit | Дождитесь числа секунд из Retry-After. Сократите параллельные обращения. |
| 502 | parcel_source_unavailable, invalid_source_response, invalid_source_geometry | Покажите временную ошибку. Повторяйте с паузой и ограничением числа попыток. |
| 503 | parcel_source_unavailable | Повторите после интервала из Retry-After. |
| 500 | internal_error | При повторении сообщите команде время запроса, HTTP-статус и код ошибки. |
Минутный лимит задаётся для каждого логина. Некоторые неуспешные запросы с действующими учётными данными расходуют лимит. Для одного партнёра допускается до двух одновременно ожидающих обращений к источнику.
6. Правила для клиентского приложения и ИИ-ассистента
- Используйте адрес API и логин, выданные при подключении. Берите токен из секретов окружения.
- Вызов выполняйте на сервере. В HTTP Basic токен является паролем. В примерах используйте переменные, в журналах сохраняйте только сведения, нужные для диагностики.
- Считайте поля
nullотсутствующими. Для WGS 84 проверяйтеboundaryStatus, для МСК —msk.statusиmsk.calibrated. - Сохраняйте порядок осей, полигонов и колец при построении карты или экспорте. Последняя точка каждого кольца совпадает с первой.
- Различайте отсутствие сведений, временную ошибку источника и исчерпание лимита. Для
429и503учитывайтеRetry-After.
Сведения об участках имеют справочный характер. Вопросы по подключению принимает бот «Мой участок».