# Get locations typeahead suggestions scoped by country code (v1)

> **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/api/v1/references/locations/typeahead`

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

Over MCP: [`ma_get_location_typeahead`](/docs/area-insights/get_location_typeahead) (related). See [MCP and REST compared](/docs/parity#references).

## Description

Returns location typeahead suggestions within the given country (ES or PT).

## Request body

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

- `country_codes` (string[], required): Country codes to scope the search. Supported: ES, PT. Values: `ES`, `PT`.
- `name` (string, required): The location name to search for. 2–100 characters.
- `size` (integer, optional): The maximum number of suggestions to return. Default 30, maximum 100. 1–100; default 30.
- `lang` (string, optional): Language to use for the location name in the response. One of: en, pt, es, de. Values: `en`, `pt`, `es`, `de`. default "en".

## Example request

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

```bash
curl -X POST "https://api.casafari.com/api/v1/references/locations/typeahead" \
  -H "Authorization: Bearer $CASAFARI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "country_codes": [
    "PT"
  ],
  "name": "lisboa",
  "lang": "en",
  "size": 30
}'
```

## Responses

### 200 OK

Type: `object`.

- `typeahead` (object[], required): The typeahead suggestions.
  - `location_id` (integer, required): The location id.
  - `name` (string, required): The location name.
  - `matched_name` (string, required): The matched name of the location name. at most 256 characters.
  - `administrative_level` (string, required): The administrative level.
  - `breadcrumbs` (object[], required): Location breadcrumbs sorted from top to bottom.
    - `location_id` (integer, required): Location ID.
    - `name` (string, required): The name of location.

Example from the API description:

```json
{
  "typeahead": [
    {
      "location_id": 1296,
      "name": "Lisboa",
      "matched_name": "Lisboa",
      "administrative_level": "Distrito",
      "breadcrumbs": [
        {
          "location_id": 499,
          "name": "Portugal"
        },
        {
          "location_id": 1296,
          "name": "Lisboa"
        }
      ]
    }
  ]
}
```

### 401 Unauthorized

Type: `object`.

- `detail` (string, optional): Description of the error encountered.

### 403 Forbidden

Type: `object`.

- `detail` (string, optional): Description of the error encountered.

## Questions about this

- [Which countries does Casafari cover?](/docs/faq/which-countries)
- [Does Casafari cover Spain and Portugal?](/docs/faq/coverage-spain-portugal)
- [Does every tool cover all 16 countries?](/docs/faq/per-tool-coverage)
- [How do I turn a place name into a location id?](/docs/faq/location-ids)