Документация 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   # и так далее

Курсор вместо номера страницы. На глубине в десятки тысяч объявлений offset дорожает с глубиной, а при притоке новых объявлений страницы сдвигаются — одно и то же объявление может прийти дважды или пропасть между страницами. Надёжнее идти курсором: в каждом ответе есть next_cursor — передайте его в следующий запрос как cursor, с теми же фильтрами. offset и сортировка при курсоре не нужны: порядок — по дате появления, новые сверху. next_cursor: null — выборка закончилась. С dedupe=true курсор тоже работает и листает группы: каждая группа приходит ровно один раз, а объявления, появившиеся после первой страницы, в этот проход не попадают — их забирайте следующим проходом или лентой /v1/feed. Курсор обычной выдачи и курсор dedupe=true не взаимозаменяемы: чужой или мусорный курсор — ответ 400 bad_cursor.

?limit=1000                 # первая 1000, в ответе next_cursor
?limit=1000&cursor=<next_cursor>   # следующая 1000
?limit=1000&cursor=...         # пока next_cursor не станет null

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

Лента изменений

/v1/feed отдаёт новые объявления и смены цены по порядку, в котором они случились. Каждый ответ содержит next_cursor — передайте его в следующем запросе параметром cursor, и вы получите всё, что произошло после. Ничего не теряется и не приходит дважды.

• Первый запрос без cursor возвращает пустую страницу и next_cursor — текущую точку. Нужны изменения с конкретного момента — передайте since (дата и время в ISO 8601).
• Фильтры — те же, что у /v1/items: можно получать изменения только по своему региону или типу. Если по фильтрам в очередной порции ничего не нашлось, next_cursor всё равно сдвигается — просто запросите дальше.
• У каждого объявления в ленте есть event (new — новое для Metrapi, price — изменилась цена), event_at и event_seq. Объявление приходит один раз за страницу, в текущем состоянии.
• new приходит и для объявления, давно размещённого на площадке, но попавшего к нам недавно (например, после обновления): у него first_seen в прошлом. Для постоянной выгрузки берите ленту — сортировка /v1/items по дате такие объявления среди свежих не покажет.
• Снятые с публикации — отдельной лентой /v1/feed/delisted (delisted — снято, relisted — вернулось). Храните у себя и её курсор.
• Лента хранит изменения за 90 дней. Курсор старше — ответ 410: загрузите базу заново через /v1/items.
• Лимит частоты — общий с /v1/items (1 запрос в 2 секунды на ключ).

?cursor=100001234&region=Самарская+область   # -> { "count": 87, "items": [...], "next_cursor": 100004517 }

Формат XML

Ответы /v1/items, /v1/item/{…}, /v1/feed и /v1/feed/delisted можно получить в XML — например, для загрузки в 1С или Битрикс: добавьте format=xml. Имена полей те же, что в JSON; списки — повторяющиеся элементы <item>; ключ, который нельзя записать именем тега, — <entry key="…">. Пустой список и null в XML выглядят одинаково — пустым элементом. Ошибки при format=xml тоже приходят в XML.

curl -H "X-Api-Key: КЛЮЧ" "https://api.metrapi.ru/v1/items?city=msk&limit=100&format=xml"

<response><count>100</count><items><item><source>cian</source>…</item>…</items></response>

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

Одна и та же квартира часто размещена на нескольких площадках. Параметр dedupe=true схлопывает такие записи в одну, а в поле sources[] перечисляет все площадки, где она есть, и цену на каждой — это и есть суть агрегатора. При dedupe=true параметры limit и offset считаются в группах (объектах), а не в отдельных объявлениях; группы идут от самого свежего объявления к старым, и страницами можно пройти всю выборку. Листать надёжнее курсором (next_cursor): с offset новые объявления сдвигают страницы. Запись группы, разнесённой по разным точкам, может прийти двумя строками, поэтому записей на странице бывает чуть больше limit — конец выборки определяйте по next_cursor: null.

{
  "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 — полнота зависит от площадки: часть характеристик отдают не все источники.

Коды ответов

Журнал изменений

Что менялось в API и документации, от свежего к старому. Время — московское. Пометка проверьте интеграцию — изменение может повлиять на уже работающую интеграцию. Те же записи в JSON — /v1/changelog. Журнал ведётся с 02.09.2026.

Поддержка

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