# Time On Market Distribution

> **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://api.casafari.com/market-analytics-api/distributions/time-on-market`

[Area Insights](/docs/area-insights) · [REST API](/docs/rest/area-insights). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token).

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

## Description

Returns time on market (days and months) distribution by price ranges.

Each distribution unit is defined by price boundaries and includes the time on market for properties within those boundaries.

## Request body

Content type `application/json`. Required. 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.* The list of property types specific to certain countries: **apartment:** ○ dachgeschosswohnung: **Germany** ○ etagenwohnung: **Germany** ○ erdgeschosswohnung: **Germany** **house:** ○ family_house: **Germany** ○ reihenhaus: **Germany** ○ reihenendhaus: **Germany** ○ reihenmittelhaus: **Germany** ○ einfamilienhaus: **Germany** ○ zweifamilienhaus: **Germany** ○ landwirtschaftliche_betriebe: **Germany** **investment:** ○ restaurant: **Germany** ○ werkstatt: **Germany** **plot:** ○ urban_plot: **Italy, Germany, Portugal, Spain, France** ○ rural_plot: **Italy, Germany, Portugal, Spain, France** 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.
- `date_range` (object, optional): Filter properties based on the start date of their last active period on the market.
  - `min` (string (date), required): Start date in the format `YYYY-MM-DD`.
  - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`.

## Example request

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

```bash
curl -X POST "https://api.casafari.com/market-analytics-api/distributions/time-on-market" \
  -H "Authorization: Bearer $CASAFARI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "types": [
    "apartment"
  ],
  "business_type": "sale",
  "custom_location_boundary": {
    "location_ids": [
      1
    ]
  }
}'
```

## Responses

### 200 Successful Response

Type: `object[]`.

- `lower_bound` (integer, required): The lower price bound of the distribution unit.
- `upper_bound` (integer, required): The upper price bound of the distribution unit.
- `days_on_market` (integer, required): The average days on the market.
- `months_on_market` (number, required): The average months on the market.
- `properties_count` (integer, required): The number of properties that participated in the distribution.

### 204 No Content

No body.

### 400 Bad Request

Type: `object`.

- `message` (string, required)
- `errors` (string[], optional, nullable)
- `details` (string, optional, nullable)

### 422 Validation Error

Type: `object`.

- `detail` (object[], optional)
  - `loc` ((string | integer)[], required)
  - `msg` (string, required)
  - `type` (string, required)
  - `input` (any, optional)
  - `ctx` (object, optional)

## Questions about this

- [How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap)