Search commercial premises

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

API key67 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/search; POST /v1/search 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: search_premises (equivalent). MCP and REST compared.

Description

Find shops, restaurant premises, offices, warehouses and other commercial premises for rent or sale anywhere in Spain. Describe the site in plain words in any language (brief), send criteria as data, or both (criteria override the brief). Returns exact counts (matching, all criteria stated, some not stated), the criteria as understood, and the best results: each with its data, what was met and what its text does not state, the sentence that matched, its coordinates (exact, or snapped to the centre of a ~500 m cell and marked approximate when the agency hides the address; none when it has no pin), a fit verdict read from its text, location figures when your account has location access (footfall, residents, nearby places, and in location the footfall split by weekday/weekend, time of day and where the activity comes from live, plus residents by age, households by income and spending power, each null when not stated or unknown, never 0 for unknown; location_sources gives each figure's unit, source and vintage, and when it was computed), and the agency's own listing link. Our fit verdict is one input: every raw figure is there for your own scoring. Up to 200 results a page (50 with a publishable key). next_cursor gets the next page: send it as cursor (alone, with limit if you like); the order is fixed when the search runs and stays the same for its 24 hours, so pages never repeat or skip a premises. page gives offset, limit and the total ranked. The read-through (check) runs only for pages of up to 50. Keep search_id to refine. Keywords only, no model: send just criteria.keywords and/or exclude_keywords (plus any data criteria) with no brief and check: false, e.g. {"criteria": {"operation": "rent", "cities": ["madrid"], "keywords": [["salida de humos", "sortida de fums"], ["esquina", "chaflán"]], "exclude_keywords": ["se traspasa"]}, "check": false}; each keyword group met carries the sentence that matched (evidence) and the phrase it holds (matched).

Request body

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

briefstring

The site brief in plain words, e.g. "burger restaurant, corner unit 120-250 m², smoke outlet, busy street, Madrid, rent under 8,000 a month".

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

limitinteger

Results a page, up to 200; above 50 check is off.

1–200default 10

cursorstring

next_cursor from an earlier answer: returns that search's next page, same criteria and order. Send without brief, criteria or change.

checkboolean

Read the top results' text against the brief (adds a few seconds). Off above 50 results a page and on later pages.

default true

insightsboolean

Add insights, charts as data over every match, each with a one-sentence answer, its count, scope, source and date: per criterion how many matches meet it, leave it unsaid or contradict it (and how many would state everything without it); with one price limit, what it reaches among premises of this kind and place before the limit, else what the matches ask per m²; and where the matches are by district or town. Asking prices; each unit counted once.

default false

Example request

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

curl

curl -X POST "https://platform.casafari.com/v1/claro/search" \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "criteria": {
    "operation": "rent",
    "cities": [
      "madrid"
    ],
    "keywords": [
      [
        "salida de humos",
        "sortida de fums"
      ],
      [
        "esquina",
        "chaflán"
      ]
    ],
    "exclude_keywords": [
      "se traspasa"
    ]
  },
  "check": false
}'

Responses

200 Search commercial premises

No body.

Example from the API description (long arrays shortened)

JSON

{
  "search_id": "s_7hQ2",
  "criteria": {
    "operation": "rent",
    "cities": [
      "madrid"
    ],
    "area_min": 120,
    "smoke_extraction": true
  },
  "counts": {
    "matching": 14,
    "all_criteria_stated": 6,
    "some_not_stated": 8
  },
  "not_applied": [],
  "results": [
    {
      "id": "pm_3kX9vQ2LmT8a",
      "title": "Local comercial en esquina",
      "type": "retail",
      "city": "madrid",
      "city_name": "Madrid",
      "district": "Centro",
      "address": null,
      "location_precision": "approximate",
      "coordinates": {
        "lat": 40.42,
        "lon": -3.705,
        "precision": "approximate"
      },
      "for_rent": true,
      "for_sale": false,
      "rent_eur_month": 5000,
      "sale_eur": null,
      "area_m2": 200,
      "floor_number": 0,
      "street_level": true,
      "floors": 1,
      "frontage_m": null,
      "smoke_outlet": true,
      "business_transfer": false,
      "criteria": [
        {
          "criterion": "smoke_extraction",
          "status": "met",
          "evidence": "con salida de humos"
        }
      ],
      "photos": [
        "https://st2.retelligence.co/c/1234/c/de/abcde350.jpg"
      ],
      "excerpt": "Local en esquina con salida de humos. Zona de mucho paso.",
      "agency": {
        "name": "Agencia Sol",
        "listing_url": "https://agenciasol.es/1"
      },
      "location": {
        "footfall_daily_walk_5min": 50000,
        "footfall_weekday_avg_walk_5min": 52000,
        "footfall_weekend_avg_walk_5min": 41000,
        "residents_walk_10min": 20000,
        "residents_drive_10min": 300000,
        "residents_age_30_44_walk_10min": 5200,
        "households_walk_10min": 9000,
        "households_income_above_57824_walk_10min": null,
        "spending_power_total_eur_walk_10min": 310000000,
        "spending_power_per_resident_eur_walk_10min": 15500,
        "cafes_walk_5min": 12,
        "transit_stops_walk_5min": 5
      },
      "location_sources": {
        "computed_at": "2026-10-12",
        "groups": [
          {
            "fields": [
              "footfall_daily_walk_5min",
              "footfall_weekday_avg_walk_5min"
            ],
            "unit": "footfall index: summed per-cell daily count within the walk, not distinct people (weekday/weekend are daily averages; the others split the daily count)",
            "source": "Targomo Footfall estimates (collection 234)",
            "vintage": "2024"
          },
          {
            "fields": [
              "residents_walk_10min",
              "residents_drive_10min"
            ],
            "unit": "residents",
            "source": "Targomo, MB Research sociodemographics (collection 87)",
            "vintage": "2024"
          }
        ]
      }
    }
  ],
  "page": {
    "offset": 0,
    "limit": 200,
    "total": 14
  },
  "next_cursor": null,
  "notes": [
    "The read-through of the results' text (check) runs only for pages of up to 50; results are ranked by criteria and meaning only."
  ]
}

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

Search commercial premises

#Description

#Request body

#Example request

#Responses

#200 Search commercial premises

#400 Invalid request

#401 Missing or invalid key

#403 No access

#429 Rate limited

#Related pages

Description

Request body

Example request

Responses

200 Search commercial premises

400 Invalid request

401 Missing or invalid key

403 No access

429 Rate limited

Related pages