# Address from Coordinates

> The Reverse geocoding service retrieves address candidates from geographic coordinates, with street, house number, postal code, and distance.

The Reverse geocoding service retrieves **address candidates** from geographic coordinates, with street, house number, postal code, and distance.

## Endpoint

`POST https://{host}:{port}/Egon/api/revGeo`

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

Geographic coordinates (latitude, longitude), radius, and search options.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `par` | Object | Yes |  |
| `par.iso3` | String | Yes | Country code (ISO 3166-1 alpha-3) |
| `par.type` | String | No | Type of reverse: `P` punctual or `V` vector. Default value: `P` |
| `par.radius` | Number | No | Radius from the input coordinates, in meters. Default value: `100` |
| `par.increase_radius` | Number | No | Increased search radius. Default value: `1` |
| `par.search_attempts` | Number | No | Number of search attempts. Default value: `1` |
| `par.max_candidates` | Number | No | Maximum number of candidates to extract. Default value: `10` |
| `data` | Object | Yes |  |
| `data.latitude` | Number | Yes | Latitude |
| `data.longitude` | Number | Yes | Longitude |

### Example request

```bash
curl -X POST "https://{host}:{port}/Egon/api/revGeo" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"par":{"iso3":"ITA"},"data":{"longitude":10.97382316,"latitude":45.406161}}'
```

## Response

Nearest address candidates, distance, administrative hierarchy, and system status.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | Object | No |  |
| `data.results` | Array | No | Reverse-geocoding results |
| `data.results.hn_id` | Number | No | ID of the number |
| `data.results.province_code` | String | No | Province code |
| `data.results.city` | String | No | City description |
| `data.results.locality` | String | No | District description |
| `data.results.street` | String | No | Street name |
| `data.results.zipcode` | String | No | Postal code |
| `data.results.hn` | String | No | House number |
| `data.results.exponent` | String | No | Exponent |
| `data.results.longitude` | String | No | Longitude |
| `data.results.latitude` | String | No | Latitude |
| `data.results.distance` | Number | No | Distance (in meters) |
| `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**

Nearest address candidates, distance, administrative hierarchy, and system status.

```json
{
  "data": {
    "results": [
      {
        "hn_id": 380100008326045,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO PACINOTTI",
        "zipcode": "37135",
        "hn": "4",
        "exponent": "B",
        "longitude": "10.973796",
        "latitude": "45.406168",
        "distance": 3
      },
      {
        "hn_id": 380600052104491,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO PACINOTTI",
        "zipcode": "37135",
        "hn": "4",
        "exponent": "C",
        "longitude": "10.97373",
        "latitude": "45.4061",
        "distance": 12
      },
      {
        "hn_id": 380100008311753,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO MEUCCI",
        "zipcode": "37135",
        "hn": "1",
        "longitude": "10.973873",
        "latitude": "45.406044",
        "distance": 14
      },
      {
        "hn_id": 380100008326075,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO PACINOTTI",
        "zipcode": "37135",
        "hn": "5",
        "longitude": "10.97367",
        "latitude": "45.40611",
        "distance": 18
      },
      {
        "hn_id": 380100008326087,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO PACINOTTI",
        "zipcode": "37135",
        "hn": "7",
        "exponent": "A",
        "longitude": "10.97367",
        "latitude": "45.4061",
        "distance": 18
      },
      {
        "hn_id": 380100008311777,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO MEUCCI",
        "zipcode": "37135",
        "hn": "2",
        "exponent": "A",
        "longitude": "10.97379",
        "latitude": "45.40588",
        "distance": 31
      },
      {
        "hn_id": 380100008326051,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO PACINOTTI",
        "zipcode": "37135",
        "hn": "4",
        "longitude": "10.9735",
        "latitude": "45.40615",
        "distance": 36
      },
      {
        "hn_id": 380100008311789,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO MEUCCI",
        "zipcode": "37135",
        "hn": "2",
        "longitude": "10.97373",
        "latitude": "45.40574",
        "distance": 48
      },
      {
        "hn_id": 380100008326039,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO PACINOTTI",
        "zipcode": "37135",
        "hn": "4",
        "exponent": "A",
        "longitude": "10.97308",
        "latitude": "45.40625",
        "distance": 83
      },
      {
        "hn_id": 380100008311813,
        "province_code": "VR",
        "city": "VERONA",
        "street": "VIA ANTONIO MEUCCI",
        "zipcode": "37135",
        "hn": "5",
        "longitude": "10.97354",
        "latitude": "45.40536",
        "distance": 94
      }
    ]
  },
  "system": {
    "ret_code": 0,
    "des_ret_code": "Ok"
  }
}
```

**HTTP 200: Missing par**

The request is missing the required par object.

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

**HTTP 200: Invalid iso3**

The iso3 value is not a valid ISO 3166-1 alpha-3 country code.

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

**HTTP 200: Missing data**

The request is missing the required data object.

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

**HTTP 200: Missing token**

Provide the required authentication token in the token request header.

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

**HTTP 200: Invalid token**

The supplied token is invalid, expired, or not authorized for this service.

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