> 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-pt-br/api-rest/identity-api/identity-api-reference/other-services/reverse-geocoding.md).

# Geocodificação reversa

Esta API traduz um local no mapa (coordenadas de **latitude e longitude**) para um **endereço legível por humanos**.

O serviço converte coordenadas geográficas em informações detalhadas de endereço, incluindo **país**, **áreas administrativas** e **endereços formatados**.

### Endpoint

```
POST /reverse-geocoding
```

### Cabeçalhos

| Nome          | Tipo   | Obrigatório | Descrição                         |
| ------------- | ------ | ----------- | --------------------------------- |
| **x-api-key** | string | **Sim**     | API Key de autorização de acesso. |

### Corpo da solicitação

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

#### Parâmetros

| Parâmetro   | Tipo   | Obrigatório | Descrição                                              |
| ----------- | ------ | ----------- | ------------------------------------------------------ |
| `latitude`  | number | **Sim**     | Representação numérica da **coordenada de latitude**.  |
| `longitude` | number | **Sim**     | Representação numérica da **coordenada de longitude**. |

#### Exemplo de solicitação

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

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro                                   | Tipo   | Descrição                                                                    |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------- |
| `results`                                   | array  | Array de resultados de geocodificação com informações de endereço.           |
| `results[].address_components`              | array  | Array de componentes de endereço com informações detalhadas de localização.  |
| `results[].address_components[].long_name`  | string | **Nome completo** do componente de endereço.                                 |
| `results[].address_components[].short_name` | string | **Nome abreviado** do componente de endereço.                                |
| `results[].address_components[].types`      | array  | Tipos do componente de endereço.                                             |
| `results[].formatted_address`               | string | Endereço formatado **legível por humanos**.                                  |
| `results[].geocoding.distance`              | number | Distância das coordenadas solicitadas (`null` para correspondências exatas). |
| `results[].geocoding.type`                  | string | Tipo de correspondência de geocodificação (por exemplo, `"Exact"`).          |
| `results[].types`                           | array  | Tipos do resultado de geocodificação.                                        |

#### Exemplo de resposta

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

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Requisição inválida",
  "detail": "Solicitação inválida.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Não autorizado

```json
{
  "message": "Não autorizado"
}
```

#### `403` Proibido

```json
{
  "Message": "O usuário não está autorizado a acessar este recurso com uma negação explícita"
}
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Gateway inválido",
  "detail": "O servidor recebeu uma resposta inválida.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "A requisição do Endpoint excedeu o tempo limite"
}
```