> ## Documentation Index
> Fetch the complete documentation index at: https://api.housera.ro/llms.txt
> Use this file to discover all available pages before exploring further.

# Statisticile anunțurilor

> Cum citești vizualizările, salvările și contactele anunțurilor, pe zile și pe perioade, și cum compari prețul cu zona.

Prin API citești aceleași cifre pe care contul le vede în Housera: graficul din prima pagină a contului, rândul fiecărui anunț din Anunțurile mele și comparația prețului cu zona de pe pagina anunțului. Toate cer dreptul `listings:read` și acoperă doar anunțurile pe care le vede cheia (vezi [Ce anunțuri vede fiecare cheie](https://api.housera.ro/ro/concepts/access.md)).

Cifrele sunt de trei feluri:

| Cifră | Ce numără |
| - | - |
| `views` | Vizitele pe pagina anunțului. Același om care revine în aceeași zi se numără o dată. |
| `saves` | De câte ori a fost salvat anunțul la favorite. |
| `contacts` | Cererile clienților venite prin anunț: mesaje, cereri de apel și de vizionare. Un contact adăugat de mână nu intră aici. |

Zilele sunt zile calendaristice, în fusul orar din `timezone`. Ziua de azi vine cu `partial: true`, fiindcă nu s-a încheiat, iar cifrele ei cresc până la miezul nopții.

## Graficul contului

`GET /account/stats?range=30` dă graficul din prima pagină a contului, pe 7, 30 sau 90 de zile:

```json theme={null}
{
  "data": {
    "range": 30,
    "scope": "team",
    "agent": null,
    "timezone": "UTC",
    "days": [
      { "day": "2026-10-14", "views": 41, "saves": 3, "contacts": 1, "partial": false },
      { "day": "2026-11-12", "views": 12, "saves": 0, "contacts": 0, "partial": true }
    ],
    "totals": { "views": 1240, "saves": 61, "contacts": 18 },
    "previous": { "views": 1105, "saves": 58, "contacts": 21 },
    "top": [
      { "agent": { "name": "Maria Popa", "email": "maria@exemplu.ro" }, "views": 520, "saves": 22, "contacts": 7 }
    ],
    "moments": [
      { "day": "2026-10-20", "kind": "published", "listing": { "code": "HEWPUTA8", "title": "Apartament 3 camere Copou" } }
    ],
    "contacts": {
      "sources": [ { "source": "message", "count": 11 }, { "source": "phone", "count": 7 } ],
      "new": 4,
      "in_progress": 9
    }
  }
}
```

* `previous` are totalurile perioadei de dinainte, de aceeași lungime, ca să vezi dacă anunțurile merg mai bine sau mai rău.
* Cheia unui cont fără echipă (o persoană sau un agent) primește anunțurile contului (`scope: account`), iar `top` are cele mai văzute cinci anunțuri.
* Cheia titularului, a unui administrator sau a unui manager primește anunțurile echipei pe care o vede în portal (`scope: team`): titularul și administratorii toată firma, managerul echipa lui. `top` are atunci colegii cu cele mai multe vizualizări. Cu `agent=<email>` primești doar cifrele unui coleg.
* `moments` și `contacts` vin din cererile clienților, așa că le primești doar dacă cheia are și `leads:read`. Fără el sunt `null`.

## Zilele unui anunț

`GET /account/listings/{code}/stats?from=2026-10-01&to=2026-10-31` dă zilele unui singur anunț, cel mult 90 într-o cerere. Fără `from` și `to` primești ultimele 30 de zile, cu azi. O dată din viitor se oprește la azi.

```json theme={null}
{
  "data": {
    "code": "HEWPUTA8",
    "from": "2026-10-01",
    "to": "2026-10-31",
    "timezone": "UTC",
    "days": [ { "day": "2026-10-01", "views": 18, "saves": 1, "contacts": 0, "partial": false } ],
    "totals": { "views": 512, "saves": 20, "contacts": 6 },
    "views_total": 3120
  }
}
```

`views_total` are toate vizualizările de la publicare. Pentru un raport săptămânal către proprietar ceri ultimele 7 zile ale anunțului și le compari cu săptămâna de dinainte.

## Cifrele din lista anunțurilor

Fiecare anunț din `GET /account/listings` și `GET /account/listings/{code}` are rândul din Anunțurile mele:

```json theme={null}
"stats_30d": { "views": 512, "saves": 20, "contacts": 6 },
"views_total": 3120
```

Dacă vrei doar cifrele, ceri `fields=code,stats_30d,views_total`.

## Prețul față de zonă

Anunțul are și comparația de pe pagina lui, când o ceri în `fields`:

```json theme={null}
"price_per_sqm": 1850,
"price_vs_area": {
  "listing_sqm": 1850, "median_sqm": 1720, "delta_pct": 8,
  "p25_sqm": 1540, "p75_sqm": 1930,
  "median_price": 112000, "p25_price": 100000, "p75_price": 125000,
  "sample": 46
}
```

* `price_per_sqm` e prețul pe metru pătrat, în euro, doar la vânzare.
* `price_vs_area` compară anunțul cu anunțurile de același tip și cu aceeași tranzacție din zonă: mediana, intervalul tipic (între `p25` și `p75` stă jumătatea din mijloc a anunțurilor) și cât de departe e anunțul de mediană (`delta_pct`, pozitiv peste, negativ sub). Valorile `*_price` sunt aceleași, socotite la suprafața anunțului.
* `price_vs_area` e `null` când zona nu are destule anunțuri comparabile, la fel ca pe pagina anunțului.
* Comparația se calculează pentru fiecare anunț, așa că vine doar când o ceri în `fields`, la `GET /account/listings` sau la `GET /account/listings/{code}`, de exemplu `fields=code,price_per_sqm,price_vs_area`. Răspunsul unei scrieri (`POST`, `PUT`, `PATCH`) nu o are.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.