Мой участок Разработчикам
ДОКУМЕНТАЦИЯ · API V1

Партнёрский API «Моего участка»

Один запрос по кадастровому номеру земельного участка. Ответ в JSON содержит доступные характеристики, контур в WGS 84 и координаты в МСК с отметкой калибровки.

Выдадим адрес API, логин и токен по запросу через Telegram-бот.

Запросить доступ в Telegram

1. Как получить доступ

Откройте 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
  }
}
Поля объекта data
ПолеТип и значение
cadastralNumberСтрока. Кадастровый номер из запроса.
cadastralQuarter, addressСтрока или null. Номер квартала и адрес либо описание местоположения.
registeredAreaM2Число или null. Учётная площадь в м².
cadastralValueRubЧисло или null. Кадастровая стоимость в рублях.
cadastralValueRecordedOn, registeredOnСтрока в формате источника или null. Дата внесения стоимости и дата постановки на учёт.
registrationStatus, landCategory, permittedUseСтрока или null. Статус объекта, категория земель и разрешённое использование.
boundaryStatusavailable или unavailable. Доступность границы.
wgs84Объект GeoJSON Polygon, MultiPolygon или null.
mskОбъект со статусом пересчёта и отметкой калибровки. Поля координат доступны при status: "ready".
staleБулево значение. true, если источник явно отметил, что данные не удалось обновить при временном сбое.

Если источник подтвердил отсутствие контура, ответ может содержать доступные атрибуты при 200, boundaryStatus: "unavailable" и wgs84: null.

4. Координаты и калибровка МСК

Возможные значения msk.status
СтатусЧто получает клиент
readysystem — название системы, zone — номер зоны, zoneId — идентификатор вида 69:1, calibrated — true для калиброванной зоны или false для расчёта по базовым параметрам, polygons — координаты.
boundary_unavailableКонтур недоступен. calibrated: null.
zone_unavailableWGS 84 доступна, пересчёт для зоны недоступен. calibrated: null.

Отметка калибровки описывает параметры зоны. Точность исходной геометрии зависит от сведений источника.

5. Ошибки, лимиты и повторы

Ошибка имеет структуру {"error":{"code":"invalid_credentials"}}. В обработчике клиента используйте HTTP-статус вместе с error.code.

Коды HTTP
HTTPКодДействие
400invalid_cadastral_numberПроверьте номер и убедитесь, что параметр cad передан один раз.
401invalid_credentialsПроверьте логин, токен, статус и даты доступа.
404parcel_not_returned, route_not_foundДля первого кода уточните номер или наличие сведений. Для второго проверьте выданный URL.
405method_not_allowedИспользуйте GET.
429partner_limit, partner_busy, source_busy, edge_limitДождитесь числа секунд из Retry-After. Сократите параллельные обращения.
502parcel_source_unavailable, invalid_source_response, invalid_source_geometryПокажите временную ошибку. Повторяйте с паузой и ограничением числа попыток.
503parcel_source_unavailableПовторите после интервала из Retry-After.
500internal_errorПри повторении сообщите команде время запроса, HTTP-статус и код ошибки.

Минутный лимит задаётся для каждого логина. Некоторые неуспешные запросы с действующими учётными данными расходуют лимит. Для одного партнёра допускается до двух одновременно ожидающих обращений к источнику.

6. Правила для клиентского приложения и ИИ-ассистента

Сведения об участках имеют справочный характер. Вопросы по подключению принимает бот «Мой участок».