Какво връща API
API е ориентиран към обобщени данни. Продажбите и наемите са отделни пазарни множества в съхранението, изчисленията и отговорите. API връща показатели с брой наблюдения, увереност и времеви период — без описания, снимки, контакти или точни адреси от обяви.
Ценови показатели
При продажба: обща офертна цена и EUR/м². При наем: месечен офертен наем и EUR/м²/месец. Двата режима никога не се комбинират.
Показатели за предлагане
Активно предлагане, нови наблюдения и свалени обяви за допустими градове, квартали и видове имоти.
Показатели за качество
Брой ценови наблюдения, разнообразие на източниците, максимален дял на източник и средна или висока увереност.
Историческа доставка
До 366 дневни обобщени snapshot-а на заявка за лицензите Data Delivery и Enterprise.
Удостоверяване и управление на ключове
Продукционният дизайн използва API ключ на организацията като Bearer token. След активиране на управлението на ключове упълномощените администратори ги създават и отнемат в защитената зона; тайната се показва еднократно и никога не се изпраща по имейл.
- Съхранявайте ключовете в сървърен secret manager или променлива на средата.
- Никога не поставяйте продукционен ключ в браузърен JavaScript, source control, логове, prompts или съобщения до поддръжката.
- Използвайте отделен ключ за всяка продукционна система и го отнемете веднага при промяна на система или администратор.
- Изпращайте уникален X-Client-Request-Id за проследяване без разкриване на бизнес данни.
curl --request GET \
--url 'https://bulgarian-listings.152-53-109-83.sslip.io/api/v1/market/snapshot?area_id=bg-sofia-lozenets&market_mode=sale&property_kind=apartment&as_of=2026-07-18' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'X-Client-Request-Id: portfolio-review-2026-07-19'Договор на отговора
Всеки успешен отговор отделя лицензираните данни от оперативните метаданни. Snapshot и времевият ред изискват market_mode=sale или market_mode=rent. Запазвайте режима и метаданните при съхранение или показване.
| Поле | Значение |
|---|---|
data | Заявеният обобщен пазарен резултат. |
data.market_mode | sale или rent. Това измерение трябва да се запази; резултати от различни режими не трябва да се сливат. |
meta.request_id | Идентификатор за проследяване при комуникация с поддръжката. |
meta.generated_at | UTC моментът на генериране на отговора. |
meta.observation_window | Датите на наблюденията, подкрепящи резултата. |
meta.weighted_data_units | Таксуваните единици данни за този отговор. |
Продукционни v1 API методи
Достъпността зависи от лицензираното ниво, покритието с достатъчно качество и разрешената употреба в поръчката.
| Метод | Път | Резултат | Начално ниво |
|---|---|---|---|
| GET | /markets/coverage | Открива допустимите area ID и отделното покритие за продажби и наеми; може да се филтрира по market_mode. | Insights |
| GET | /market/snapshot | Връща един обобщен snapshot за задължително избран режим sale или rent. | Insights |
| GET | /market/timeseries | Връща до 366 дневни точки за един задължително избран режим, зона и вид имот. | Data Delivery |
Пример за snapshot при продажба
Стойностите за продажба са само илюстративни. Те не са текуща пазарна статистика. При rent ценовите полета означават месечен офертен наем и EUR/м²/месец.
{
"data": {
"area_id": "bg-sofia-lozenets",
"market_mode": "sale",
"property_kind": "apartment",
"as_of": "2026-07-18",
"active_listings": 418,
"new_listings": 19,
"removed_listings": 14,
"priced_listings": 391,
"median_asking_price_eur": 286000,
"median_asking_price_per_sqm_eur": 2840,
"p25_asking_price_per_sqm_eur": 2370,
"p75_asking_price_per_sqm_eur": 3310,
"source_count": 3,
"max_source_share": 0.42,
"confidence": "high",
"calculation_version": "market-api-daily-v2",
"published_at": "2026-07-19T08:30:00Z"
},
"meta": {
"request_id": "req_01JZ8W5Y6M9R7Q2F4A",
"generated_at": "2026-07-19T08:30:00Z",
"observation_window": {
"from": "2026-07-18",
"to": "2026-07-18"
},
"weighted_data_units": 1
}
}Пример за времеви ред при продажба
Един времеви ред съдържа точно един пазарен режим. Всяка точка запазва режима и броя наблюдения, за да се отличи движението от промяна в извадката.
{
"data": {
"area_id": "bg-sofia-lozenets",
"market_mode": "sale",
"property_kind": "apartment",
"date_from": "2026-07-15",
"date_to": "2026-07-18",
"points": [
{"area_id": "bg-sofia-lozenets", "market_mode": "sale", "property_kind": "apartment", "as_of": "2026-07-15", "active_listings": 402, "new_listings": 12, "removed_listings": 9, "priced_listings": 378, "median_asking_price_eur": 281000, "median_asking_price_per_sqm_eur": 2815, "p25_asking_price_per_sqm_eur": 2350, "p75_asking_price_per_sqm_eur": 3280, "source_count": 3, "max_source_share": 0.43, "confidence": "high", "calculation_version": "market-api-daily-v2", "published_at": "2026-07-16T01:10:00Z"},
{"area_id": "bg-sofia-lozenets", "market_mode": "sale", "property_kind": "apartment", "as_of": "2026-07-18", "active_listings": 418, "new_listings": 19, "removed_listings": 14, "priced_listings": 391, "median_asking_price_eur": 286000, "median_asking_price_per_sqm_eur": 2840, "p25_asking_price_per_sqm_eur": 2370, "p75_asking_price_per_sqm_eur": 3310, "source_count": 3, "max_source_share": 0.42, "confidence": "high", "calculation_version": "market-api-daily-v2", "published_at": "2026-07-19T08:30:00Z"}
]
},
"meta": {
"request_id": "req_01JZ8W8BQM5P3JY7VT",
"generated_at": "2026-07-19T08:30:00Z",
"observation_window": {"from": "2026-07-15", "to": "2026-07-18"},
"weighted_data_units": 1
}
}Кеширане и претеглени единици
Лицензите се отчитат според доставените данни. Snapshot струва една единица; coverage — една единица на 100 зони; времеви ред — една единица на 30 дневни точки, закръглено нагоре.
- Използвайте ETag и If-None-Match. Съвпадащ отговор 304 не връща данни и не използва единици.
- Проверявайте meta.weighted_data_units и X-Data-Units-Remaining след всяка успешна заявка.
- Месечният твърд лимит на лиценза спира доставката, преди употребата да надхвърли договорения обем.
- Спазвайте Retry-After при HTTP 429 и използвайте exponential backoff с jitter за временни 5xx грешки.
X-Request-Id: req_01JZ8W5Y6M9R7Q2F4A
X-Data-Units-Used: 1
X-Data-Units-Remaining: 24841
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
ETag: "snapshot-bg-sofia-lozenets-sale-2026-07-18"Грешки и повторни заявки
Грешките използват стабилни машинно четими кодове и съдържат същия идентификатор на заявка като response headers.
| HTTP | Код | Действие на клиента |
|---|---|---|
400 | invalid_parameter | Коригирайте заявката; не я повтаряйте без промяна. |
401 | invalid_api_key | Спрете и сменете credential-а. |
403 | licence_scope_denied | Методът е извън обхвата на ключа или лиценза. |
403 | licence_inactive | Свържете се със собственика на организацията или PazarenRadar. |
404 | not_found | Проверете каноничния идентификатор чрез /markets/coverage. |
429 | rate_limited | Изчакайте Retry-After и повторете с jitter. |
429 | monthly_usage_exhausted | Изчакайте следващия месец или договорете по-голям обем. |
500/503 | temporary_failure | Повторете до три пъти с exponential backoff. |
{
"error": {
"code": "not_found",
"message": "not found",
"request_id": "req_01JZ8WBZ4R8Q1C6K9N"
}
}Инструкции за AI агенти
Третирайте API като лицензиран аналитичен инструмент, а не като неограничени данни за обхождане. Добавете тези правила към всеки агент с достъп.
- Разрешавайте локациите чрез GET /markets/coverage преди анализ. Никога не отгатвайте area_id.
- Избирайте точно един market_mode за всеки анализ. Никога не сливайте, осреднявайте или сравнявайте sale и rent цени като величини с еднаква единица.
- Използвайте само полета и enum стойности от предоставения OpenAPI договор; не измисляйте липсващи показатели.
- Посочвайте пазарния режим, датата, периода на наблюдение, броя ценови обяви и увереността към всеки извод.
- При sale ценовите полета са обща офертна цена и EUR/м². При rent са месечен офертен наем и EUR/м²/месец. Нито едното не е цена на сключена сделка.
- Не използвайте обобщените данни за идентифициране на лице, контакт, точен имот или адрес.
- Дръжте API credential-ите извън контекста на модела. Дайте на агента ограничен сървърен tool, а не самия ключ.
- Оценявайте единиците преди дълги времеви редове и изисквайте човешко одобрение за голям обем.
- Повтаряйте само 429 и временни 5xx отговори. Никога не влизайте в цикъл при 400, 401, 403 или 404.
- Запазвайте request_id в цитатите или одитните логове, за да може всеки извод да бъде проследен.
Примерна политика за агент
Използвай PazarenRadar само за обобщен анализ на имотния пазар в България. Разрешавай каноничните локации чрез coverage tool. Избирай точно един market_mode: sale или rent. Никога не комбинирай двата режима. При sale ценовите полета са обща офертна цена и EUR/м²; при rent са месечен офертен наем и EUR/м²/месец. Никога не измисляй area ID, показател, дата или липсваща стойност. Добавяй пазарен режим, дата, период на наблюдение, брой ценови обяви и увереност към всеки пазарен извод. Нито един режим не съдържа цени на сключени сделки. Никога не разкривай credentials, лични данни или точни адреси. Искай човешко потвърждение преди времеви редове с голям разход. Спазвай договорния обхват, Retry-After и твърдите лимити.
Примерна tool дефиниция
Предоставете на агента ограничен tool. Вашето приложение — не моделът — добавя Bearer credential-а и прилага разрешените зони, показатели и бюджет.
{
"name": "get_market_snapshot",
"description": "Get aggregate asking-price, supply and movement evidence for one licensed Bulgarian market area.",
"input_schema": {
"type": "object",
"properties": {
"area_id": {
"type": "string",
"description": "Canonical area ID returned by GET /markets/coverage."
},
"property_kind": {
"type": "string",
"enum": ["all", "apartment", "one-room", "two-room", "three-room", "four-plus-room", "house"]
},
"market_mode": {
"type": "string",
"enum": ["sale", "rent"],
"description": "Required. Never combine sale and rent evidence."
},
"as_of": {
"type": "string",
"format": "date"
}
},
"required": ["area_id", "market_mode", "property_kind"],
"additionalProperties": false
}
}Примери за интеграция
Примерите използват продукционния базов адрес и изискват активен ключ с подходящ обхват, издаден на организацията.
curl --request GET \
--url 'https://bulgarian-listings.152-53-109-83.sslip.io/api/v1/market/snapshot?area_id=bg-sofia-lozenets&market_mode=sale&property_kind=apartment&as_of=2026-07-18' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'X-Client-Request-Id: portfolio-review-2026-07-19'const parameters = new URLSearchParams({
area_id: 'bg-sofia-lozenets',
market_mode: 'sale',
property_kind: 'apartment',
as_of: '2026-07-18',
});
const response = await fetch(
`https://bulgarian-listings.152-53-109-83.sslip.io/api/v1/market/snapshot?${parameters}`,
{
headers: {
Accept: 'application/json',
Authorization: `Bearer ${process.env.PAZARENRADAR_API_KEY}`,
'X-Client-Request-Id': crypto.randomUUID(),
},
},
);
if (response.status === 429) {
throw new Error(`Retry after ${response.headers.get('retry-after')}s`);
}
if (!response.ok) throw new Error(await response.text());
const snapshot = await response.json();
console.log(snapshot.data.median_asking_price_per_sqm_eur);import os
import uuid
import requests
response = requests.get(
"https://bulgarian-listings.152-53-109-83.sslip.io/api/v1/market/snapshot",
params={
"area_id": "bg-sofia-lozenets",
"market_mode": "sale",
"property_kind": "apartment",
"as_of": "2026-07-18",
},
headers={
"Accept": "application/json",
"Authorization": f"Bearer {os.environ['PAZARENRADAR_API_KEY']}",
"X-Client-Request-Id": str(uuid.uuid4()),
},
timeout=20,
)
response.raise_for_status()
snapshot = response.json()
print(snapshot["data"]["median_asking_price_per_sqm_eur"])Нужен ви е продукционен договор?
Оценяваме употребата, потвърждаваме покритието и определяме обема, съхранението, показването и правата за производни резултати преди продукционен достъп.
Подписаният лиценз за данни и поръчката определят разрешената употреба, обем, съхранение и права върху производни резултати.