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

API Архива оценки

REST API в формате JSON. Базовый адрес: https://archivocenki.ru/api/v1

Начало работы

Зарегистрируйтесь на сайте.
Подтвердите телефон в личном кабинете через бота в Telegram или MAX. Это обязательно: без подтвержденного телефона ключи не выдаются.
После подтверждения автоматически включается пробный период: 7 дней, 100 запросов в сутки.
Создайте ключ API в кабинете. Полный ключ показывается один раз - сохраните его.

Авторизация

Передавайте ключ в заголовке X-API-Key в каждом запросе. Ключ начинается с ak_. Храните его на сервере и не публикуйте в клиентском коде; скомпрометированный ключ отзовите в кабинете и создайте новый.

Заголовок

X-API-Key: ak_ваш_ключ

Лимиты

Число запросов в сутки зависит от тарифа: Пробный - 100, Старт - 1 000, Про - 10 000, Бизнес - 100 000. Каждый ответ содержит заголовки:

X-RateLimit-Limit - суточный лимит тарифа;
X-RateLimit-Remaining - сколько запросов осталось сегодня.

При исчерпании лимита API отвечает кодом 429 до начала следующих суток.

Ошибки

Ошибка возвращается с HTTP-кодом 4xx или 5xx и телом {"detail": "..."}.

Код	Когда	Тело
401	Ключ не передан, неверен или отозван	`{"detail": "..."}`
402	Нет активной подписки или пробного периода	`{"detail": "subscription_required"}`
403	Телефон владельца ключа не подтвержден, либо тариф не включает ресурс (например, скриншоты)	`{"detail": "phone_not_verified"}`
429	Исчерпан суточный лимит запросов тарифа	`{"detail": "..."}`

Поиск объявлений

GET/v1/listings

Список объявлений по фильтрам с курсорной пагинацией. Для следующей страницы передайте next_cursor из ответа в параметр cursor. Когда next_cursor равен null, страниц больше нет.

Параметр	Тип	Описание
city	string	Город: moscow, spb
source	string	Площадка: cian, yandex
status	string	active - в публикации, removed - снято
rooms	integer	Число комнат, 0 - студия
price_min, price_max	integer	Цена, руб
area_min, area_max	number	Общая площадь, м²
changed_since	string (ISO 8601)	Только объявления, измененные после этой даты
limit	integer	Размер страницы, до 100
cursor	string	Курсор следующей страницы из next_cursor

Запрос

curl "https://archivocenki.ru/api/v1/listings?city=spb&rooms=1&price_max=9000000&limit=50" \
  -H "X-API-Key: ak_ваш_ключ"

Ответ 200

{
  "items": [
    {
      "id": 418229,
      "source": "cian",
      "city": "spb",
      "status": "active",
      "rooms": 1,
      "area_total": 36.8,
      "floor": 7,
      "price": 8450000,
      "price_per_m2": 229620,
      "first_seen_at": "2026-08-02T06:40:00Z",
      "last_seen_at": "2026-09-27T06:12:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6NDE4MjI5fQ"
}

Набор полей элемента списка приведен для примера и может расширяться. Полная карточка - в /v1/listings/{id}.

Карточка объявления

GET/v1/listings/{id}

Текущие поля объявления: адрес, площади, этаж, продавец, фотографии, статус.

Запрос

curl "https://archivocenki.ru/api/v1/listings/418229" -H "X-API-Key: ak_ваш_ключ"

Ответ 200

{
  "id": 418229,
  "source": "cian",
  "url": "https://www.cian.ru/sale/flat/...",
  "status": "active",
  "address": "Санкт-Петербург, ...",
  "rooms": 1,
  "area_total": 36.8,
  "area_living": 17.2,
  "area_kitchen": 10.1,
  "floor": 7,
  "floors_total": 12,
  "price": 8450000,
  "seller": { "type": "agency", "name": "..." },
  "photos": ["https://..."]
}

История цены

GET/v1/listings/{id}/prices

Все зафиксированные цены объявления в хронологическом порядке.

Запрос

curl "https://archivocenki.ru/api/v1/listings/418229/prices" -H "X-API-Key: ak_ваш_ключ"

Ответ 200

[
  { "ts": "2026-08-02T06:40:00Z", "price": 8900000, "price_per_m2": 241848 },
  { "ts": "2026-09-01T07:05:00Z", "price": 8450000, "price_per_m2": 229620 }
]

События

GET/v1/listings/{id}/events

Лента жизненного цикла. Типы: new - появилось, price_up и price_down - изменение цены, field_changed - изменились поля карточки, removed - снято, reappeared - вернулось на площадку.

Запрос

curl "https://archivocenki.ru/api/v1/listings/418229/events" -H "X-API-Key: ak_ваш_ключ"

Ответ 200

[
  { "ts": "2026-08-02T06:40:00Z", "type": "new" },
  { "ts": "2026-09-01T07:05:00Z", "type": "price_down" }
]

Состав полей события приведен для примера.

Скриншоты карточки

GET/v1/listings/{id}/screenshots

Снимки страницы объявления на каждое изменение цены. Доступно в тарифах Про и Бизнес. Ссылка url действует 1 час, скачивайте файл сразу или запрашивайте ссылку повторно.

Запрос

curl "https://archivocenki.ru/api/v1/listings/418229/screenshots" -H "X-API-Key: ak_ваш_ключ"

Ответ 200

[
  {
    "captured_at": "2026-09-01T07:06:12Z",
    "price": 8450000,
    "url": "https://archivocenki.ru/s3/screenshots/...?X-Amz-Expires=3600"
  }
]

Использование

GET/v1/usage

Текущий тариф, суточный лимит и сколько запросов использовано сегодня.

Запрос

curl "https://archivocenki.ru/api/v1/usage" -H "X-API-Key: ak_ваш_ключ"

Ответ 200

{ "plan": "pro", "daily_limit": 10000, "usage_today": 1284 }

Состав полей приведен для примера.