Обʼєкти (читання)

Читання публічного каталогу оголошень — property (вторинка), rental (оренда) і complex (ЖК). Відповіді віддаються в явній стабільній формі (allowlist): внутрішні поля не витікають, а нові поля моделі не зʼявляються несподівано. Читання — це GET, і воно безкоштовне (не списується з квоти викликів).

Базовий URL: https://developers.grem.capital/api/v1.

Список

GET /objects?kind=property&city=Kyiv&page=1&limit=20&sort=newest
Authorization: Bearer gsk_live_...

Параметри запиту:

• kind (обовʼязковий) — property, rental або complex
• city, country (опц.) — фільтри точного збігу
• page (за замовчуванням 1), limit (за замовчуванням 20, максимум 50)
• sort — newest (за замовчуванням) або oldest

Відповідь:

{
  "data": [ { "id": "...", "kind": "property", "name": "...", "price": 120000, "currency": "USD", ... } ],
  "paginate": { "currentPage": 1, "totalPages": 471, "totalCount": 9412 },
  "requestId": "req_..."
}

Один обʼєкт

GET /objects/{kind}/{id}
Authorization: Bearer gsk_live_...

{kind} — property, rental або complex. Повертає один обʼєкт у тій самій формі плюс requestId. Невідомий id — 404.

Форма обʼєкта

Спільні поля (точний набір залежить від типу):

• id, kind, name, slug, status (active або sold), createdAt
• price, currency (property/rental); price: { from, to, currency } (complex)
• address — повна адреса, включно з street і координатами location
• constructionYear — звичайний 4-значний рік (null, якщо невідомий)
• Площі — обʼєкти: spaceAll: { "value": 50, "unit": "m2" }; підказка відображення — nativeAreaUnit
• photos — [{ id, isMain, mimetype, variants, ready }]
• author — агент/агенція оголошення (курований публічний блок)
• У complex додано apartmentPlans[] (планування) і progress[] (хід будівництва)

Що ви бачите

Відповідь залежить від того, хто ви:

• Будь-який обʼєкт — публічна картка оголошення (те, що бачать відвідувачі grem.capital).
• Обʼєкт під відкритим комісійним договором — як авторизований брокер ви додатково бачите винагороду за схваленою угодою і можете вирішити, чи надсилати лід.
• Ваші власні обʼєкти — повний вигляд власника.

Нікому не віддаються: приватні контакти власника, дані продавця з імпорту, нотатки модерації, оригінали фото без водяного знака та внутрішні ідентифікатори.