# Search locations by name or postcode

> **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).

`GET https://platform.casafari.com/v1/locations/search`

[REST API](/docs/rest) · [Location Lookup](/docs/rest/locations). 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). Free: 0 tokens.

Over MCP: `locations_search`, on every product's server.

## Description

Free (uses no tokens). Search by name, by postcode, or both. Each result has a kind (country, region, province, city, district, neighbourhood, development or other), the same in every country, and level, its depth in the tree (the country is 1; depths differ between countries). Results come exact name or alias first, then cities before districts, regions and provinces, neighbourhoods and developments. Postcodes: Spain, France (partly) and Portugal (parts of Lisbon) only; other countries have none, and country with postcode for one answers 400. Pass `country` when you know it.

## Query parameters

- `query` (string, optional): A place name or alias; misspellings are tolerated. Required unless postcode is given. 1–100 characters.
- `postcode` (string, optional): The places this postcode covers, smallest area first (for example 28019 or 1950-102). One postcode matches several places. Postcodes: Spain, France (partly) and Portugal (parts of Lisbon) only; other countries have none, and country with postcode for one answers 400. Pass `country` when you know it. 3–10 characters.
- `postcode_match` (string, optional): exact (default) matches a full-length code; prefix matches the start of one (280, 1950). 2-digit Spanish province prefixes are not postcodes. Needs postcode. Values: `exact`, `prefix`. default "exact".
- `country` (string, optional): ISO 3166-1 alpha-2 country code to restrict the search to; must be entitled. Pass it when you know it; with postcode it must be ES, FR or PT. 2–2 characters.
- `lang` (string, optional): Language of the names returned. Values: `en`, `es`, `pt`, `fr`, `de`, `it`, `pl`. default "en".
- `size` (integer, optional): Page size, at most 25 (a Free plan account is capped lower). 1–25.

## Example request

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

```bash
curl "https://platform.casafari.com/v1/locations/search" \
  -H "Authorization: Bearer $CASAFARI_API_KEY"
```

## Responses

### 200 Success.

Type: `object`.

### 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`, `page_depth_exceeded` (https://platform.casafari.com/errors/invalid-request, https://platform.casafari.com/errors/key-in-query, https://platform.casafari.com/errors/page-depth-exceeded)
- `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)
- `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)
- `429`: `rate_limited`, `request_limit_reached` (https://platform.casafari.com/errors/rate-limited, https://platform.casafari.com/errors/request-limit-reached)
- `500`: `internal_error` (https://platform.casafari.com/errors/internal-error)
- `502`: `upstream_error` (https://platform.casafari.com/errors/upstream-error)
- `503`: `unavailable` (https://platform.casafari.com/errors/unavailable)
- `504`: `upstream_timeout` (https://platform.casafari.com/errors/upstream-timeout)

## Related pages

- [Get a location with its parents (GET /v1/locations/{location_id})](/docs/rest/locations/get-a-location-with-its-parents)
- [List the child locations of a location (GET /v1/locations/{location_id}/children)](/docs/rest/locations/list-the-child-locations-of-a-location)
- [Find the locations that contain a point (GET /v1/locations/by-coordinates)](/docs/rest/locations/find-the-locations-that-contain-a-point)
- [Location Lookup REST API: all operations](/docs/rest/locations)
- [How to get a bearer token for the Casafari REST API](/docs/rest)
- [MCP vs REST API compared](/docs/parity)