API Geocoder e Geocoder Reverso (versão 2.0.1)

Serviço de consulta a endereços da Prefeitura de Belo Horizonte (PBH).

Busca por escolas

O serviço localiza escolas próximas ao endereço informado. É possível limitar a busca para retornar apenas escolas que pertençam à mesma jurisdição do endereço informado.

Para evitar número excessivo de resultados na busca por todas as escolas, utilize os parâmetros "limite" (para indicar o número máximo de resultados) ou "distancia" (para indicar o raio de busca).

Tipos de busca

Chamada ao serviço

Parâmetros de entrada do serviço geolocalização para escolas

Parâmetros obrigatórios:

Parâmetros opcionais:

Tipos de resposta

Resposta de Sucesso

{ 
"escolas": [
{
    "bairro": "Caiçaras",
    "distancia": "746.684565412584",
    "geometria": "POINT (608200.673274671 7798987.72053387)",
    "idJurisdicao": "898",
    "nomeEscola": "INSTITUTO SAGRADA FAMILIA",
    "numeroJurisdicao": "184",
    "regional": "NOROESTE"
},
{
    "bairro": "Caiçaras",
    "distancia": "719.693165246138",
    "geometria": "POINT (608297.438610578 7799018.66434569)",
    "idJurisdicao": "898",
    "nomeEscola": "COLEGIO ANCHIETA",
    "numeroJurisdicao": "184",
    "regional": "NOROESTE"
}],
"status": "ok"
}

Resposta de erro

{
"escolas": {
    "idJurisdicao": ""
},
"status": "erro",
"erro": "Endereço não encontrado."
}

Exemplos de chamadas

1) Consulta por logradouro e número:

URL
Parâmetros

filtro=jurisdicao

logradouro=afonso+pena

numero=1212
Resposta 
{
"escolas": [
    {
        "bairro": "Centro",
        "distancia": "150.843087416416",
        "geometria": "POINT (611244.373935884 7796587.13060613)",
        "idBairro": "37",
        "idJurisdicao": "759",
        "idRegional": "2",
        "nomeEscola": "COLEGIO MINAS GERAIS",
        "numeroJurisdicao": "242",
        "regional": "CENTRO-SUL",
        "tipo": "P"
    
    },
    ....
    {
        "bairro": "Centro",
        "distancia": "764.921223408888",
        "geometria": "POINT (611655.52147859 7795947.56850637)",
        "idBairro": "37",
        "idJurisdicao": "759",
        "idRegional": "2",
        "nomeEscola": "ESCOLA ALBERT EINSTEIN",
        "numeroJurisdicao": "242",
        "regional": "CENTRO-SUL",
        "tipo": "P"
    
    }],
"status": "ok"
}
URL
Parâmetros

filtro=jurisdicao

logradouro=catalao

classificacao=popular

numero=8
Resposta 
								{
"escolas": [
    {
        "bairro": "Caiçaras",
        "distancia": "576.157732500847",
        "geometria": "POINT (608386.856872408 7798903.76732291)",
        "idBairro": "23",
        "idJurisdicao": "898",
        "idRegional": "5",
        "nomeEscola": "SANTOS ANJOS",
        "numeroJurisdicao": "184",
        "regional": "NOROESTE",
        "tipo": "E"
    },
    {
        "bairro": "Caiçaras",
        "distancia": "697.231578502466",
        "geometria": "POINT (609015.068812423 7798984.52117368)",
        "idBairro": "23",
        "idJurisdicao": "898",
        "idRegional": "5",
        "nomeEscola": "PROFESSOR RICARDO SOUZA CRUZ",
        "numeroJurisdicao": "184",
        "regional": "NOROESTE",
        "tipo": "E"
    },
    {
        "bairro": "Caiçaras",
        "distancia": "719.693165246138",
        "geometria": "POINT (608297.438610578 7799018.66434569)",
        "idBairro": "23",
        "idJurisdicao": "898",
        "idRegional": "5",
        "nomeEscola": "COLEGIO ANCHIETA",
        "numeroJurisdicao": "184",
        "regional": "NOROESTE",
        "tipo": "P"
    },
    {
        "bairro": "Caiçaras",
        "distancia": "746.684565412584",
        "geometria": "POINT (608200.673274671 7798987.72053387)",
        "idBairro": "23",
        "idJurisdicao": "898",
        "idRegional": "5",
        "nomeEscola": "INSTITUTO SAGRADA FAMILIA",
        "numeroJurisdicao": "184",
        "regional": "NOROESTE",
        "tipo": "P"
    }],
"status": "ok"
}

3) Consulta por logradouro completo (popular + oficial) e número:

URL
Parâmetros

filtro=jurisdicao

logradouro=catalao

numero=1275

