API – Serviço de endereços - Geolocalização (versão 1.3.1)

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).

Chamada ao serviço

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

Parâmetros obrigatórios:

logradouro ou cep – Dado textual que informa o logradouro ou cep a ser pesquisado.
numero – Dado numérico que informa o número do imóvel a ser pesquisado.

Parâmetros opcionais:

filtro – Dado textual que informa se a busca deve ser limitada por jurisdicao. Valores: 'jurisdicao'
classificacao – Dado que informa se a busca deve considerar o nome oficial ou popular do logradouro. Opcionalmente pode buscar todos, com possibilidade de perda da qualidade do resultado. Valores: 'oficial', 'popular', 'completo'. Caso não seja informado o parâmetro é feita a busca pelo nome oficial.
limite – Dado numérico para limitar o número de resultados. Caso não seja informado valor ou seja informado o valor 0 (zero), são retornados todos os resultados.
bairro – Dado textual que informa o nome do bairro a ser pesquisado.
distância – Distância máxima em metros entre escola e endereço informado. Limita a busca a um raio desejado a partir daquele endereço.

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"

2) Consulta por logradouro popular e número:

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 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"

4) 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"

5) 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"

5) Consulta por logradouro oficial e popular:

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"
}

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.