Документация API

Введение

Metrapi отдаёт объявления о продаже и аренде недвижимости, собранные из 8 источников (Avito, ЦИАН, ДомКлик, Яндекс.Недвижимость, FarPost, Move.ru, sob.ru, Юла) — в единой нормализованной схеме, с готовыми фильтрами и склейкой дублей одной квартиры с разных площадок. Один запрос — данные со всех источников сразу. Актуальный список всегда отдаёт /v1/sources.

API входит в полный доступ. Все запросы — обычный HTTP GET с заголовком X-Api-Key, ответы — JSON. Никаких SDK не нужно, подойдёт curl, Python requests, любой HTTP-клиент.

API отдаёт данные объявлений целиком, включая координаты (lat/lon) — см. таблицу «Поля объявления». Аналитика рынка, интерактивная карта и наш внутренний геокодер через API не доступны — это инструменты личного кабинета, не публичного API.

Быстрый старт

1. Получите ключ — подключите полный доступ в личном кабинете или напишите на info@metrapi.ru. Ключ выглядит как metrapi_xxxxxxxx.
2. Добавьте его в заголовок X-Api-Key каждого запроса.
3. Шлите запросы на https://api.metrapi.ru.

Первый запрос

# Двушки в Москве до 15 млн
curl -H "X-Api-Key: ВАШ_КЛЮЧ" \
  "https://api.metrapi.ru/v1/items?city=msk&deal_type=sale&rooms=2&price_max=15000000"

Ответ

{
  "count": 128,
  "items": [
    {
      "source": "avito",
      "deal_type": "sale",
      "realty_type": "flat",
      "address": "Москва, ул. Тверская, 12",
      "city": "msk",
      "price": 14200000,
      "rooms": 2, "area_total": 54.0,
      "floor": 5, "floors_total": 9,
      "metro": "Тверская",
      "metro_minutes": 7, "metro_mode": "walk",
      "lat": 55.7645, "lon": 37.6062,
      "url": "https://www.avito.ru/...",
      "published_at": "2026-06-18"
    }
  ]
}

Хотите потыкать запросы прямо в браузере — откройте интерактивную песочницу: нажмите Authorize, вставьте ключ один раз — и он подставится во все запросы.

Авторизация

Все рабочие эндпоинты требуют заголовок X-Api-Key с вашим персональным ключом. Без ключа сервер вернёт 401, с неверным — 403.

Ключ — секрет. Держите его на своём сервере, не вставляйте в код страницы в браузере или в мобильное приложение, откуда его легко достать.

curl -H "X-Api-Key: metrapi_xxxxxxxx" "https://api.metrapi.ru/v1/items?city=msk"

Лимиты

Частота ограничена по-разному для разных ручек — чтение наших данных не трогает источники объявлений, поэтому лимит там мягче, чем у ручек, которые идут за свежими данными к первоисточнику.

Пагинация

limit — сколько объявлений вернуть (по умолчанию 50, максимум 1000), offset — сколько пропустить. Чтобы выгрузить всю выборку, идите страницами, пока count не станет меньше limit:

?limit=1000&offset=0      # первая 1000
?limit=1000&offset=1000   # следующая 1000
?limit=1000&offset=2000   # и так далее

Склейка дублей

Одна и та же квартира часто размещена на нескольких площадках. Параметр dedupe=true схлопывает такие записи в одну, а в поле sources[] перечисляет все площадки, где она есть, и цену на каждой — это и есть суть агрегатора.

{
  "address": "Москва, ул. Тверская, 12",
  "price": 14200000,
  "sources": [
    {"source": "avito", "price": 14200000, "url": "https://www.avito.ru/..."},
    {"source": "cian",  "price": 14500000, "url": "https://www.cian.ru/..."}
  ],
  "sources_count": 2
}

У каждого объявления есть group_id — идентификатор его группы дублей. Он приходит и без dedupe: тогда вы получаете все публикации по отдельности и группируете их у себя, ничего не теряя. group_id стабилен — не меняется при изменении цены, поэтому по нему можно связывать выгрузки, сделанные в разные дни. null означает, что группу определить нельзя (в адресе нет номера дома или неизвестна площадь) — такое объявление считается отдельным объектом.

Рядом идёт group_spread_m — расстояние в метрах между самыми удалёнными объявлениями группы. Это мера уверенности: 0 — площадки указали одну и ту же точку, несколько сотен метров — объявления связаны по адресу, а координаты у площадок расходятся.

Фильтры

Параметры запроса /v1/items. Комбинируются по логическому И. Коды зон обхода — /v1/cities, районы и метро города — /v1/facets.

Мультивыбор. Параметры city, realty_type, rooms, source, district, metro, microdistrict, locality, settlement, seller_type, land_status, build_status, house_type, renovation, bathroom, balcony принимают несколько значений — просто повторите параметр: ?rooms=2&rooms=3. Значения внутри одного параметра объединяются по ИЛИ.

Чего нет в выдаче

Часть объявлений отсекается ещё до фильтров — если не знать об этом, результат выглядит неполным без видимой причины:

Поля объявления

Ответ содержит только перечисленные ниже поля. Незаполненные приходят как null — полнота зависит от площадки: часть характеристик отдают не все источники.

Коды ответов

Поддержка

Технические вопросы — support@metrapi.ru, подключение и оплата — info@metrapi.ru, или через систему тикетов в личном кабинете. Подробнее — на странице Контакты.