1) Consulta por logradouro:

Nesse tipo de consulta, é fornecido o parâmetro de entrada logradouro, que deve conter o nome do logradouro que se pretende consultar. O serviço retorna uma coordenada geográfica referente ao(s) logradouro(s) encontrado(s). Caso o numero não seja informado será retornada o endereco com o menor numero de logradouro existente. Ex: Para o logradouro Rua Minas Novas são encontrados 38 endereços variando entre o numero 14 e 274. Portanto o serviço retornará o endereço cujo o numero é 14.

Chamada ao serviço:

Resultado obtido:

2) Consulta por logradouro popular:

Nesse tipo de consulta, é fornecido como parâmetro de entrada o nome popular do logradouro, ou seja, um nome conhecido mas não oficial. Além disso, deve ser informado um parâmetro que indique a busca de logradouro popular ( classificacao=popular ). O serviço retorna o nome oficial e a coordenada geográfica referente ao(s) logradouro(s) encontrado(s).

Chamada ao serviço:

Resultado obtido:

3) Consulta por logradouro oficial e popular:

Nesse tipo de consulta, é fornecido como parâmetro de entrada o nome do logradouro e a busca é feita considerando os nomes oficiais e populares. Para tal, deve ser informado um parâmetro que indique que a busca deve ser completa ( classificacao=completo ). O serviço retorna o nome oficial e a coordenada geográfica referente ao(s) logradouro(s) encontrado(s). É importante destacar que a flexibilidade da busca integrando os dois tipos de logradouros implica em possível perda de qualidade do resultado.

Chamada ao serviço:

Resultado obtido:

4) Consulta por codigo do logradouro e número

Nesse tipo de consulta, são fornecidos os parâmetros de entrada: o código e o número do logradouro.

Chamada ao serviço:

Resultado obtido:

5) Consulta por número do logradouro e número

Nesse tipo de consulta, são fornecidos os parâmetros de entrada logradouro e numero, que devem conter, respectivamente, o nome do logradouro e o número do imóvel que se pretende consultar.

Chamada ao serviço:

Resultado obtido:

6) Consulta por nome do logradouro e número com letra

Nesse tipo de consulta, são fornecidos os parâmetros de entrada logradouro e número, que devem conter, respectivamente, o nome do logradouro e o número do imóvel com a letra que se pretende consultar.

Chamada ao serviço:

Resultado obtido:

7) Consulta por nome do logradouro, número e bairro

Nesse tipo de consulta são fornecidos os parâmetros de entrada logradouro, numero e bairro, que devem conter, respectivamente, o nome do logradouro, o número do imóvel e o nome do bairro. O serviço retorna a coordenada geográfica referente ao endereço encontrado.

Chamada ao serviço:

Resultado obtido:

8) Consulta por nome do logradouro, número com letra e bairro

Nesse tipo de consulta são fornecidos os parâmetros de entrada logradouro, numero e bairro, que devem conter, respectivamente, o nome do logradouro, o número do imóvel com a letra e o nome do bairro. O serviço retorna a coordenada geográfica referente ao endereço encontrado.

Chamada ao serviço:

Resultado obtido:

9) Consulta por bairro

Nesse tipo de consulta, é informado o parâmetro de entrada bairro, que deve conter o nome do bairro que se pretende consultar. O serviço retorna a coordenada geográfica referente ao primeiro endereço encontrado no bairro.

Chamada ao serviço:

Resultado obtido:

10) Consulta por CEP

Nesse tipo de consulta é fornecido o parâmetros de entrada cep, que deve conter o número do CEP. O serviço retorna a coordenada geográfica pertencente ao primeiro numero de logradouro encontrado a partir do CEP informado. Quando buscamos apenas por cep, poderiam ser retornados múltiplos endereços que pertençam aquele cep, porém o serviço retorna apenas endereço que possua o menor numero de logradouro. Ex: Para o Cep 30310-090 são encontrados 38 endereços na Rua Minas Novas variando entre o numero 14 e 274. Portanto nosso serviço retornará o endereço cujo o numero é 14.

Chamada ao serviço:

Resultado obtido:

11) Consulta por CEP e número

Nesse tipo de consulta são fornecidos os parâmetros de entrada cep e numero, que devem conter, respectivamente, o número do CEP e o número do imóvel. O serviço retorna a coordenada geográfica referente ao endereço encontrado.

Chamada ao serviço:

Resultado obtido:

12) Consulta por CEP e número com letra

