# API ImoBox.ro - Documentație Tehnică

Această documentație descrie endpoint-urile și structurile de date oferite de `api.imobox.ro`, serverul principal de API al platformei ImoBox. Permite căutarea avansată în limbaj natural a anunțurilor imobiliare și obținerea de statistici agregate privind piața imobiliară din România.

**Versiune API:** v1  
**URL de bază:** `https://api.imobox.ro`

---

## 1. Căutare Anunțuri Imobiliare

Căutarea principală, suportând limbaj natural și filtre complexe.

- **Endpoint:** `/v1/anunturi`
- **Metodă:** `GET`

### Parametri de tip Query (`?`)

| Nume | Tip | Necesar | Implicit | Descriere |
| :--- | :--- | :---: | :---: | :--- |
| `q` | `string` | **Da** | - | Șirul de căutare în limbaj natural (ex: *'apartament 2 camere bucuresti'*, *'casa cu gradina cluj'*). |
| `limit` | `integer` | Nu | `25` | Numărul de rezultate pe pagină. Limita maximă este 100, minima este 1. |
| `pagina` | `integer` | Nu | `1` | Pagina de rezultate pentru a naviga prin paginare. |
| `format` | `string` | Nu | `json` | Specifică formatul de output. Valori acceptate: `json`, `text`, `html`, `table`. Dacă parametrul lipsește, server-ul returnează `html` implicit. |

### Răspunsuri (Cod HTTP 200 OK)

În funcție de parametrul `format`, răspunsul poate fi:
- **`json`**: Returnează un obiect JSON detaliat (vezi structura `ApiResponse` mai jos).
- **`text` / `html`**: Returnează reprezentări vizuale/textuale simplificate.

---

## 2. Modele de Date (JSON)

Dacă interogarea folosește `format=json`, răspunsul va respecta structura `ApiResponse`.

### `ApiResponse`
Obiectul principal returnat de server, care conține atât metadate cât și rezultatele propriu-zise.

```json
{
  "requestInfo": { ... },
  "summaryStatistics": { ... },
  "results": [ ... ]
}
```

#### `RequestInfo` (Metadate și Paginare)
Conține informații despre starea cererii și sistemul de paginare.
- **`status`**: Statusul interogării (ex: `success`).
- **`query`**: Obiect ce conține parametrii `request` și `q` utilizați de server.
- **`totalResults`**: Numărul total de oferte găsite.
- **`pagina`**: Pagina curentă.
- **`resultsPerPage`**: Numărul de rezultate per pagină.
- **`totalPages`**: Numărul total de pagini.
- **`fallbackTriggered`**: Boolean ce indică dacă motorul a folosit metode fallback de căutare.

#### `SummaryStatistics` (Statistici Agregate)
Statistici privind prețurile și suprafețele pentru lotul curent de anunțuri, defalcate pe tip de tranzacție:
- **`vanzare`**: Obiect statistic (`StatisticiTranzactie`).
- **`inchiriere`**: Obiect statistic (`StatisticiTranzactie`).

Fiecare **`StatisticiTranzactie`** conține:
- `pretTotal`: { min, max, mediu }
- `pretPerMp`: { min, max, mediu }
- `suprafata`: { min, max, mediu }

---

## 3. Structura unui Anunț (`Anunt`)

Matricea `results` conține obiecte dinamice în funcție de proprietatea `imobil` (polimorfism prin *discriminator*). 

### Proprietăți Comune (`AnuntBaza`)
Toate anunțurile, indiferent de tip, vor conține obligatoriu următoarele câmpuri:

- **`id_anunt`** (string): ID-ul unic al anunțului.
- **`titlu_anunt`** (string): Titlul comercial.
- **`moneda`** (string): Moneda prețului (ex: `EUR`, `RON`).
- **`oras`** (string), **`judet`** (string): Informații de localizare.
- **`imobil`** (string): Discriminatorul. Poate fi `teren`, `apartament` sau `casa`.
- **`tip_anunt`** (string): Tipul tranzacției (`vanzare-cumparare` sau `inchiriere`).
- **`latitudine`** / **`longitudine`** (string): Coordonate geografice.
- **`data_actualizare`** (date-time, null): Ultima actualizare.
- **`url`** (uri): Link direct către anunț pe imobox.ro.
- **`imagine_url`** (uri): URL-ul imaginii reprezentative.

### Specializare: `AnuntLocuinta` (Apartament sau Casă)
Dacă `imobil` este `apartament` sau `casa`, obiectul include suplimentar:
- **`pret_total`** (number): Prețul cerut.
- **`suprafata_casa`** (number): Suprafața utilă/construită a locuinței.
- **`camere`** (integer): Numărul de camere.

### Specializare: `AnuntTeren`
Dacă `imobil` este `teren`, obiectul include suplimentar:
- **`pret_mp`** (number): Prețul pe metru pătrat.
- **`pret_total`** (number): Prețul total.
- **`suprafata_teren`** (number): Suprafața totală a parcelei.

---

*Notă: Pentru endpoint-ul dedicat Inteligenței Artificiale ce utilizează formatul Schema.org (DataFeed), vă rugăm să consultați `knowledge-graph-index.md` referitor la endpoint-ul `/knowledge-graph-index.json` situat direct pe domeniul principal.*