---
title: "API Geolocation Crédito"
description: "Geocodificação reversa (lat/lon → endereço, tipo geocode) e direta (endereço → coordenadas, tipo forward-geocoding), cobrada por consulta."
lang: pt-BR
canonical: https://doc.apibrasil.io/apis/creditos/6ecd521d-b23d-4684-9add-c75b6d36df9f
markdown: https://doc.apibrasil.io/apis/creditos/6ecd521d-b23d-4684-9add-c75b6d36df9f.md
source: apibrasil-documentation
---

# API Geolocation Crédito

> Geocodificação reversa (lat/lon → endereço, tipo geocode) e direta (endereço → coordenadas, tipo forward-geocoding), cobrada por consulta.

- **Categoria:** Geolocalização e Logística
- **Cobrança:** por consulta, só com o Bearer Token
- **Preço:** R$ 0,09 por consulta
- **Limite:** 999.000 por mês
- **Cadastro:** exige CNPJ
- **Versão:** v2
- **Publicada por:** APIBrasil
- **Especificação OpenAPI:** https://doc.apibrasil.io/apis/creditos/6ecd521d-b23d-4684-9add-c75b6d36df9f/openapi.json

## Como chamar

**Endereço base:** `https://gateway.apibrasil.io/api/v2`

Autenticação: cabeçalho `Authorization: Bearer <token>`. Nada além disso.

Com `homolog: true` no corpo, o gateway responde de uma base fixa, com a forma real da resposta, e não cobra. O CPF 00000000000 é dessa base e não é de ninguém: use-o nos testes, nunca em produção.

## Endpoints (4 endpoints)

**Sumário**

1. `POST /consulta/geolocation-credits/credits`
2. `POST /consulta/geolocation-credits/credits`
3. `POST /consulta/geolocation-credits/credits`
4. `POST /consulta/geolocation-credits/credits`

### 1. POST /consulta/geolocation-credits/credits

API Geolocation Crédito - Geocodificação reversa (homologação)

Converte coordenadas ("lat" e "lon") em endereço: rua, bairro, cidade, estado, CEP, país e o endereço completo formatado. Com "homolog": true a resposta traz um endereço fictício no mesmo formato da produção, sem consultar o fornecedor e sem cobrança.

- **Método:** `POST`
- **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/geolocation-credits/credits`
- **Versão da rota:** v2

**Cabeçalhos**

| Cabeçalho | Valor |
| --- | --- |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer $APIBRASIL_TOKEN` |

**Corpo da requisição**

```json
{
  "tipo": "geocode",
  "homolog": true,
  "lat": -19.9322,
  "lon": -43.938
}
```

**Em cURL**

```bash
curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/geolocation-credits/credits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIBRASIL_TOKEN" \
  -d '{"tipo":"geocode","homolog":true,"lat":-19.9322,"lon":-43.938}'
```

Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação.

**Resposta de exemplo, do catálogo**

```json
{
  "user": {
    "first_name": "[omitido]",
    "email": "[omitido]",
    "cellphone": "[omitido]",
    "notification": "yes"
  },
  "balance": "1.000,000",
  "balance_before": "1.000,000",
  "tax": "0,000",
  "status_code": 200,
  "error": false,
  "message": "Dados validos em homologacao! Voce nao foi tarifado e a requisicao nao foi contabilizada.",
  "valor_consulta": 0,
  "api_limit_for": "homolog",
  "homolog": true,
  "data": {
    "address": {
      "city": "Cidade Exemplo",
      "city_district": "Distrito Exemplo",
      "country": "Brazil",
      "country_code": "br",
      "county": "Condado Exemplo",
      "municipality": "Municipio Exemplo",
      "neighbourhood": "Bairro Exemplo",
      "postcode": "30000-000",
      "region": "Regiao Exemplo",
      "road": "Rua Exemplo",
      "state": "Minas Gerais",
      "state_district": "Regiao Metropolitana"
    },
    "boundingbox": [
      "-19.9300",
      "-19.9200",
      "-43.9500",
      "-43.9400"
    ],
    "display_name": "Rua Exemplo, Bairro Exemplo, Cidade Exemplo, Minas Gerais, Brazil",
    "lat": "-19.9250",
    "licence_by": "https://apibrasil.io",
    "lon": "-43.9450",
    "osm_id": "123456789",
    "osm_type": "way",
    "place_id": "987654321"
  }
}
```

### 2. POST /consulta/geolocation-credits/credits

API Geolocation Crédito - Geocodificação reversa (produção)

Com "homolog": false as coordenadas são consultadas no fornecedor e a resposta traz o endereço real do ponto. A cobrança acontece só quando há resultado: coordenadas fora do intervalo (latitude de -90 a 90, longitude de -180 a 180) devolvem 400 sem cobrança.

