# Price and activity time series for an area

> **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph).

`POST https://platform.casafari.com/v1/area-insights/time-series`

[Area Insights](/docs/area-insights) · [REST API](/docs/rest/area-insights). Send `Authorization: Bearer $CASAFARI_API_KEY`: a platform API key (`cf_sk_...`) from [the console](https://platform.casafari.com/console), or an OAuth access token; `X-API-Key` carries the key too. See [platform API keys](/docs/rest#platform-api-keys). Costs 25 tokens a call (1 token = EUR 0.04).

Over MCP: [`area-insights_get_time_series_data`](/docs/area-insights/get_time_series_data) (equivalent). See [MCP and REST compared](/docs/parity#area-insights).

The platform's OpenAPI file leaves the shape open; what is shown comes from the same definitions the platform publishes elsewhere: request: the existing API's POST /market-analytics-api/time-series, the same backend; response 200: the existing API's POST /market-analytics-api/time-series.

## Description

Costs 25 tokens a call.

## Request body

Content type `application/json`. Optional. Type: `object`.

- `types` (string[], required): The list of property types by type groups: **apartment:** ["apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung"] **house:** ["country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe"] **room:** ["room"] **building:** ["apartment_building", "office_building", "mix_use_building"] **investment:** ["retail", "office", "industrial", "warehouse", "hotel", "building", "other_commercial", "restaurant", "werkstatt"] **development:** ["apartment_development", "house_development"] **plot:** ["urban_plot", "rural_plot"] **other:** ["parking", "garage", "other"] *Note that you can select multiple types only from one property type group.* Some types exist only in some countries: **Germany:** dachgeschosswohnung, etagenwohnung, erdgeschosswohnung, family_house, reihenhaus, reihenendhaus, reihenmittelhaus, einfamilienhaus, zweifamilienhaus, landwirtschaftliche_betriebe, restaurant, werkstatt; **France, Germany, Italy, Portugal, Spain:** urban_plot, rural_plot. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `building`, `other_commercial`, `restaurant`, `werkstatt`, `urban_plot`, `rural_plot`, `room`, `parking`, `garage`, `other`, `apartment_building`, `office_building`, `mix_use_building`, `apartment_development`, `house_development`. at least 1 item.
- `business_type` (string, required) Values: `sale`, `rent`.
- `price_range` (object, optional, nullable)
  - `min` (integer, optional, nullable) 1–2147483647.
  - `max` (integer, optional, nullable) 1–2147483647.
- `price_per_sqm_range` (object, optional, nullable)
  - `min` (integer, optional, nullable) 1–2147483647.
  - `max` (integer, optional, nullable) 1–2147483647.
- `rooms_range` (object, optional, nullable)
  - `min` (integer, optional, nullable) 1–15000.
  - `max` (integer, optional, nullable) 1–15000.
- `bedrooms_range` (object, optional, nullable)
  - `min` (integer, optional, nullable) 0–15000.
  - `max` (integer, optional, nullable) 0–15000.
- `bathrooms_range` (object, optional, nullable)
  - `min` (integer, optional, nullable) 1–15000.
  - `max` (integer, optional, nullable) 1–15000.
- `total_area_range` (object, optional, nullable)
  - `min` (integer, optional, nullable) 1–1000000.
  - `max` (integer, optional, nullable) 1–1000000.
- `plot_area_range` (object, optional, nullable)
  - `min` (integer, optional, nullable) 1–1000000.
  - `max` (integer, optional, nullable) 1–1000000.
- `construction_year_range` (object, optional, nullable)
  - `min` (integer, optional, nullable) 1–3000.
  - `max` (integer, optional, nullable) 1–3000.
- `characteristics` (object, optional, nullable)
  - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`.
  - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`.
- `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item.
- `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional.
- `bank` (boolean, optional): Whether the property is owned by the bank.
- `auction` (boolean, optional): Whether the property is the subject of an auction. default false.
- `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default false.
- `custom_location_boundary` (object, required)
  - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647.
  - `polygon` (object[], optional): List of geo-points to search within. Polygon must contain at least 4 points. First and last points must match. at least 4 items.
    - `latitude` (number, required) -90–90.
    - `longitude` (number, required) -180–180.
  - `circle` (object, optional): Circle boundary to search within.
    - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000.
    - `target_point` (object, required): Target point coordinates to search around.
      - `latitude` (number, required) -90–90.
      - `longitude` (number, required) -180–180.
- `data_point` (string, required): Specifies the type of real estate data to retrieve for a given period. Values: `avg_price`, `avg_price_psqm`, `available_on_market`, `new`, `sold_or_rented`, `price_up`, `price_down`.
- `date_interval` (string, required): Defines the time interval for aggregating data points. Determines the frequency at which data is reported in the response. Values: `week`, `month`, `quarter`, `year`.
- `date_range` (object, required)
  - `min` (string (date), required): Start date in the format `YYYY-MM-DD`. If the specified date is not Monday - the closest previous Monday will be selected.
  - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`. If the specified date is not Sunday - the closest previous Sunday will be selected.

## Example request

Placeholders only: replace the token and the values with your own.

```bash
curl -X POST "https://platform.casafari.com/v1/area-insights/time-series" \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "types": [
    "apartment"
  ],
  "business_type": "sale",
  "custom_location_boundary": {
    "location_ids": [
      11737
    ]
  },
  "data_point": "avg_price_psqm",
  "date_interval": "quarter",
  "date_range": {
    "min": "2024-01-01",
    "max": "2025-12-31"
  }
}'
```

## Responses

### 200 Success.

Type: `object[]`.

- `date_start` (string (date), required): The starting date of the period associated with the passed `date_interval` field value. The format follows `YYYY-MM-DD`.
- `value` (number, required): The numerical value corresponding to the passed `data_point` field value for the given `date_start`.

Example from a real call (Madrid, apartments for sale) (long arrays shortened):

```json
[
  {
    "date_start": "2024-01-01",
    "value": 5294.94
  },
  {
    "date_start": "2024-04-01",
    "value": 5421.34
  }
]
```

### Errors

Every error is an `application/problem+json` body (RFC 9457) with `type` (a page that explains it), `title`, `status`, `detail` (what to do), `instance`, `code` and `request_id` (what to quote to support). A `402` carries an `upgrade_url`, a `429` a `Retry-After` header. The codes each status can carry:

- `400`: `invalid_request`, `key_in_query` (https://platform.casafari.com/errors/invalid-request, https://platform.casafari.com/errors/key-in-query)
- `401`: `unauthorized`, `invalid_credential`, `credential_revoked`, `token_expired` (https://platform.casafari.com/errors/unauthorized, https://platform.casafari.com/errors/invalid-credential, https://platform.casafari.com/errors/credential-revoked, https://platform.casafari.com/errors/token-expired)
- `402`: `payment_required` (https://platform.casafari.com/errors/payment-required)
- `403`: `insufficient_scope`, `not_entitled`, `account_suspended` (https://platform.casafari.com/errors/insufficient-scope, https://platform.casafari.com/errors/not-entitled, https://platform.casafari.com/errors/account-suspended)
- `404`: `not_found` (https://platform.casafari.com/errors/not-found)
- `405`: `method_not_allowed` (https://platform.casafari.com/errors/method-not-allowed)
- `409`: `conflict` (https://platform.casafari.com/errors/conflict)
- `413`: `payload_too_large` (https://platform.casafari.com/errors/payload-too-large)
- `415`: `unsupported_media_type` (https://platform.casafari.com/errors/unsupported-media-type)
- `422`: `validation_failed` (https://platform.casafari.com/errors/validation-failed)
- `429`: `rate_limited`, `daily_limit_reached`, `request_limit_reached`, `usage_limit_reached` (https://platform.casafari.com/errors/rate-limited, https://platform.casafari.com/errors/daily-limit-reached, https://platform.casafari.com/errors/request-limit-reached, https://platform.casafari.com/errors/usage-limit-reached)
- `500`: `internal_error` (https://platform.casafari.com/errors/internal-error)
- `502`: `upstream_error` (https://platform.casafari.com/errors/upstream-error)
- `503`: `capacity_exhausted`, `unavailable` (https://platform.casafari.com/errors/capacity-exhausted, https://platform.casafari.com/errors/unavailable)
- `504`: `upstream_timeout` (https://platform.casafari.com/errors/upstream-timeout)

## Related pages

- [Market analysis of an area (POST /v1/area-insights/analysis)](/docs/rest/area-insights/market-analysis-of-an-area)
- [Property type distribution in an area (POST /v1/area-insights/distributions/properties)](/docs/rest/area-insights/property-type-distribution-in-an-area)
- [Price distribution in an area (POST /v1/area-insights/distributions/prices)](/docs/rest/area-insights/price-distribution-in-an-area)
- [Bedrooms distribution in an area (POST /v1/area-insights/distributions/bedrooms)](/docs/rest/area-insights/bedrooms-distribution-in-an-area)
- [Area Insights REST API: all operations](/docs/rest/area-insights)
- [How to get a bearer token for the Casafari REST API](/docs/rest)
- [MCP vs REST API compared](/docs/parity)