classificacao=completo
Resposta 
{
    "escolas":  {
        "bairro": "Caiçaras",
        "distancia": "843.259587274897",
        "geometria": "POINT (607731.837594768 7799132.16164839)",
        "idBairro": "23",
        "idJurisdicao": "734",
        "idRegional": "5",
        "nomeEscola": "CAIO NELSON DE SENA",
        "numeroJurisdicao": "214",
        "regional": "NOROESTE",
        "tipo": "E"
    },
    "status": "ok"
}

4) Consulta por cep e número:

URL
Parâmetros

filtro=jurisdicao

cep=30150350

numero=516B
Resposta 
{
"escolas": [
    {
        "bairro": "Santa Efigênia",
        "distancia": "165.91161497088",
        "geometria": "POINT (612947.922108562 7796455.50692836)",
        "idBairro": "141",
        "idJurisdicao": "760",
        "idRegional": "2",
        "nomeEscola": "YOLANDA MARTINS SILVA",
        "numeroJurisdicao": "243",
        "regional": "CENTRO-SUL",
        "tipo": "E"
    },
    {
        "bairro": "Santa Efigênia",
        "distancia": "584.26054450834",
        "geometria": "POINT (612334.626955309 7796180.67189013)",
        "idBairro": "141",
        "idJurisdicao": "760",
        "idRegional": "2",
        "nomeEscola": "COLEGIO LOGOSOFICO GONZALEZ PECOTCHE",
        "numeroJurisdicao": "243",
        "regional": "CENTRO-SUL",
        "tipo": "P"
    
    },
    ...
    {
        "bairro": "Santa Efigênia",
        "distancia": "1575.90668396994",
        "geometria": "POINT (611406.570285035 7795814.81505453)",
        "idBairro": "141",
        "idJurisdicao": "760",
        "idRegional": "2",
        "nomeEscola": "CESPRO-CENTRO SUPLETIVO DO PROMOVE",
        "numeroJurisdicao": "243",
        "regional": "CENTRO-SUL",
        "tipo": "P"
    }],
"status": "ok"
}

5) Consulta por cep e número com limite de resultados:

URL
Parâmetros

cep=30150350

numero=516B

limite=2
Resposta 
{
"escolas": [
    {
        "bairro": "Santa Efigênia",
        "distancia": "165.91161497088",
        "geometria": "POINT (612947.922108562 7796455.50692836)",
        "idBairro": "141",
        "idJurisdicao": "760",
        "idRegional": "2",
        "nomeEscola": "YOLANDA MARTINS SILVA",
        "numeroJurisdicao": "243",
        "regional": "CENTRO-SUL",
        "tipo": "E"
    
    },
    {
        "bairro": "Santa Efigênia",
        "distancia": "584.26054450834",
        "geometria": "POINT (612334.626955309 7796180.67189013)",
        "idBairro": "141",
        "idJurisdicao": "760",
        "idRegional": "2",
        "nomeEscola": "COLEGIO LOGOSOFICO GONZALEZ PECOTCHE",
        "numeroJurisdicao": "243",
        "regional": "CENTRO-SUL",
        "tipo": "P"
    }],
"status": "ok"
}

6) Consulta por endereço sem restrição de jurisdição:

URL
Parâmetros

cep=30150350

numero=516B

limite=3
Resposta 
{
"escolas": [
    {
        "bairro": "Santa Efigênia",
        "distancia": "165.91161497088",
        "geometria": "POINT (612947.922108562 7796455.50692836)",
        "idBairro": "141",
        "idJurisdicao": "760",
        "idRegional": "2",
        "nomeEscola": "YOLANDA MARTINS SILVA",
        "numeroJurisdicao": "243",
        "regional": "CENTRO-SUL",
        "tipo": "E"
    },
    {
        "bairro": "São Lucas",
        "distancia": "220.345552859868",
        "geometria": "POINT (613085.801374152 7796164.8350572)",
        "idBairro": "164",
        "idJurisdicao": "880",
        "idRegional": "2",
        "nomeEscola": "MARIA DAS NEVES",
        "numeroJurisdicao": "284",
        "regional": "CENTRO-SUL",
        "tipo": "M"
    },
    {
        "bairro": "Santa Efigênia",
        "distancia": "362.302160617339",
        "geometria": "POINT (613267.457986852 7796337.26057538)",
        "idBairro": "141",
        "idJurisdicao": "880",
        "idRegional": "3",
        "nomeEscola": "MAJOR AMERICO FERREIRA LIMA",
        "numeroJurisdicao": "284",
        "regional": "LESTE",
        "tipo": "E"
    }],
"status": "ok"
}

7) Consulta por jurisdição infantil:

URL
Parâmetros

cep=30150350

numero=516B

tipoJurisdicao=infantil

filtro=jurisdicao

