API Geocodificação (Versão 2)

Introdução

Esta API permite consultar a latitude e longitude de um endereço, também conhecido como geocodificação, em inglês, "geocode" ou "geocoding".

API Consultar Geocodificação (Consultar pelo Endereço)

Consulta as coordenadas geográficas de um endereço específico.

Endpoint

GET https://consultar.io/api/v2/geocodificacao/consultar

Requisição

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
endereco	Texto	Sim	Endereço para consulta	RUA EXEMPLO, 123, SAO PAULO, SP

Resposta

Campo	Tipo	Descrição	Exemplo
licenca	Texto	Licença de uso	https://consultar.io/licencas
logradouro	Texto	Logradouro do endereço	Rua Exemplo
bairro	Texto	Bairro do endereço	Exemplo
localidade	Texto	Município do endereço	São Paulo
uf	Texto	Unidade Federativa do endereço	SP
latitude	Número	Latitude do endereço	-23.1234567
longitude	Número	Longitude do endereço	-46.1234567

Exemplos

Exemplo de Requisição (cURL)

curl -X GET 'https://consultar.io/api/v2/geocodificacao/consultar?endereco=RUA+EXEMPLO,+123,SAO+PAULO,+SP' -H 'Authorization: Token <seu-token>'

Exemplo de Resposta de Sucesso (200)

{
  "licencas": "https://consultar.io/licencas",
  "logradouro": "Rua Exemplo",
  "bairro": "Exemplo",
  "localidade": "São Paulo",
  "uf": "SP",
  "latitude": -23.1234567,
  "longitude": -46.1234567
}

Exemplo de Resposta de Erro (404)

{
  "error": "NAO_ENCONTRADO",
  "message": "Nenhum registro foi encontrado para os parâmetros informados."
}

Observações

• Recomendamos informar pelo menos Logradouro, Número (se houver), Município e UF.
• Não recomendamos informar Complemento, Bairro e CEP.
• Não recomendamos usar abreviações.

API Consultar Geocodificação Reversa (Consultar pela Latitude/Longitude)

Consulta o endereço a partir de coordenadas geográficas.

Endpoint

GET https://consultar.io/api/v2/geocodificacao/reversa/consultar

Requisição

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
coordenadas	Texto	Sim	Coordenadas geográficas (latitude e longitude)	-23.1234567,-46.1234567

Resposta

Campo	Tipo	Descrição	Exemplo
licencas	Texto	Creditois da licença de uso do software e dados	https://consultar.io/licencas
logradouro	Texto	Logradouro mais próximo das coordenadas informadas	Rua Exemplo
bairro	Texto	Bairro do logradouro	Exemplo
localidade	Texto	Município do logradouro	São Paulo
uf	Texto	Unidade Federativa do logradouro	SP
latitude	Número	Latitude do logradouro	-23.1234567
longitude	Número	Longitude do logradouro	-46.1234567

Exemplos

Exemplo de Requisição (cURL)

curl -X GET 'https://consultar.io/api/v2/geocodificacao/reversa/consultar?coordenadas=-23.1234567,-46.1234567' -H 'Authorization: Token <seu-token>'

Exemplo de Resposta de Sucesso (200)

{
  "licencas": "https://consultar.io/licencas",
  "logradouro": "Rua Exemplo",
  "bairro": "Exemplo",
  "localidade": "São Paulo",
  "uf": "SP",
  "latitude": -23.1234567,
  "longitude": -46.1234567
}

Exemplo de Resposta de Erro (404)

{
  "error": "NAO_ENCONTRADO",
  "message": "Nenhum registro foi encontrado para os parâmetros informados."
}

Códigos de Status HTTP

Código	Erro (error)	Descrição
400	REQUISICAO_INVALIDA	Veja a mensagem de erro (message) para mais detalhes.
403	PLANO_INATIVO	Plano inativo. Faça uma Recarga.
403	CREDITOS_INSUFICIENTES	Créditos insuficientes. Faça uma Recarga.
404	NAO_ENCONTRADO	Registro não encontrado.
500	ERRO	Veja a mensagem de erro (message) para mais detalhes.
500	ERRO_INTERNO	Ocorreu um erro inesperado no nosso sistema.
503	SERVICO_INDISPONIVEL	Veja a mensagem de erro (message) para mais detalhes.

Limites e Considerações

• Cada requisição "Consultar Geocodificação" consome R$ 0,05 dos créditos
• Cada requisição "Consultar Geocodificação Reversa" consome R$ 0,05 dos créditos
• Somente as respostas com os códigos de status 200 e 404 consomem créditos
• Todas as requisições são registradas no histórico de transações
• O token de autenticação deve ser mantido em segurança
• Em caso de comprometimento do token, entre em contato com o Suporte