Como Migrar do Geocoder para o Endereço BH¶

Visão Geral¶

O Geocoder foi o primeiro serviço de geocodificação da Prefeitura Municipal de Belo Horizonte. Os dados disponibilizados por ele, são provenientes da base cadastral mantida pela Gerência de Manutenção do Cadastro Territorial Multifinalitário - GCGS-PB. Neste serviço a chave de identificação dos endereços id correspondia à chave da tabela de cadastro de endereços, conhecida como id_ctm. E por este motivo estava sujeito a deixar de existir, em função das manutenções diárias de endereçamento da cidade.

O Endereço BH, utiliza uma outra abordagem para identificação dos endereços. Nele o id não corresponde ao id_ctm. O id do Endereço BH é constante ou imutável. Mesmo que o endereço tenha seu estado modificado, ou o mesmo seja deletado*, esta chave continuará existindo e assim os sistemas que a utilizarem poderão continuar resgatando o endereço e ter a informação mais recente sobre o mesmo, sem o risco de gerar alguma quebra nos dados.

Ao contrário do Geocoder o Endereço BH é autenticado e deve ser integrado mediante o protocolo OpenID. Os detalhes desse processo serão encontrados ao longo deste documento.

Também neste documento será detalhado os casos de usos similares e funcionalidades que não foram contempladas no novo serviço.

* nenhum endereço sofre deleção física da base de dados

Passo a passo¶

1. Criação de usuário e permissões para acesso ao Endereço BH
2. Validação dos casos de usos disponíveis no Endereço BH
3. Alteração na implementação existente

Passo 1¶

Criação de usuário e permissões para acesso ao Endereço BH¶

Para acessar os serviços do Endereço BH é necessário um usuário, do tipo sistema, cadastrado no AcessoPBH.

Caso o sistema ainda não possua usuário, é necessário solicitar para área responsável. Mais informações neste link ou mais informações no manual disponível em autorizacaodesistemas.pbh.gov.br

Solicitar concessão de permissão para que o usuário possa acessar os serviços do Endereço BH Mais informações

Passo 2¶

Validação dos casos de usos disponíveis no Endereço BH¶

Endpoints¶

É necessário idenfificar todos os casos de usos atualmente utilizados no Geocoder e verificar se casos de usos disponíveis no Endereço BH atendem aos requisitos existentes. Para facilitar a migração tabela abaixo contém as possíveis equivalências entre os serviços do Geocoder e Endereço BH

Possíveis equivalências entre endpoints dos serviços¶

Possíveis equivalência entre os parâmetros utilizados nos dois serviços¶

Exemplos de possíveis equivalências¶

Nota 1¶

Equivalência entre os casos de usos¶

O Geocoder utiliza filtros para realizar a busca por endereços. O usuário informa individualmente cada campo que compõe o endereço, cabendo o Geocoder restringir o resultado da consulta somente aos endereços que possuem todos os campos informados pelo usuário.

Já o Endereço BH realiza pesquisa pela presença dos termos informados pelo usuário nos campos do endereço. O usuário deverá informar todos os termos a serem pesquisados em um único campo e Endereço BH pesquisará pela presença dos termos em todos os campos dos endereços.

Portanto, mesmo informando termos pertencentes a um determinado campo do endereço, caso estes termos estejam presentes em outros campos, estes serão incluídos no resultado.

Nota 2¶

Mudança no identificador da entidade Endereço¶

O campos id presente no Geocoder e no Endereço BH são DIFERENTES e não possuem equivalência. Para manter a compatibilidade o campo id da entidade Endereço do Geocoder está disponível no atributo id_endereco_pbh no Endereço BH, mais informações abaixo

Recomendamos que seja realizada a migração também dos identificadores, para utilizar o campo id do Endereço BH, realizando as modificações necessárias na base de dados.

Nota 3¶

Verificar a questao do Filtrado=true e dos logradouros afetados no geocoder para definir se será tratado no Endereço BH

Passo 3¶

Alteração na implementação existente¶

O serviços disponíveis no Endereço BH possuem URL, parâmetros e formatos de retorno diferentes dos serviços disponíveis no Geocoder, em alguns casos, não possuindo uma equivalência direta.

Poderá ser observado um comportamento diferente quanto aos resultados obtidos entre os serviços nos dois sistemas, principalmente diferenças quanto a presença de mais endereços ou com ordenação diferente dos resultados obtidos entre os dois sistemas.

Mudança de URL¶

URL base dos serviços:

• Geocoder http[s]://geocoder.pbh.gov.br/geocoder/
• Endereço BH: https://enderecobh.pbh.gov.br/api/

URL Ambiente de homologação: https://enderecobh-hm.pbh.gov.br

A nova URL está disponível somente o protoloco HTTPS

Requisição¶

Autorização e Autenticação¶

O Endereço BH implementam o protocolo OAuth2/OpenConnectID para controlar o acesso aos serviços. Para utilizar os serviços do Endereço BH é necesário encaminhar no cabeçalho de cada requisição o Acess Token obtido através do AcessoPBH/GAS-PBH

Exemplo de requisição ao Endereço BH

GET /enderecos?q=avenida afonso pena 1212
Authorization: Bearer CONTEUDO_ACESS_TOKEN

Mais informações na documentação do Endereço BH. Acesso ao link

Formato de saída¶

Endereço¶

No Geoceoder os campos dos endereços estão disponíveis nas propriedades dos objetos endereco[].

Exemplo saída JSON Geocoder - Pesquisa Endereço¶

