What premises ask in a place

POSThttps://platform.casafari.com/v1/claro/market

API key63 parameters

Send Authorization: Bearer $CASAFARI_API_KEY: a platform API key or OAuth access token, metered in platform units; see platform sign-in and Claro AI. 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 (equivalent). MCP and REST compared.

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.

questionstring

The question in plain words, any language: "what do offices rent for in Valencia?"

criteriaobject

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.

53 properties

operationstring

rent sale either

citiesstring[]

Spanish towns or cities by name or slug ("valencia", "Palma"). Leave out for all of Spain.

provincesstring[]

Provinces; a property must be in one of them.

52 allowed 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

districtsstring[]

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.

typesstring[]

hotel retail warehouse industrial office other_commercial

area_minnumber

area_maxnumber

price_minnumber

EUR: a month for rent, the total for a sale; applies to each operation without its own rent_/sale_ limit.

price_maxnumber

rent_price_minnumber

EUR a month; compared only with rents.

rent_price_maxnumber

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_minnumber

EUR total; compared only with sale prices.

sale_price_maxnumber

price_m2_minnumber

EUR per m² of the property's area (a month for rent); a property with no stated area is "not stated".

price_m2_maxnumber

rent_price_m2_minnumber

rent_price_m2_maxnumber

sale_price_m2_minnumber

sale_price_m2_maxnumber

street_levelboolean

frontage_min_mnumber

Facade length (fachada) in metres.

frontage_max_mnumber

floors_minnumber

Number of floors (plantas) the premises has.

floors_maxnumber

ceiling_min_mnumber

smoke_extractionboolean

cornerboolean

shop_windowboolean

open_planboolean

step_freeboolean

loading_accessboolean

licencestring

food_service retail office gym none

licence_activitiesstring[]

Activities its licence sentence must name, in Spanish or Catalan: cafetería, panadería, restaurante...

transfer_price_minnumber

Transfer fee (traspaso) in EUR; met when its stated range overlaps.

transfer_price_maxnumber

business_transferboolean

true: only business transfers (traspasos); false: none.

business_typesstring[]

Uses its text says it suits, in English: restaurant, cafe, gym...

keywordsstring[][]

Groups of phrases; a property meets a group when its text holds any phrase. Write phrases as Spanish agencies do.

exclude_keywordsstring[]

Leave out properties whose text holds any of these.

footfall_minnumber

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_minnumber

Residents within a 10-minute walk. Needs location data access.

pop_drive10_minnumber

Residents within a 10-minute drive. Needs location data access.

transit_minnumber

Stations and stops within a 5-minute walk. Needs location data access.

competitors_maxobject[]

At most this many places of a kind within a 5-minute walk (gyms: 10). Needs location data access.

2 properties

kindstringrequired

restaurants fast_food cafes shops supermarkets gyms

maxnumberrequired

own_stores_away_mnumber

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_maxobject[]

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.

4 properties

segmentstringrequired

gym burger fast_food coffee bakery pharmacy supermarket fashion pizza

within_mnumberrequired

maxnumberrequired

chainsstring[]

Only these brands count (rivals or your own), e.g. Burger King, Basic-Fit. Matched on Overture brand and name.

spending_per_resident_minnumber

Spending power a resident a year (EUR) within a 10-minute walk. Needs location data access.

high_income_share_minnumber

% of households within a 10-minute walk with net income above 40,162 EUR a year. Needs location data access.

age_shares_minobject[]

Minimum % of residents within a 10-minute walk in an age band. Needs location data access.

2 properties

bandstringrequired

0_14 15_29 30_44 45_59 60p

min_pctnumberrequired

meaningstring

A wish no field holds, in any language; ranks results, never filters.

sortstring

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.

best price_asc price_desc area_desc footfall_desc supply_gap

gap_segmentstring

The business kind the supply_gap sort counts.

gym burger fast_food coffee bakery pharmacy supermarket fashion pizza

gap_radius_minteger

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.

300 600

Example request

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

curl

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.

Show the response shape (3 fields)

errorobject

2 properties

codestringrequired

messagestringrequired

401 Missing or invalid key

Type: object.

Show the response shape (3 fields)

errorobject

2 properties

codestringrequired

messagestringrequired

403 No access

Type: object.

Show the response shape (3 fields)

errorobject

2 properties

codestringrequired

messagestringrequired

429 Rate limited

Type: object.

Show the response shape (3 fields)

errorobject

2 properties

codestringrequired

messagestringrequired

What premises ask in a place

#Description

#Request body

#Example request

#Responses

#200 What premises ask in a place

#400 Invalid request

#401 Missing or invalid key

#403 No access

#429 Rate limited

#Related pages

Description

Request body

Example request

Responses

200 What premises ask in a place

400 Invalid request

401 Missing or invalid key

403 No access

429 Rate limited

Related pages