- **Método:** `POST`
- **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/geolocation-credits/credits`
- **Versão da rota:** v2

**Cabeçalhos**

| Cabeçalho | Valor |
| --- | --- |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer $APIBRASIL_TOKEN` |

**Corpo da requisição**

```json
{
  "tipo": "geocode",
  "homolog": false,
  "lat": -19.9322,
  "lon": -43.938
}
```

**Em cURL**

```bash
curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/geolocation-credits/credits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIBRASIL_TOKEN" \
  -d '{"tipo":"geocode","homolog":false,"lat":-19.9322,"lon":-43.938}'
```

Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação.

**Resposta de exemplo, do catálogo**

```json
{
  "user": {
    "first_name": "[omitido]",
    "email": "[omitido]",
    "cellphone": "[omitido]",
    "notification": "yes"
  },
  "balance": "999,910",
  "balance_before": "1.000,000",
  "tax": "0,090",
  "status_code": 200,
  "error": false,
  "message": "Dados validos! Voce foi tarifado em R$ 0,09.",
  "valor_consulta": 0.09,
  "api_limit_for": "credit",
  "homolog": false,
  "data": {
    "address": {
      "city": "Belo Horizonte",
      "city_district": "Regional Centro-Sul",
      "country": "Brazil",
      "country_code": "br",
      "county": "Região Metropolitana de Belo Horizonte",
      "municipality": "Região Geográfica Imediata de Belo Horizonte",
      "neighbourhood": null,
      "postcode": "30140-140",
      "region": "Southeast Region",
      "road": "Alameda Travessia",
      "state": "Minas Gerais",
      "state_district": "Região Geográfica Intermediária de Belo Horizonte"
    },
    "boundingbox": [
      "-19.9329564",
      "-19.9312096",
      "-43.9383392",
      "-43.9378336"
    ],
    "display_name": "Alameda Travessia, Savassi, Regional Centro-Sul, Belo Horizonte, Região Geográfica Imediata de Belo Horizonte, Região Metropolitana de Belo Horizonte, Região Geográfica Intermediária de Belo Horizonte, Minas Gerais, Southeast Region, 30140-140, Brazil",
    "lat": "-19.9321661",
    "licence_by": "https://apibrasil.io",
    "lon": "-43.9381273",
    "osm_id": "844448192",
    "osm_type": "way",
    "place_id": "12103719"
  }
}
```

### 3. POST /consulta/geolocation-credits/credits

API Geolocation Crédito - Geocodificação direta (homologação)

Converte um endereço em texto ("query") em coordenadas e endereço estruturado: latitude, longitude, rua, número, bairro, cidade, estado, CEP e país, com o grau de confiança do resultado. Com "homolog": true a resposta traz dados fictícios no mesmo formato da produção, sem consultar o fornecedor e sem cobrança.

- **Método:** `POST`
- **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/geolocation-credits/credits`
- **Versão da rota:** v2

**Cabeçalhos**

| Cabeçalho | Valor |
| --- | --- |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer $APIBRASIL_TOKEN` |

**Corpo da requisição**

```json
{
  "tipo": "forward-geocoding",
  "homolog": true,
  "query": "Avenida Afonso Pena 1212, Belo Horizonte"
}
```

**Em cURL**

```bash
curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/geolocation-credits/credits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIBRASIL_TOKEN" \
  -d '{"tipo":"forward-geocoding","homolog":true,"query":"Avenida Afonso Pena 1212, Belo Horizonte"}'
```

Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação.

**Resposta de exemplo, do catálogo**

```json
{
  "user": {
    "first_name": "[omitido]",
    "email": "[omitido]",
    "cellphone": "[omitido]",
    "notification": "yes"
  },
  "balance": "1.000,000",
  "balance_before": "1.000,000",
  "tax": "0,000",
  "status_code": 200,
  "error": false,
  "message": "Dados validos em homologacao! Voce nao foi tarifado e a requisicao nao foi contabilizada.",
  "valor_consulta": 0,
  "api_limit_for": "homolog",
  "homolog": true,
  "data": {
    "administrative_area": "Area Exemplo",
    "confidence": 1,
    "continent": "South America",
    "country": "Brazil",
    "country_code": "BRA",
    "county": "Condado Exemplo",
    "label": "Rua Exemplo, 100, Cidade Exemplo, MG, Brasil",
    "latitude": -19.925,
    "licence_by": "https://apibrasil.io",
    "locality": "Cidade Exemplo",
    "longitude": -43.945,
    "name": "Rua Exemplo",
    "neighbourhood": "Centro",
    "number": "100",
    "postal_code": "30000000",
    "region": "Minas Gerais",
    "region_code": "MG",
    "street": "Rua Exemplo",
    "type": "address"
  }
}
```

### 4. POST /consulta/geolocation-credits/credits