{
  "endereco": [
    {
      "bairropopular": "Centro",
      "cep": "30130001",
      "codregional": "19",
      "idbairro": "37",
      "id": "13615",
      "idlogradouro": "1259",
      "idregional": "2",
      "idterritorio": "29",
      "siglaterritorio": "CS1",
      "letra": "",
      "nomelogradouro": "AFONSO PENA",
      "nomeregional": "CENTRO-SUL",
      "numero": "254",
      "tipologradouro": "AVENIDA",
      "wkt": "POINT(610853.139726381 7797449.20281154)",
      "idterritorioFiscalizacao": "27",
      "numBairroPopular": "642"
    }
  ],
  "status": "ok"
}

Exemplo saída GeoJSON Endereço BH - Pesquisa Endereço¶

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": 713858,
        "id_endereco_pbh": 157801,
        "id_tipo_logradouro": 18,
        "tipo_logradouro": "RUA",
        "sigla_tipo_logradouro": "RUA",
        "id_logradouro": 3125,
        "nome_logradouro": "AMAROS",
        "numero": 172,
        "letra": "A",
        "id_bairro_popular": 167,
        "bairro_popular": "São Paulo",
        "id_bairro_oficial": 71,
        "bairro_oficial": "São Paulo",
        "id_regional": 4,
        "cod_regional": 21,
        "nome_regional": "NORDESTE",
        "cep": "31910180",
        "id_territorio": 4,
        "id_territorio_fiscalizacao": 7,
        "sigla_territorio": "NE3",
        "ind_ativo": "ativo",
        "status_ctm": "E",
        "wkt": {
          "epsg_4326": "POINT (-43.9223085833891 -19.8685332830945)",
          "epsg_31983": "POINT (612830.601300225 7802706.02354846)"
        }
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-43.9224199449533, -19.8685907791933]
      }
    }
  ],
  "sort": {
    "sorted": false,
    "unsorted": true,
    "empty": true
  },
  "offset": 0,
  "pageNumber": 0,
  "pageSize": 50,
  "paged": true,
  "unpaged": false
}

Propriedades do Endereço¶

No Endereço BH o resultado utiliza o formato GeoJSON de retorno dos resultados, cada registro é retornado camo um objeto dentro do campo {features[]}, os campos de cada registro estão disponíveis no objeto {features[].properties}.

Equivalências entre os campos¶

Endereço¶

Logradouro¶

Bairro (Bairro Popular)¶

Logradouro¶

Tipo Logradouro¶

Campo Geometria¶

No Geocoder a geometria de cada endereço está presente no {endereco[].wkt}. O formato de coodernada utilizado é o Sirgas 2000 23S (EPSG 31983).

Exemplo :

 {
  "endereco": [
    {
      ...
      "wkt": "POINT(610853.139726381 7797449.20281154)",
    }
  ]
}

No resultado do Endereço BH cada endereço será retornado como Feature do GeoJSON com um campo {features[].geometry}, utilizando o sistema de coodernadas WGS84 (EPSG 4326).

Também será informado o tipo {features[].geometry.type} de geometria e, que no caso dos endereços, será o tipo "Point".

Exemplo :

{
  ...
  "features": [
    {
      ...
      "geometry": {
        "type": "Point",
        "coordinates": [-43.9224199449533, -19.8685907791933]
      }
    }
  ],
  ...
}

Será retornado também as geometrias no formato WKT (campo {features[].properties.wkt}) nos sistemas de coordenadas:

• WGS84 (EPSG 4326) no campo {features[].properties.wkt.epsg_4326}
• Sirgas 2000 23S (EPSG 31983) no campo {features[].properties.wkt.epsg_31983} Este último campo é o equivalente ao disponibilizado no Geocoder.

Exemplo :

{
  ...
  "features": [
    {
      ...
      "properties": {
        ...
        "wkt": {
          "epsg_4326": "POINT (-43.9224199449533 -19.8685907791933)",
          "epsg_31983": "POINT(612818.900382729 7802699.73479656)"
        },
      },
    ...
    }
  ],
  ...
}

Passos permissão¶

Passos para solicitar concessão de permissão¶

1. Definir quais serviços do Endereço BH serão utilizados.
2. Identificar as permissões necessárias para acessos aos serviços.
3. Solicitar via SDM a concessão das permissões para o usuário do sistema, informando o usuário e os tipos de permissões.

Área da solicitação SDM:

Servicos de Tecnologia e Informacao.Geoprocessamento.BHMap.Conteudo

Caso Uso básico do Geocoder¶

1. Usuário inicia a pesquisa por um determinado endereço em uma Aplicação.
2. Aplicação realiza a consulta ao Geocoder, utilizando o serviço REST.
3. Geocoder retorna o resultado em formato JSON para Aplicação.
4. Aplicação exibe para o Usuário o endereço localizado.

Caso Uso básico do Endereço BH¶

1. Diagramas com fluxo Pesquisa de Endereço no Geocoder e no Endereço BH

1. Usuário inicia a pesquisa por um determinado endereço em uma Aplicação.
2. Aplicação reliza autenticação e solicitação do credencial (acess token) ao AcessoPBH
3. AcessoPBH retorna a credencial para o Aplicação.
4. Aplicação realiza a requisição ao Endereço BH passando no cabeçalho a a credencial obtida do _AcessoPBH.
5. Endereço BH retorna o resultado em formato GeoJSON para Aplicação.
6. Aplicação exibe para o Usuário o endereço localizado.