# Get locations

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

[Existing Casafari API](/docs/existing-api-customers) · [API v1](/docs/existing-api-customers/v1) · References. Send `Authorization: Token $CASAFARI_TOKEN` with your existing API token; see [where to get it](/docs/existing-api-customers#where-to-get-your-existing-token).

The same path under `/api`, signed in with a bearer token, is in the REST API reference: [`POST /api/v1/references/locations`](/docs/rest/references/get-locations-v1).

## Description

Returns a list of all possible locations with user restrictions.

## Request body

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

- `name` (string, optional): Location name to search.
- `coordinates` (object[], optional): Limit search to locations within a closed polygon. First and last points must match. at least 4 items.
  - `latitude` (number, required): Latitude. -90–90.
  - `longitude` (number, required): Longitude. -180–180.
- `zip_codes` (string[], optional): List of zip codes to filter by. at most 15 items.
- `lang` (string, optional): Language to use for the location names in the response. (When the provided language is not supported, the results will be returned in English.)

## Example request

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

```bash
curl -X POST "https://api.casafari.com/v1/references/locations" \
  -H "Authorization: Token $CASAFARI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "ferreiras",
  "coordinates": [
    {
      "longitude": -8.183479,
      "latitude": 37.1404
    },
    {
      "longitude": -8.18482,
      "latitude": 37.13909
    },
    {
      "longitude": -8.1854,
      "latitude": 37.13805
    },
    {
      "longitude": -8.21646,
      "latitude": 37.11383
    },
    {
      "longitude": -8.183479,
      "latitude": 37.1404
    }
  ],
  "lang": "pt"
}'
```

## Responses

### 200

Type: `object`.

- `locations` (object[], required): List of location objects.
  - `location_id` (integer, required): ID of the location.
  - `name` (string, required): Name of the location.
  - `parent_id` (integer, required): ID of the parent level location.
  - `administrative_level` (string, required): Location administrative level.
  - `locations_structure` (object[], required): Information about all the parent locations, starting from the top-most level - country.
    - `location_id` (integer, required): Location ID, as returned by the POST /v1/references/locations endpoint.
    - `name` (string, required): Location name.
    - `administrative_level` (string, required): Location administrative level.
    - `zip_codes` (string[], optional): The location zip codes. default [].
    - `level` (integer, required): Location level as number.

Example from the API description (long arrays shortened):

```json
{
  "locations": [
    {
      "location_id": 1603,
      "name": "Ferreiras",
      "parent_id": 1602,
      "administrative_level": "Freguesia",
      "locations_structure": [
        {
          "location_id": 499,
          "name": "Portugal",
          "administrative_level": "País",
          "zip_codes": [
            "1200-224"
          ],
          "level": 1
        },
        {
          "location_id": 1597,
          "name": "Faro",
          "administrative_level": "Distrito",
          "zip_codes": [],
          "level": 2
        }
      ]
    }
  ]
}
```

### 401 Unauthorized

Type: `object`.

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

### 403 Forbidden

Type: `object`.

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

## Related pages

- [Get agencies (GET /v1/references/agencies)](/docs/existing-api-customers/v1/get-agencies)
- [Get agents (GET /v1/references/agents)](/docs/existing-api-customers/v1/get-agents)
- [Get conditions (GET /v1/references/conditions)](/docs/existing-api-customers/v1/get-conditions)
- [Get features (GET /v1/references/features)](/docs/existing-api-customers/v1/get-features)
- [The same path in the REST API reference (POST /api/v1/references/locations)](/docs/rest/references/get-locations-v1)
- [Existing Casafari API v1: all operations](/docs/existing-api-customers/v1)
- [Existing API customers: token and documentation](/docs/existing-api-customers)