Nesse tipo de consulta são fornecidos os parâmetros de entrada cep e numero, que devem conter, respectivamente, o número do CEP e o número do imóvel com letra. O serviço retorna a coordenada geográfica referente ao endereço encontrado.

Chamada ao serviço:

Resultado obtido:

13) Consulta de endereço por id

Nessa consulta é possível buscar as informações de um endereço, dado seu id.

Exemplo de chamada ao serviço:

Resultado obtido:

1) Consulta por única coordenada:

Este serviço recebe dois parâmetros, ponto e distancia(opcional). O serviço retorna o endereço referente a coordenada e distância indicadas. Caso não encontre endereço dentro do raio informado, ele retornará um JSON com id vazio.

Chamada ao serviço:

Exemplo de retorno para consultas com apenas um ponto:

2) Consulta com múltiplas coordenadas:

Este serviço recebe como parâmetros múltiplos pontos e a distância (opcional). Deve-se separar cada ponto por vírgula.

O serviço retorna os endereços referente às coordenadas pesquisadas, seguindo a mesma ordenação dos pontos informados.

Exemplo de coordenadas:

POINT(612905.595953109 7796291.76966232),POINT(611376.555220056 7796659.80606211),POINT(608283.395804183 7799770.55397166)

Exemplo de consulta:

Resultado obtido:

1) Busca por número aproximado

Nesse tipo de consulta,são fornecidos tipo de logradouro, nome do logradouro, numero do logradouro e o parametro aproximado como verdadeiro.

Ex: Se buscamos Avenida Afonso Pena. O primeiro numero de logradouro encontrado na base é o 254. Portanto caso informemos qualquer valor entre 1 e 254 será retornado Avenida Afonso Pena, 254.

Chamada ao serviço:

Resultado obtido:

2) Busca por número aproximado com paridade

Nesse tipo de consulta, são fornecidos tipo de logradouro, nome do logradouro, numero do logradouro, aproximado e paridade como verdadeiros. Paridade significa dizer que queremos buscar o endereço aproximado no mesmo lado da rua informado.

Ex1: Se buscamos Avenida Afonso Pena, 1. O primeiro numero de logradouro ímpar mais proximo de 1 encontrado na base é o 255. Portanto será retornado Avenida Afonso Pena, 255.

Ex2: Se buscamos Avenida Afonso Pena, 2. O primeiro numero de logradouro par mais proximo de 2 encontrado na base é o 254. Portanto será retornado Avenida Afonso Pena, 254.

Chamada ao serviço:

Resultado obtido:

3) Busca por número aproximado com limite de aproximação

Nesse tipo de consulta,são fornecidos tipo de logradouro, nome do logradouro, numero do logradouro, o parametro aproximado como verdadeiro e o limite de aproximação. Este limite deve ser um valor inteiro maior que zero.

Ex1: Se buscamos Avenida Afonso Pena, 155, com limite de aproximação igual a 100. Será buscado o logradouro mais proximo do numero 155 na base encontrado entre Avenida Afonso Pena, 55 e Avenida Afonso Pena, 255

Ex2: Se informamos Avenida Afonso Pena, 101, com limite de aproximação igual a 100. Não será encontrado endereço algum , já que não existem nenhum endereço em nossa base entre Avenida Afonso Pena, 1 e Avenida Afonso Pena, 201.

Chamada ao serviço:

Resultado obtido:

4) Busca por número aproximado com limite de aproximação e paridade

Nesse tipo de consulta, são fornecidos tipo de logradouro, nome do logradouro, numero do logradouro,limite de aproximação, aproximado e paridade como verdadeiros. Ou seja, queremos buscar um endereço no mesmo lado da rua até um determinado limite

Ex1: Se buscamos Avenida Afonso Pena, 1, com limite de aproximação igual a 300 e paridade verdadeira. Será buscado o primeiro endereço ímpar mais proximo de 1 encontrado na base em Avenida Afonso Pena entre o limite de logradouro 1 e 300

Chamada ao serviço:

Resultado obtido:

A API diferencia o status HTTP da resposta de acordo com a situação do retorno. Para simplificar o tratamento das respostas, os possíveis códigos de status retornados foram limitados para as opções abaixo:

Além do status HTTP, a resposta inclui uma mensagem genérica para o usuário e uma mensagem detalhada para o desenvolvedor, facilitando a identificação do erro.

1) Sucesso com resultado

HTTP status: 200 OK

2) Sucesso sem resultados

HTTP status: 200 OK

3) Erro na requisição

HTTP status: 400 BAD REQUEST

4) Erro no servidor

HTTP status: 500 INTERNAL SERVER ERROR