Esse documento aborda as funcionalidades do geolocalização, o serviço de consulta a endereços da Prefeitura de Belo Horizonte (PBH).
Geolocalização é um web service REST que possibilita consultas a endereços na base da PBH, tendo como resposta um objeto JSON, que contém, entre outros atributos, a coordenada geográfica pertencente ao endereço pretendido.
O serviço possibilita ao usuário os seguintes tipos de consulta:
Parâmetros de entrada do serviço geolocalização
A chamada ao serviço geolocalização tem o seguinte formato:
Foram definidos os seguintes parâmetros de entrada para o serviço, a saber:
Padrão de resposta do serviço geolocalização no formato JSON
Objeto JSON de resposta com uma tupla:
{
"endereco":
{
"bairropopular":"Padre Eustáquio",
"cep":"30720060",
"idbairro":"121",
"id":"83150",
"idlogradouro":"58527",
"idregional":"5",
"idterritorio":"10",
"siglaterritorio":"CS5",
"nomelogradouro":"RIACHUELO",
"nomeregional":"NOROESTE",
"numero":"1477",
"tipologradouro":"RUA",
"wkt":"POINT(607102.256839604 7797526.04284156)"
}
}
Objeto JSON de resposta com N tuplas:
{
"endereco":[
{
"bairropopular":"",
"cep":"",
"idbairro":"",
"id":"355158",
"idlogradouro":"1259",
"idregional":"",
"idterritorio":"",
"siglaterritorio":"",
"nomelogradouro":"AFONSO PENA",
"nomeregional":"",
"numero":"",
"tipologradouro":"AVENIDA",
"wkt":"POINT(610953.797568434 7797526.6227256)"
},
{
"bairropopular":"",
"cep":"",
"idbairro":"",
"id":"450753",
"idlogradouro":"1261",
"idregional":"",
"idterritorio":"",
"siglaterritorio":"",
"nomelogradouro":"AFONSO PENA JUNIOR",
"nomeregional":"",
"numero":"",
"tipologradouro":"RUA",
"wkt":"POINT(612355.423050508 7800399.26825121)"
}]
}
Caso não seja encontrada nenhuma resposta, o retorno do serviço será:
{
"endereco":
{
"id":""
}
}
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). Exemplo de consulta:
Chamada ao serviço:
Resultado obtido:
{
"endereco":[
{
"bairropopular":"",
"cep":"",
"idbairro":"",
"id":"355158",
"idlogradouro":"1259",
"idregional":"",
"idterritorio":"",
"siglaterritorio":"",
"nomelogradouro":"AFONSO PENA",
"nomeregional":"",
"numero":"",
"tipologradouro":"AVENIDA",
"wkt":"POINT(610953.797568434 7797526.6227256)"
},
{
"bairropopular":"",
"cep":"",
"idbairro":"",
"id":"450753",
"idlogradouro":"1261",
"idregional":"",
"idterritorio":"",
"siglaterritorio":"",
"nomelogradouro":"AFONSO PENA JUNIOR",
"nomeregional":"",
"numero":"",
"tipologradouro":"RUA",
"wkt":"POINT(612355.423050508 7800399.26825121)"
},
{
"bairropopular":"",
"cep":"",
"idbairro":"",
"id":"528860",
"idlogradouro":"304916",
"idregional":"",
"idterritorio":"",
"siglaterritorio":"",
"nomelogradouro":"AFONSO PENA",
"nomeregional":"",
"numero":"",
"tipologradouro":"BECO",
"wkt":"POINT(615595.449734951 7804109.92619029)"
}]
}
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. Segue abaixo um exemplo de consulta:
Chamada ao serviço:
Resultado obtido:
{
"endereco":
{
"bairropopular":"Centro",
"cep":"30130908",
"idbairro":"37",
"id":"6821",
"idlogradouro":"1259",
"idregional":"2",
"idterritorio":"29",
"siglaterritorio":"O2",
"nomelogradouro":"AFONSO PENA",
"nomeregional":"CENTRO-SUL",
"numero":"1212",
"tipologradouro":"AVENIDA",
"wkt":"POINT(611376.555302274 7796659.80607242)"
}
}
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. Segue abaixo um exemplo de consulta:
Chamada ao serviço:
Resultado obtido:
{
"endereco":
{
"bairropopular":"Santa Efigênia",
"cep":"30150350",
"idbairro":"141",
"id":"6102",
"idlogradouro":"42747",
"idregional":"2",
"idterritorio":"29",
"siglaterritorio":"O2",
"letra":"A",
"nomelogradouro":"MANAUS",
"nomeregional":"CENTRO-SUL",
"numero":"516",
"tipologradouro":"RUA",
"wkt":"POINT(612900.186741748 7796291.9896287)"
}
}
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:
{
"endereco":
{
"bairropopular":"Centro",
"cep":"30130908",
"idbairro":"37",
"id":"6821",
"idlogradouro":"1259",
"idregional":"2",
"idterritorio":"29",
"siglaterritorio":"O2",
"nomelogradouro":"AFONSO PENA",
"nomeregional":"CENTRO-SUL",
"numero":"1212",
"tipologradouro":"AVENIDA",
"wkt":"POINT(611376.555302274 7796659.80607242)"
}
}
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:
{
"endereco":
{
"bairropopular":"Santa Efigênia",
"cep":"30150350",
"idbairro":"141",
"id":"6102",
"idlogradouro":"42747",
"idregional":"2",
"idterritorio":"29",
"siglaterritorio":"O2",
"letra":"A",
"nomelogradouro":"MANAUS",
"nomeregional":"CENTRO-SUL",
"numero":"516",
"tipologradouro":"RUA",
"wkt":"POINT(612900.186741748 7796291.9896287)"
}
}
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 centróide do bairro encontrado.
Chamada ao serviço:
Resultado obtido:
{
"endereco":
{
"bairropopular":"Buritis",
"cep":"",
"idbairro":"18",
"id":"",
"idlogradouro":"",
"idregional":"",
"idterritorio":"",
"siglaterritorio":"",
"nomelogradouro":"",
"nomeregional":"",
"numero":"",
"tipologradouro":"",
"wkt":"POINT(607870.692673383 7790847.35043903)"
}
}
Nesse tipo de consulta é fornecido o parâmetros de entrada cep, que deve conter número do CEP. O serviço retorna a coordenada geográfica pertencente ao logradouro com o CEP informado.
Chamada ao serviço:
Resultado obtido:
{
"endereco":
{
"bairropopular":"",
"cep":"30720530",
"idbairro":"",
"id":"445788",
"idlogradouro":"",
"idregional":"",
"idterritorio":"",
"siglaterritorio":"",
"nomelogradouro":"",
"nomeregional":"",
"numero":"",
"tipologradouro":"",
"wkt":"POINT(607174.383502849 7799030.76192641)"
}
}
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:
{
"endereco":
{
"bairropopular":"",
"cep":"30130908",
"idbairro":"",
"id":"6821",
"idlogradouro":"",
"idregional":"",
"idterritorio":"",
"siglaterritorio":"",
"nomelogradouro":"",
"nomeregional":"",
"numero":"1212",
"tipologradouro":"",
"wkt":"POINT(611376.555302274 7796659.80607242)"
}
}
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:
{
"endereco":
{
"bairropopular":"",
"cep":"30150350",
"idbairro":"",
"id":"6100",
"idlogradouro":"",
"idregional":"",
"letra":"C",
"nomelogradouro":"",
"nomeregional":"",
"numero":"516",
"tipologradouro":"",
"wkt":"POINT(612892.493340947 7796298.10840506)"
}
}
Ponto em formato wkt:
Distância:
Instruções de utilização e retorno:
Este serviço recebe dois parâmetros, ponto e distancia(opcional).
Ponto é uma coordenada no formato WKT, e distância um valor maior que 10. Caso não seja passando um valor de distância, o serviço assumirá 10 como valor. O serviço irá retornar o id do Endereço mais próximo da coordenada passada como parâmetro. Caso não encontre endereço dentro do raio informado, ele retornará um JSON com id vazio.
Realizando a chamada do serviço com apenas um ponto como parâmetro. Exemplo:
Chamada ao serviço:
O retorno é um JSON cujo o elemento raiz é 'endereco'.
Exemplo de retorno para consultas com apenas um ponto:
{
"endereco":
{
"id":"460390",
"numero":"1476",
"cep":"30720060",
"wkt":"POINT(607107.995968176 7797543.31938658)",
"nomelogradouro":"RIACHUELO",
"idlogradouro":"58527",
"tipologradouro":"RUA",
"bairropopular":"Padre Eustáquio",
"idbairro":"121",
"nomeregional":"NOROESTE"
}
}
A passagem como parâmetro de multiplos pontos deve conter como elemento separador dos mesmos a VIRGULA, por exemplo.
Exemplo de chamada e resposta para consultas envolvendo multiplos pontos:
POINT(607108.49522605 7797536.4531855),POINT(607158.49522605 7797540.4531855),POINT(607308.49522605 7797836.4531855)
Exemplo de consulta:
O retorno é um elemento JSON, cuja raiz é Endereco, contendo um array cujo tamanho é equivalente ao número de pontos informados como parâmetro, seguindo a mesma ordenação dos pontos, e seu retorno tem a estrutura a seguir:
{
"endereco":
[
{
"id":"460390",
"numero":"1476",
"cep":"30720060",
"wkt":"POINT(607107.995968176 7797543.31938658)",
"nomelogradouro":"RIACHUELO",
"idlogradouro":"58527",
"tipologradouro":"RUA",
"bairropopular":"Padre Eustáquio",
"idbairro":"121",
"nomeregional":"NOROESTE"
},
{
"id":"347286",
"numero":"841",
"cep":"30720320",
"wkt":"POINT(607148.780062884 7797545.02904469)",
"nomelogradouro":"PROGRESSO",
"idlogradouro":"55759",
"tipologradouro":"RUA",
"bairropopular":"Padre Eustáquio",
"idbairro":"121",
"nomeregional":"NOROESTE"
},
{
"id":"305215",
"numero":"1086",
"cep":"30720310",
"wkt":"POINT(607299.786760495 7797835.86088386)",
"nomelogradouro":"CASTIGLIANO",
"idlogradouro":"14056",
"tipologradouro":"RUA",
"bairropopular":"Padre Eustáquio",
"idbairro":"121",
"nomeregional":"NOROESTE"
}
]
}
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:
| Código | Status HTTP | Situação |
|---|---|---|
| 200 | OK | A requisição foi tratada com sucesso. |
| 400 | Bad Request | A requisição enviada apresenta alguma característica inválida. |
| 500 | Internal Server Error | A requisição está correta mas ocorreu um erro interno no sistema. |
Além do status HTTP, a resposta inclui uma mensagem genérica para o usuário e uma mensagem detalhada para facilitar a identificação do erro.
| Mensagem | Descrição |
|---|---|
| Parâmetros de requisição inválidos. | ... |
| Erro ao obter conexão com banco de dados. | ... |
HTTP status: 200 OK
{
"status": "ok",
"endereco":
{
"bairropopular":"Padre Eustáquio",
"cep":"30720060",
"idbairro":"121",
"id":"83150",
"idlogradouro":"58527",
"idregional":"5",
"idterritorio":"10",
"siglaterritorio":"CS5",
"nomelogradouro":"RIACHUELO",
"nomeregional":"NOROESTE",
"numero":"1477",
"tipologradouro":"RUA",
"wkt":"POINT(607102.256839604 7797526.04284156)"
}
}HTTP status: 200 OK
{
"status": "ok",
"endereco": {
"id":""
}
}HTTP status: 400 BAD REQUEST
{
"status": "erro",
"endereco": {
"id":""
},
"erro": "Parâmetros de requisição inválidos."
}HTTP status: 500 INTERNAL SERVER ERROR
{
"status": "erro",
"endereco": {
"id":""
},
"erro": "Erro de banco de dados. Veja descrição para outras informações.",
"detalhes": "Name db_geocoder is not bound in this Context"
}