# Suggest Birth Locality

> The Suggest Birth Locality endpoint searches official and historical birth localities and returns the corresponding Belfiore code.

The Suggest Birth Locality endpoint searches official and historical **birth localities** and returns the corresponding Belfiore code.

## Endpoint

`POST https://{host}:{port}/Egon/api/suggest/birthLocality`

Replace `{host}` and `{port}` with the address of your Egon instance.

## Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | String | Yes | Authentication token sent in the `token` request header. |

## Request

Search query and optional birth date filtering.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `par` | Object | Yes | Processing parameters for birth locality search |
| `par.function` | String | No | Data set to search: `official`, `historical`, or `all`. Default: `all`. Default value: `all` |
| `par.level` | Number | No | Search level: `1` for Country and `5` for City |
| `data` | Object | Yes | Search criteria for birth locality lookup |
| `data.province_code` | String | No | Province code |
| `data.locality` | String | No | Locality description |
| `data.locality_id` | Number | No | Locality identifier |
| `data.belfiore_code` | String | No | Belfiore code |
| `data.minimum_date` | String | No | Start of validity date (format: YYYY-MM-DD) |
| `data.maximum_date` | String | No | End of validity date (format: YYYY-MM-DD) |

### Example request

```bash
curl -X POST "https://{host}:{port}/Egon/api/suggest/birthLocality" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"par":{"function":"official","level":5},"data":{"locality":"Viter"}}'
```

## Response

Birth locality candidate list, Belfiore codes, and system status.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | Object | No |  |
| `data.results` | Array | No | Array of candidate matches returned by the suggestion engine |
| `data.results.locality_id` | Number | No | Locality identifier |
| `data.results.province_code` | String | No | Province code |
| `data.results.locality` | String | No | Locality description |
| `data.results.belfiore_code` | String | No | Belfiore code. In case of historical code it will be preceded by S- |
| `data.results.minimum_date` | String | No | Start of validity date (format: YYYY-MM-DD) |
| `data.results.maximum_date` | String | No | End of validity date (format: YYYY-MM-DD) |
| `system` | Object | No | System error and execution status |
| `system.ret_code` | Number | No | Code: 0 no blocking error, <> 0 blocking error code |
| `system.des_ret_code` | String | No | Description |

### Example responses

**HTTP 200: Valid response**

Birth locality candidate list, Belfiore codes, and system status.

```json
{
  "data": {
    "results": [
      {
        "locality_id": 38000000303,
        "province_code": "VT",
        "locality": "Viterbo",
        "belfiore_code": "M082",
        "minimum_date": "00010101 00:00:00",
        "maximum_date": "99991231 23:59:59"
      }
    ]
  },
  "system": {
    "ret_code": 0,
    "des_ret_code": "Ok"
  }
}
```

**HTTP 200: Missing par**

The par object is missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "par not found"
  }
}
```

**HTTP 200: Missing data**

The data object is missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "data not found"
  }
}
```

**HTTP 200: Missing token**

The token request header is missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "token not found"
  }
}
```

**HTTP 200: Invalid token**

The token is invalid.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "token not valid"
  }
}
```