# What premises ask in a place

> **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/claro/market`

[Claro AI](/docs/claro) · [REST API](/docs/claro#rest-api). Send `Authorization: Bearer $CASAFARI_API_KEY`: a platform API key or OAuth access token, metered in platform units; see [platform sign-in](/docs/rest#platform-api-keys) and [Claro AI](/docs/claro#keys). On the platform this is `POST https://platform.casafari.com/v1/claro/market`; `POST /v1/market` is Claro's own path, which the platform adds `/claro` to. The platform forwards the call to Claro unchanged: Claro's `Claro-Version` header and its error bodies (`{"error":{"code","message"}}`, with `rate_limited` and `quota_reached` on a 429) pass through.

Over MCP: [`market_snapshot`](/docs/claro/market_snapshot) (equivalent). See [MCP and REST compared](/docs/parity#claro-ai).

## Description

What commercial premises of a kind ask in a place anywhere in Spain, from every active property of that kind and place (each unit counted once): the asking price per m² as a distribution with its median and middle half, by size band, by district or town, and for one town or province the monthly average over three years with the change in a year, the properties on the market and their days on the market (Casafari Area Insights). Ask in plain words (question: "what does retail rent for in Chamberí?") or send criteria as data (place, types, operation, optional size range); other criteria are ignored. Asking prices, not agreed ones; at least 10 properties or no figures. Returns the criteria as understood and `insights`: charts as data, each with a one-sentence answer, its count, scope, source and date.

## Request body

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

- `question` (string, optional): The question in plain words, any language: "what do offices rent for in Valencia?"
- `criteria` (object, optional): Criteria as data. Hard criteria (operation, cities, types, price, area) exclude properties outside them; the rest exclude only properties that state the opposite, and each result says which were met and which the property does not state.
  - `operation` (string, optional) Values: `rent`, `sale`, `either`.
  - `cities` (string[], optional): Spanish towns or cities by name or slug ("valencia", "Palma"). Leave out for all of Spain.
  - `provinces` (string[], optional): Provinces; a property must be in one of them. Values: `a-coruna`, `alava`, `albacete`, `alicante`, `almeria`, `asturias`, `avila`, `badajoz`, `barcelona`, `burgos`, `caceres`, `cadiz`, `cantabria`, `castellon`, `ceuta`, `ciudad-real`, `cordoba`, `cuenca`, `girona`, `granada`, `guadalajara`, `guipuzcoa`, `huelva`, `huesca`, `islas-baleares`, `jaen`, `la-rioja`, `las-palmas`, `leon`, `lleida`, `lugo`, `madrid`, `malaga`, `melilla`, `murcia`, `navarra`, `ourense`, `palencia`, `pontevedra`, `salamanca`, `santa-cruz-de-tenerife`, `segovia`, `sevilla`, `soria`, `tarragona`, `teruel`, `toledo`, `valencia`, `valladolid`, `vizcaya`, `zamora`, `zaragoza`.
  - `districts` (string[], optional): Named districts or neighbourhoods in the cities (Centro, Malasaña, Chamberí, Eixample, Gràcia, Poblenou...). A property outside them is out; one that does not state its district stays, marked not stated.
  - `types` (string[], optional) Values: `hotel`, `retail`, `warehouse`, `industrial`, `office`, `other_commercial`.
  - `area_min` (number, optional)
  - `area_max` (number, optional)
  - `price_min` (number, optional): EUR: a month for rent, the total for a sale; applies to each operation without its own rent_/sale_ limit.
  - `price_max` (number, optional)
  - `rent_price_min` (number, optional): EUR a month; compared only with rents.
  - `rent_price_max` (number, optional): EUR a month; compared only with rents. With sale_price_max, operation "either" keeps a property whose rent or sale price fits its own limit.
  - `sale_price_min` (number, optional): EUR total; compared only with sale prices.
  - `sale_price_max` (number, optional)
  - `price_m2_min` (number, optional): EUR per m² of the property's area (a month for rent); a property with no stated area is "not stated".
  - `price_m2_max` (number, optional)
  - `rent_price_m2_min` (number, optional)
  - `rent_price_m2_max` (number, optional)
  - `sale_price_m2_min` (number, optional)
  - `sale_price_m2_max` (number, optional)
  - `street_level` (boolean, optional)
  - `frontage_min_m` (number, optional): Facade length (fachada) in metres.
  - `frontage_max_m` (number, optional)
  - `floors_min` (number, optional): Number of floors (plantas) the premises has.
  - `floors_max` (number, optional)
  - `ceiling_min_m` (number, optional)
  - `smoke_extraction` (boolean, optional)
  - `corner` (boolean, optional)
  - `shop_window` (boolean, optional)
  - `open_plan` (boolean, optional)
  - `step_free` (boolean, optional)
  - `loading_access` (boolean, optional)
  - `licence` (string, optional) Values: `food_service`, `retail`, `office`, `gym`, `none`.
  - `licence_activities` (string[], optional): Activities its licence sentence must name, in Spanish or Catalan: cafetería, panadería, restaurante...
  - `transfer_price_min` (number, optional): Transfer fee (traspaso) in EUR; met when its stated range overlaps.
  - `transfer_price_max` (number, optional)
  - `business_transfer` (boolean, optional): true: only business transfers (traspasos); false: none.
  - `business_types` (string[], optional): Uses its text says it suits, in English: restaurant, cafe, gym...
  - `keywords` (string[][], optional): Groups of phrases; a property meets a group when its text holds any phrase. Write phrases as Spanish agencies do.
  - `exclude_keywords` (string[], optional): Leave out properties whose text holds any of these.
  - `footfall_min` (number, optional): Minimum footfall index within a 5-minute walk (an index of pedestrian activity that compares places; not a head count). Needs location data access.
  - `pop_walk10_min` (number, optional): Residents within a 10-minute walk. Needs location data access.
  - `pop_drive10_min` (number, optional): Residents within a 10-minute drive. Needs location data access.
  - `transit_min` (number, optional): Stations and stops within a 5-minute walk. Needs location data access.
  - `competitors_max` (object[], optional): At most this many places of a kind within a 5-minute walk (gyms: 10). Needs location data access.
    - `kind` (string, required) Values: `restaurants`, `fast_food`, `cafes`, `shops`, `supermarkets`, `gyms`.
    - `max` (number, required)
  - `own_stores_away_m` (number, optional): No store from your own list (upload it with PUT /v1/stores) within this many metres of the premises, straight-line, 1-1,000. Needs an exact pin.
  - `competitors_near_max` (object[], optional): At most `max` businesses of a segment (or of the named `chains`) within `within_m` straight-line metres (1-1,000), from Overture Maps places. A property with an approximate pin gets no verdict.
    - `segment` (string, required) Values: `gym`, `burger`, `fast_food`, `coffee`, `bakery`, `pharmacy`, `supermarket`, `fashion`, `pizza`.
    - `within_m` (number, required)
    - `max` (number, required)
    - `chains` (string[], optional): Only these brands count (rivals or your own), e.g. Burger King, Basic-Fit. Matched on Overture brand and name.
  - `spending_per_resident_min` (number, optional): Spending power a resident a year (EUR) within a 10-minute walk. Needs location data access.
  - `high_income_share_min` (number, optional): % of households within a 10-minute walk with net income above 40,162 EUR a year. Needs location data access.
  - `age_shares_min` (object[], optional): Minimum % of residents within a 10-minute walk in an age band. Needs location data access.
    - `band` (string, required) Values: `0_14`, `15_29`, `30_44`, `45_59`, `60p`.
    - `min_pct` (number, required)
  - `meaning` (string, optional): A wish no field holds, in any language; ranks results, never filters.
  - `sort` (string, optional): supply_gap ranks where residents per similar place is highest (residents within a 10-minute walk / (places within gap_radius_m, 600 m by default, + 1)); needs gap_segment or one competitors_near_max segment. Needs location data access; unscored properties go last. Values: `best`, `price_asc`, `price_desc`, `area_desc`, `footfall_desc`, `supply_gap`.
  - `gap_segment` (string, optional): The business kind the supply_gap sort counts. Values: `gym`, `burger`, `fast_food`, `coffee`, `bakery`, `pharmacy`, `supermarket`, `fashion`, `pizza`.
  - `gap_radius_m` (integer, optional): Radius in metres in which the supply_gap sort counts similar places: 600 (default) or 300 (about a 5-minute walk). Only with sort supply_gap. Values: `300`, `600`.

## Example request

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

```bash
curl -X POST "https://platform.casafari.com/v1/claro/market" \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "<question>"
}'
```

## Responses

### 200 What premises ask in a place

No body.

Example from the API description (long arrays shortened):

```json
{
  "criteria": {
    "operation": "rent",
    "cities": [
      "madrid"
    ],
    "districts": [
      "Chamberí"
    ],
    "types": [
      "retail"
    ]
  },
  "insights": [
    {
      "id": "market",
      "kind": "histogram",
      "title": "Retail premises for rent in Chamberí, Madrid ask a median of €21.0/m² a month; the middle half ask €17.2/m²–€26.4/m² (52 with a stated rent and size).",
      "n": 38,
      "scope": "retail premises for rent in Centro, 100–400 m² (half to twice this size), each unit counted once",
      "source": "Claro properties on the market; asking rents, not agreed ones",
      "as_of": "2026-10-13",
      "unit": "eur_m2_month",
      "bins": [
        {
          "from": 10,
          "to": 15,
          "n": 6
        },
        {
          "from": 15,
          "to": 20,
          "n": 9
        }
      ],
      "open_high": true,
      "median": 21.5,
      "p25": 17.8,
      "p75": 27
    }
  ],
  "notes": []
}
```

### 400 Invalid request

Type: `object`.

- `error` (object, optional)
  - `code` (string, required)
  - `message` (string, required)

### 401 Missing or invalid key

Type: `object`.

- `error` (object, optional)
  - `code` (string, required)
  - `message` (string, required)

### 403 No access

Type: `object`.

- `error` (object, optional)
  - `code` (string, required)
  - `message` (string, required)

### 429 Rate limited

Type: `object`.

- `error` (object, optional)
  - `code` (string, required)
  - `message` (string, required)

## Related pages

- [Search commercial premises (POST /v1/search)](/docs/rest/claro/search-premises)
- [Refine a search (POST /v1/search/refine)](/docs/rest/claro/refine-search)
- [Get one premises (GET /v1/premises/{id})](/docs/rest/claro/get-premises)
- [Compare premises (POST /v1/compare)](/docs/rest/claro/compare-premises)
- [Claro AI: all its MCP tools and REST operations](/docs/claro)
- [Connect Claro to an MCP client](/docs/claro/connect)
- [MCP vs REST API compared](/docs/parity)