Open Data API v1

Открытые данные CRAVE

Агрегированная статистика по опубликованным объявлениям CRAVE для исследователей, СМИ, банков и партнёров. Только агрегаты: без отдельных объявлений и персональных данных.

Базовый адрес: https://crave.fmgcrm.app/api/v1

Обзор

API отвечает в формате JSON по HTTPS. Все ответы обёрнуты в конверт: поле data содержит данные, поле meta — источник, лицензию, время формирования и город.

Группы, в которых меньше 3 объявлений, не публикуются. Данные основаны на ценах предложения (asking price) из объявлений, а не на ценах сделок.

Анонимные ответы GET кэшируются на 5 минут (Cache-Control: public, max-age=300), ответы на запросы с ключом — только в браузере клиента на 1 минуту (Cache-Control: private, max-age=60; Vary: Authorization). Все ответы содержат ETag: отправьте If-None-Match, чтобы получить 304 без тела. CORS открыт для любых доменов.

Авторизация

Методы price-index, cities и market-summary доступны без ключа с жёстким лимитом по IP. Для большего объёма и для оценки стоимости передайте ключ в заголовке:

Authorization: Bearer crv_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Ключ показывается один раз при выдаче. Храните его на сервере и не публикуйте в коде фронтенда. Отозванный ключ получает ответ 403.

Лимиты запросов

ДоступЛимитМетоды
Без ключа30 запросов в час с одного IPprice-index, cities, market-summary
Ключ Free60 в минуту, 5 000 в суткиprice-index, cities, market-summary
Ключ Partner300 в минуту, 100 000 в суткивсе, включая valuation

Лимиты ключа могут быть изменены индивидуально. При превышении API отвечает 429 с заголовком Retry-After (секунды до сброса окна). Более 20 неверных ключей с одного IP за 10 минут — тоже 429. Анонимный доступ считается по IP клиента: если сервер API не может его определить (развёртывание не за Cloudflare и без доверенного прокси с TRUST_PROXY_HEADERS=1), анонимные запросы получают 503 с error.code = "client_ip_unavailable" — используйте ключ.

Методы

GET
/api/v1/price-index

Индекс цен по районам: медиана, P25 и P75 цены за м², медианная цена и изменение за 30 дней.

Параметры

  • city (необязательный) — Город: almaty, astana, shymkent (по умолчанию almaty).
  • deal (необязательный) — Тип сделки: sale или rent (по умолчанию sale).
  • type (необязательный) — Тип объекта: apartment, new_building, house, commercial. Без параметра — итог по району по всем типам.

Пример запроса

curl "https://crave.fmgcrm.app/api/v1/price-index?city=almaty&deal=sale&type=apartment"
Пример ответа
{
  "data": {
    "deal": "sale",
    "type": "apartment",
    "currency": "KZT",
    "districts": [
      {
        "district": "Медеуский район",
        "district_key": "medeu",
        "district_name": { "ru": "Медеуский район", "kk": "Медеу ауданы", "en": "Medeu District" },
        "type": "apartment",
        "listings_count": 214,
        "median_price_per_m2": 1150000,
        "p25_price_per_m2": 920000,
        "p75_price_per_m2": 1420000,
        "median_price": 79000000,
        "change_30d_pct": 1.8
      }
    ]
  },
  "meta": {
    "source": "CRAVE",
    "license": "CC BY 4.0 (attribution required)",
    "attribution": "Источник: CRAVE (https://crave.fmgcrm.app)",
    "api_version": "v1",
    "generated_at": "2026-10-09T08:00:00.000Z",
    "city": "almaty"
  }
}
GET
/api/v1/cities

Справочник городов и районов с названиями на русском, казахском и английском.

Пример запроса