API Geolocation Crédito - Geocodificação direta (produção)

Com "homolog": false o endereço é consultado no fornecedor e a resposta traz o melhor resultado encontrado. A cobrança acontece só quando há resultado: endereço que o fornecedor não encontra devolve 404 sem cobrança.

- **Método:** `POST`
- **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/geolocation-credits/credits`
- **Versão da rota:** v2

**Cabeçalhos**

| Cabeçalho | Valor |
| --- | --- |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer $APIBRASIL_TOKEN` |

**Corpo da requisição**

```json
{
  "tipo": "forward-geocoding",
  "homolog": false,
  "query": "Avenida Afonso Pena 1212, Belo Horizonte"
}
```

**Em cURL**

```bash
curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/geolocation-credits/credits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIBRASIL_TOKEN" \
  -d '{"tipo":"forward-geocoding","homolog":false,"query":"Avenida Afonso Pena 1212, Belo Horizonte"}'
```

Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação.

**Resposta de exemplo, do catálogo**

```json
{
  "user": {
    "first_name": "[omitido]",
    "email": "[omitido]",
    "cellphone": "[omitido]",
    "notification": "yes"
  },
  "balance": "999,910",
  "balance_before": "1.000,000",
  "tax": "0,090",
  "status_code": 200,
  "error": false,
  "message": "Dados validos! Voce foi tarifado em R$ 0,09.",
  "valor_consulta": 0.09,
  "api_limit_for": "credit",
  "homolog": false,
  "data": {
    "administrative_area": "Belo Horizonte",
    "confidence": 1,
    "continent": "South America",
    "country": "Brazil",
    "country_code": "BRA",
    "county": "Belo Horizonte",
    "label": "Avenida Afonso Pena, Belo Horizonte, MG, Brazil",
    "latitude": -19.918997,
    "licence_by": "https://apibrasil.io",
    "locality": "Belo Horizonte",
    "longitude": -43.938577,
    "name": "Avenida Afonso Pena",
    "neighbourhood": null,
    "number": null,
    "postal_code": "30000-000",
    "region": "Minas Gerais",
    "region_code": "MG",
    "street": "Avenida Afonso Pena",
    "type": "street"
  }
}
```

Nos exemplos de resposta, os campos da conta que gerou o exemplo (`user.first_name`, `user.email`, `user.cellphone`) saem como `[omitido]`. O resto é o que o catálogo publica.

## Armadilhas: o que uma integração erra sem avisar

Apuradas nas respostas que o próprio catálogo publica. Em todas elas o código funciona no caminho feliz e falha em silêncio no resto:

1. **O erro chega no CORPO, com HTTP 200.**
   A resposta traz um campo `error` booleano e uma `message`. Checar só `response.ok` ou o status HTTP deixa passar falha como sucesso. Confira SEMPRE `error === false` antes de ler `data`.

2. **`balance`, `tax` e `extra_charges.total` são STRING em formato brasileiro — e o formato varia entre APIs.**
   Valores observados no catálogo: `"154,380"`, `"497,84"`, `"0,000"` e `"0.19"`. Vírgula em umas, ponto em outra; três casas decimais em umas, duas em outra. Em JavaScript, `parseFloat("154,380")` devolve `154` e perde os centavos sem erro nenhum, e `Number("154,380")` devolve `NaN`. Escreva um conversor que trate os dois separadores, e nunca use esses campos numa decisão financeira sem convertê-los.

3. **Cada chamada custa dinheiro.**
   Retry cego multiplica a conta. Nunca repita automaticamente um 4xx: parâmetro errado repetido continua errado e continua cobrando. Repita só tempo esgotado e 5xx, com recuo exponencial e um teto pequeno de tentativas.

4. **HTTP 402 é saldo insuficiente, e repetir não resolve.**
   É o único status que exige ação humana — recarregar. Trate-o como erro terminal, com mensagem própria, e não o jogue no mesmo balde dos 4xx genéricos.

5. **`extra_charges` cobra à parte do preço da consulta.**
   Quando o corpo pede serviços adicionais, a resposta traz cada um com o preço e um `total` que NÃO está incluso no valor base. Se você mostra custo a quem usa, some os dois.

## Ver também

- Especificação OpenAPI: https://doc.apibrasil.io/apis/creditos/6ecd521d-b23d-4684-9add-c75b6d36df9f/openapi.json
- Catálogo de APIs: [Catálogo de APIs](https://doc.apibrasil.io/apis.md)
- SDKs oficiais: [SDKs oficiais](https://doc.apibrasil.io/sdks.md)
- Índice da documentação: https://doc.apibrasil.io/llms.txt
- Versão HTML desta página: https://doc.apibrasil.io/apis/creditos/6ecd521d-b23d-4684-9add-c75b6d36df9f