> ## 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.

# Listing statistics

> How to read your listings' views, saves and contacts, by day and by period, and how to compare the price with the area.

Through the API you read the same figures the account sees in Housera: the chart on the account's front page, each listing's row in My listings, and the price comparison with the area on the listing's page. They all need the `listings:read` permission and cover only the listings the key sees (see [Which listings each key sees](https://api.housera.ro/en/concepts/access.md)).

There are three figures:

| Figure | What it counts |
| - | - |
| `views` | Visits to the listing's page. The same person coming back on the same day counts once. |
| `saves` | How many times the listing was saved to favourites. |
| `contacts` | Client requests that came through the listing: messages, call requests and viewing requests. A contact added by hand is not counted here. |

Days are calendar days in the time zone given in `timezone`. Today comes with `partial: true` because it is not over yet, and its figures keep growing until midnight.

## The account's chart

`GET /account/stats?range=30` gives the chart from the account's front page, over 7, 30 or 90 days:

```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@example.com" }, "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` holds the totals of the period before, of the same length, so you can see whether the listings are doing better or worse.
* The key of an account with no team (a person or an agent) gets the account's listings (`scope: account`), and `top` has the five most viewed listings.
* The key of the owner, an administrator or a manager gets the listings of the team it sees in the portal (`scope: team`): the whole firm for the owner and administrators, their team for a manager. `top` then has the colleagues with the most views. With `agent=<email>` you get one colleague's figures only.
* `moments` and `contacts` come from client requests, so you get them only if the key also has `leads:read`. Without it they are `null`.

## A listing's days

`GET /account/listings/{code}/stats?from=2026-10-01&to=2026-10-31` gives one listing's days, at most 90 in one request. Without `from` and `to` you get the last 30 days, today included. A future date stops at today.

```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` holds every view since the listing was published. For a weekly report to the owner, ask for the listing's last 7 days and compare them with the week before.

## The figures in the listings list

Every listing in `GET /account/listings` and `GET /account/listings/{code}` has its row from My listings:

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

If you only want the figures, ask for `fields=code,stats_30d,views_total`.

## The price against the area

The listing also carries the comparison from its page, when you ask for it in `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` is the price per square metre in euro, for sales only.
* `price_vs_area` compares the listing with listings of the same type and transaction in the area: the median, the typical range (the middle half of the listings sits between `p25` and `p75`) and how far the listing is from the median (`delta_pct`, positive above, negative below). The `*_price` values are the same figures at the listing's surface.
* `price_vs_area` is `null` when the area does not have enough comparable listings, as on the listing's page.
* The comparison is worked out for each listing, so it comes only when you ask for it in `fields`, in `GET /account/listings` or `GET /account/listings/{code}`, for example `fields=code,price_per_sqm,price_vs_area`. The answer to a write (`POST`, `PUT`, `PATCH`) does not have it.


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