Resposta 
{
"escolas": [
{

    "bairro": "Santa Efigênia",
    "distancia": "165.91161497088",
    "geometria": "POINT (612947.922108562 7796455.50692836)",
    "idBairro": "141",
    "idJurisdicao": "14",
    "idRegional": "2",
    "nomeEscola": "YOLANDA MARTINS SILVA",
    "numeroJurisdicao": "020",
    "regional": "CENTRO-SUL",
    "tipo": "E",
    "tipoJurisdicao": "INFANTIL"

},
{

    "bairro": "Santa Efigênia",
    "distancia": "584.26054450834",
    "geometria": "POINT (612334.626955309 7796180.67189013)",
    "idBairro": "141",
    "idJurisdicao": "14",
    "idRegional": "2",
    "nomeEscola": "COLEGIO LOGOSOFICO GONZALEZ PECOTCHE",
    "numeroJurisdicao": "020",
    "regional": "CENTRO-SUL",
    "tipo": "P",
    "tipoJurisdicao": "INFANTIL"

},
{

    "bairro": "Santa Efigênia",
    "distancia": "824.879550969276",
    "geometria": "POINT (612311.752899765 7796864.89505853)",
    "idBairro": "141",
    "idJurisdicao": "14",
    "idRegional": "2",
    "nomeEscola": "PROFESSORA MARILIA TANURE PEREIRA",
    "numeroJurisdicao": "020",
    "regional": "CENTRO-SUL",
    "tipo": "M",
    "tipoJurisdicao": "INFANTIL"

}...],
"status": "ok"
}

8) Consulta 0 a 3 anos - Jurisdição EI CRECHE

URL
Parâmetros

filtro=jurisdicao

tipoJurisdicao=creche

logradouro=afonso+pena

numero=1212
Resposta 
{

    "escolas": [
        {
            "bairro": "Carlos Prates",
            "codLocal": "351",
            "distancia": "248.03801801006",
            "geometria": "POINT (609656.757871549 7797611.42372895)",
            "idBairro": "31",
            "idJurisdicao": "133",
            "idRegional": "5",
            "nomeEscola": "UMEI CARLOS PRATES",
            "nomeLogradouro": "PADRE EUSTAQUIO",
            "numeroCEP": "30710580",
            "numeroJurisdicao": "201",
            "regional": "NOROESTE",
            "tipo": "M",
            "tipoJurisdicao": "CRECHE",
            "tipoLogradouro": "RUA"
        },
        {
            "bairro": "Carlos Prates",
            "codLocal": "750",
            "distancia": "758.287391220992",
            "geometria": "POINT (608822.026590342 7798046.72757255)",
            "idBairro": "31",
            "idJurisdicao": "133",
            "idRegional": "5",
            "nomeEscola": "UMEI SABINÓPOLIS",
            "nomeLogradouro": "PADRE EUSTAQUIO",
            "numeroCEP": "30710580",
            "numeroJurisdicao": "201",
            "regional": "NOROESTE",
            "tipo": "M",
            "tipoJurisdicao": "CRECHE",
            "tipoLogradouro": "RUA"
        }
    ],
    "status": "ok"
}

9) Consulta por ensino adulto - Jurisdição EJA

URL
Parâmetros

filtro=jurisdicao

tipoJurisdicao=eja

logradouro=afonso+pena

numero=1212
Resposta 
{

    "escolas": [
        {
            "bairro": "Carlos Prates",
            "codLocal": "351",
            "distancia": "248.03801801006",
            "geometria": "POINT (609656.757871549 7797611.42372895)",
            "idBairro": "31",
            "idJurisdicao": "133",
            "idRegional": "5",
            "nomeEscola": "UMEI CARLOS PRATES",
            "nomeLogradouro": "PADRE EUSTAQUIO",
            "numeroCEP": "30710580",
            "numeroJurisdicao": "201",
            "regional": "NOROESTE",
            "tipo": "M",
            "tipoJurisdicao": "CRECHE",
            "tipoLogradouro": "RUA"
        },
        {
            "bairro": "Carlos Prates",
            "codLocal": "750",
            "distancia": "758.287391220992",
            "geometria": "POINT (608822.026590342 7798046.72757255)",
            "idBairro": "31",
            "idJurisdicao": "133",
            "idRegional": "5",
            "nomeEscola": "UMEI SABINÓPOLIS",
            "nomeLogradouro": "PADRE EUSTAQUIO",
            "numeroCEP": "30710580",
            "numeroJurisdicao": "201",
            "regional": "NOROESTE",
            "tipo": "M",
            "tipoJurisdicao": "CRECHE",
            "tipoLogradouro": "RUA"
        }
    ],
    "status": "ok"
}

Respostas e códigos de erro

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.

Alterações na versão 1.6.1

Alterações na versão 1.6.0

Alterações na versão 1.5.1

Alterações na versão 1.5