curl "https://crave.fmgcrm.app/api/v1/cities"
Пример ответа
{
  "data": [
    {
      "id": "astana",
      "name": { "ru": "Астана", "kk": "Астана", "en": "Astana" },
      "center": { "lat": 51.1282, "lng": 71.4304 },
      "districts": [
        {
          "key": "yesil",
          "value": "район Есиль",
          "name": { "ru": "район Есиль", "kk": "Есіл ауданы", "en": "Yesil District" }
        }
      ]
    }
  ],
  "meta": { "source": "CRAVE", "city": null, "…": "…" }
}
GET
/api/v1/market-summary

Сводка рынка города: число опубликованных объявлений по типу и сделке, медиана цены за м², новые объявления за 7 и 30 дней.

Параметры

  • city (необязательный) — Город: almaty, astana, shymkent (по умолчанию almaty).

Пример запроса

curl -H "Authorization: Bearer $CRAVE_API_KEY" \
  "https://crave.fmgcrm.app/api/v1/market-summary?city=astana"
Пример ответа
{
  "data": {
    "listings_total": 1840,
    "min_group_size": 3,
    "median_price_per_m2": { "sale": 610000, "rent": 4300 },
    "new_listings": { "last_7d": 96, "last_30d": 402 },
    "groups": [
      { "type": "apartment", "deal_type": "sale", "listings_count": 1105, "median_price_per_m2": 640000 },
      { "type": "house", "deal_type": "rent", "listings_count": 12, "median_price_per_m2": 2900 }
    ],
    "suppressed_groups": 2,
    "currency": "KZT"
  },
  "meta": { "source": "CRAVE", "city": "astana", "…": "…" }
}
POST
/api/v1/valuation
Partner

Статистическая оценка стоимости по аналогам (AVM v0). Только для ключей Partner. Не является отчётом об оценке.

Тело JSON: city, district, type, area (обязательно), rooms, floor, floors, year, renovation (reno, pre_finish, rough), deal (sale или rent).

Пример запроса

curl -X POST "https://crave.fmgcrm.app/api/v1/valuation" \
  -H "Authorization: Bearer $CRAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"astana","district":"район Есиль","type":"apartment","rooms":2,"area":65,"deal":"sale"}'
Пример ответа
{
  "data": {
    "status": "ok",
    "method": "avm-v0",
    "currency": "KZT",
    "estimate": 42500000,
    "low": 39800000,
    "high": 46100000,
    "price_per_m2_median": 653846,
    "comps_count": 18,
    "confidence": "medium",
    "scope": "district"
  },
  "meta": { "source": "CRAVE", "city": "astana", "…": "…" }
}

Ошибки

Ошибки возвращаются в формате JSON с полем error (code, message, status) и без кэширования.

  • 400 — неверные параметры (bad_request)
  • 401 — нет ключа там, где он нужен, или ключ неизвестен (unauthorized, invalid_key)
  • 403 — ключ отозван или тариф не позволяет метод (key_revoked, plan_required)
  • 429 — превышен лимит, см. Retry-After (rate_limited)
  • 503 — источник данных временно недоступен (service_unavailable) или не удалось определить IP анонимного клиента (client_ip_unavailable)
HTTP/1.1 429 Too Many Requests
Retry-After: 1260
Content-Type: application/json; charset=utf-8

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry later.", "status": 429 } }

Лицензия и указание источника

Черновик условий — требует проверки юристом.

Данные распространяются по лицензии Creative Commons Attribution 4.0 (CC BY 4.0). Их можно копировать, публиковать и использовать в коммерческих целях при условии указания источника.

Указывайте источник рядом с данными, например: «Источник: CRAVE» со ссылкой на https://crave.fmgcrm.app. В интерактивных продуктах — в подписи к графику или таблице.

Данные предоставляются «как есть», без гарантий точности и полноты. Это цены предложения из объявлений, а не цены сделок и не оценка в смысле Закона РК «Об оценочной деятельности».

Запрещено пытаться восстановить отдельные объявления или персональные данные, обходить лимиты (в том числе через несколько ключей или IP) и выдавать данные за собственные без указания источника.

Как получить ключ

Напишите нам на [email]: название организации, контактное лицо, цель использования и ожидаемый объём запросов. Для оценки стоимости укажите, что нужен тариф Partner.

Запросить ключ