Documentație API ImoBox.ro v1

Conceptul API-ului

API-ul ImoBox.ro (v1) oferă acces programatic la baza de date de anunțuri imobiliare. A fost conceput pentru a fi simplu și previzibil, folosind principiile REST și un motor de căutare capabil să interpreteze limbaj natural.

Toate răspunsurile sunt în format JSON și includ metadate despre cerere (requestInfo), un sumar statistic al rezultatelor (summaryStatistics) și lista de anunțuri (results). API-ul este public și nu necesită cheie de autentificare.

Introducere

Acest document descrie versiunea 1 (v1) a API-ului ImoBox.ro. API-ul oferă acces programatic la baza de date de anunțuri imobiliare și este conceput pentru a fi simplu și previzibil, folosind principiile REST.

Informații Generale

Endpoint: Căutare Anunțuri

Acesta este endpoint-ul principal pentru căutarea și filtrarea anunțurilor imobiliare.

Cerere (Request)

GET /v1/anunturi

Parametri de Căutare

Endpoint-ul acceptă parametri pentru căutare în limbaj natural, paginare și limitarea rezultatelor.

Parametru Tip Descriere
q string (Opțional) Șirul de căutare în limbaj natural. Motorul va parsa automat entități precum preț, locație, suprafață, etc. Dacă este omis, va returna cele mai recente anunțuri.
limit integer (Opțional) Numărul de rezultate returnate pe pagină. Valoare default: 25. Maxim: 100.
page integer (Opțional) Numărul paginii de rezultate. Valoare default: 1.
format string (Opțional) Controlează formatul răspunsului, fiind destinat în principal pentru debugging. Pentru uz API, se recomandă insistent omiterea acestui parametru. Răspunsul implicit este JSON, livrat cu un header de compatibilitate maximă.
Valori posibile: html, page, text, json. Folosirea valorii json forțează un header application/json.

Exemplu de Cerere

O căutare pentru apartamente în București, limitată la 5 rezultate. Parametrul format este omis pentru a obține răspunsul JSON standard, recomandat pentru interogări automate.

https://api.imobox.ro/v1/anunturi?q=apartament+bucuresti&limit=5

Structura Răspunsului (Response)

Răspunsul JSON este format din trei obiecte principale:

Obiectul `summaryStatistics`

Acest obiect conține statistici agregate. Cheile vanzare și/sau inchiriere apar doar dacă în rezultate există anunțuri de tipul respectiv.

"summaryStatistics": {
    "vanzare": {
        "pretTotal": { "min": 74900, "max": 180000, "mediu": 108980 },
        "pretPerMp": { "min": 1977, "max": 3273, "mediu": 2297 },
        "suprafata": { "min": 36, "max": 55, "mediu": 47 }
    },
    "inchiriere": {
        "pretTotal": { "min": 200, "max": 650, "mediu": 475 },
        "pretPerMp": { "min": 7, "max": 18, "mediu": 12 },
        "suprafata": { "min": 20, "max": 70, "mediu": 43 }
    }
}

Obiectul `results` (Structura unui Anunț)

Fiecare obiect din lista results are o structură specifică tipului de imobil.

Exemplu Complet de Răspuns

{
    "requestInfo": {
        "status": "success",
        "query": { "q": "apartament bucuresti" },
        "totalResults": 11,
        "page": 1,
        "resultsPerPage": 25,
        "totalPages": 1,
        "fallbackTriggered": false
    },
    "summaryStatistics": {
        "vanzare": {
            "pretTotal": { "min": 74900, "max": 180000, "mediu": 108980 },
            "pretPerMp": { "min": 1977, "max": 3273, "mediu": 2297 },
            "suprafata": { "min": 36, "max": 55, "mediu": 47 }
        },
        "inchiriere": {
            "pretTotal": { "min": 200, "max": 650, "mediu": 475 },
            "pretPerMp": { "min": 7, "max": 18, "mediu": 12 },
            "suprafata": { "min": 20, "max": 70, "mediu": 43 }
        }
    },
    "results": [
        {
            "id_anunt": "281",
            "titlu_anunt": "Particular vând apartament 2 camere București Sector 6",
            "moneda": "EUR",
            "oras": "Sector 6",
            "judet": "București",
            "imobil": "apartament",
            "tip_anunt": "vanzare-cumparare",
            "latitudine": "44.42088...",
            "longitudine": "26.02692...",
            "data_actualizare": "2025-09-29 13:53:36",
            "url": "https://imobox.ro/particular-vand-apartament.../anunt/281",
            "imagine_url": "https://imobox.ro/imagini/apartament_...webp",
            "pret_total": 105000,
            "suprafata_casa": 53,
            "camere": 2
        }
    ]
}

Documentație Interactivă

Specificație Tehnică (Interactiv)

Bazată pe specificația OpenAPI. Permite explorarea în detaliu a tuturor endpoint-urilor, parametrilor și schemelor de date. Recomandat pentru dezvoltare, integrare și pentru a înțelege tehnic API-ul la cel mai profund nivel.