> For the complete documentation index, see [llms.txt](https://chekin.gitbook.io/chekin-public-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chekin.gitbook.io/chekin-public-api/api-reference/guests/location-and-document-fields.md).

# Location fields

This page explains **what value to send** for location fields: cities, provinces and municipalities, for every country.

To know **when** a field is required, use the [Guest Schema](/chekin-public-api/api-reference/guests/guest-schema.md).

***

## The rule

If a location field has an `options_url`, take the value from that list and send its **code**, not its name.

A city is sent with **three keys**:

| Key              | Value                      | Example     |
| ---------------- | -------------------------- | ----------- |
| `*_country`      | Country code               | `IT`        |
| `*_city`         | City **name**              | `Abbasanta` |
| `*_municipality` | City **code**, as a string | `420095001` |

A province is a single key that takes the **code**, for example `residence_province: "ES-M"`.

{% hint style="warning" %}
**Common mistakes**

* **The code is sent in `*_city`.** The guest is saved, but the city stays empty in the dashboard and in the Police report.
* **`*_municipality` is sent as an object.** Retrieve returns it as `{"code", "name"}`, but create and update requests take only the code string.
* **A province is sent by name** (`"Madrid"`). It's saved as text and never matched to a province.
  {% endhint %}

## Where this applies

| Country     | Fields                                                                           |
| ----------- | -------------------------------------------------------------------------------- |
| 🇮🇹 Italy  | `birth_place_*`, `document_expedition_*`, `residence_city`, `residence_province` |
| 🇪🇸 Spain  | `residence_province`, `residence_city`                                           |
| 🇧🇷 Brazil | `residence_province`, `residence_city`                                           |
| 🇯🇵 Japan  | `residence_province`                                                             |
| Other       | `arrived_from_*`, `next_destination_*` (district / municipality)                 |

The schema tells you which of these fields a reservation needs. A field that has an `options_url` always follows the rule above.

## Example: 🇮🇹 Italy, place of birth and document issue place

Take the code from `division_level_3.code` in the `/locations-search` results.

```json
{
  "birth_place_country": "IT",
  "birth_place_city": "Accettura",
  "birth_place_municipality": "417077001",

  "document_expedition_country": "IT",
  "document_expedition_city": "Abbasanta",
  "document_expedition_municipality": "420095001"
}
```

{% hint style="warning" %}
Don't leave out the `*_country` keys. Without them, the city and code are not saved as a location.
{% endhint %}

## Example: 🇪🇸 Spain, residence province

Take the code from `division_level_2.code`. Spain has 50 provinces, and autonomous-community codes such as `ES-MD` are rejected.

```json
{
  "residence_country": "ES",
  "residence_province": "ES-M"
}
```

After you send the province, request the schema again. The `residence_city` list then shows only the municipalities of that province.

{% hint style="info" %}
**Fixing guests that are already created:** send the correct keys with [Update Guest](/chekin-public-api/api-reference/guests/update-guest.md). For a city, send all three keys together.
{% endhint %}