> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/other-services/reverse-geocoding.md).

# Reverse Geocoding

This API translates a location on the map (coordinates of **latitude and longitude**) to a **human-readable address**.

The service converts geographic coordinates into detailed address information, including **country**, **administrative areas** and **formatted addresses**.

### Endpoint

```
POST /reverse-geocoding
```

### Headers

| Name          | Type   | Required | Description                       |
| ------------- | ------ | -------- | --------------------------------- |
| **x-api-key** | string | **Yes**  | API Key for access authorization. |

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter   | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| `latitude`  | number | **Yes**  | Numeric representation of the **latitude coordinate**.  |
| `longitude` | number | **Yes**  | Numeric representation of the **longitude coordinate**. |

#### Request example

```json
{
  "latitude": -70.961452,
  "longitude": 100.714224
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter                                   | Type   | Description                                                         |
| ------------------------------------------- | ------ | ------------------------------------------------------------------- |
| `results`                                   | array  | Array of geocoding results with address information.                |
| `results[].address_components`              | array  | Array of address components with detailed location information.     |
| `results[].address_components[].long_name`  | string | **Full name** of the address component.                             |
| `results[].address_components[].short_name` | string | **Abbreviated name** of the address component.                      |
| `results[].address_components[].types`      | array  | Types of the address component.                                     |
| `results[].formatted_address`               | string | Formatted address **human-readable**.                               |
| `results[].geocoding.distance`              | number | Distance from the requested coordinates (`null` for exact matches). |
| `results[].geocoding.type`                  | string | Geocoding match type (e.g., `"Exact"`).                             |
| `results[].types`                           | array  | Geocoding result types.                                             |

#### Response example

```json
{
  "results": [
    {
      "address_components": [
        {
          "long_name": "Antarctica",
          "short_name": "AQ",
          "types": [
            "country",
            "political",
            "Admin-0 country",
            "Indeterminate"
          ]
        }
      ],
      "formatted_address": "Antarctica",
      "geocoding": {
        "distance": null,
        "type": "Exact"
      },
      "types": [
        "country",
        "political"
      ]
    }
  ]
}
```

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

```json
{
  "message": "Unauthorized"
}
```

#### `403` Forbidden

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "Endpoint request timed out"
}
```