Criar recursos de validação de local usando a Plataforma Google Maps

Objetivo

Muitas vezes, é necessário validar a localização de um lugar. Há alguns serviços diferentes na Plataforma Google Maps que podem ajudar você com esse caso de uso. Este documento ajuda a escolher entre os dois principais serviços de validação de localização: a API Address Validation e a API Geocoding.

A API Address Validation é uma oferta da Plataforma Google Maps que ajuda os clientes a validar se um endereço está correto ou não.

A geocodificação com a API Geocoding é o processo de conversão de endereços em coordenadas geográficas, que podem ser usadas para colocar marcadores em um mapa ou uma posição no mapa.

Uma visão geral das diferenças entre a API Address Validation e a API Geocoding pode ser encontrada aqui.

Teste agora: acesse o console do Google Cloud e ative a API Address Validation e a API Places.

Quando escolher a API Address Validation em vez da API Geocoding

Observações sobre o fluxograma acima:

• O caso de uso de interação do usuário se refere a quando um usuário está presente para interagir com os resultados.
• O Place Autocomplete é uma API JavaScript, adequada para integração com interfaces do usuário.
• Você pode estar ciente de problemas de qualidade de dados nos seus endereços atuais. Portanto, embora você só queira geocódigos, é recomendável executar esses locais pela API Address Validation para corrigir os conjuntos de dados.

Há muitas situações em que você pode escolher, com base na árvore de decisão acima, usar um produto em vez do outro. No entanto, outras situações podem envolver o uso dos dois produtos para atender às suas metas.

Você pode usar a API Address Validation em vez da API Geocoding quando:

• Há uma grande chance de dados questionáveis ou quando um endereço incorreto tem um impacto negativo. Isso ocorre porque a API Address Validation fornece mais feedback sobre por que uma entrada não recebeu um resultado de alta precisão.
• Você precisa corrigir as entradas do usuário (por exemplo, erros de ortografia ou campos ausentes), o que aumenta a probabilidade de um resultado preciso na saída.
• Sua região de destino retorna mais metadados da API Address Validation em comparação com a API Geocoding, como a classificação do tipo de prédio como residencial ou comercial.

Você pode usar a geocodificação em vez da API Address Validation quando:

• Seu objetivo principal é recuperar a localização de um endereço, e a precisão de endereços individuais pode não ser essencial.
  • Por exemplo, você pode gerar um mapa de calor de um grande conjunto de dados.
• Você precisa de detalhes de destino hiperlocais, como entradas de edifícios, contornos de edifícios ou pontos de navegação de embarque e desembarque (disponíveis com o SearchDestinations na API Geocoding v4).
• Você precisa de uma solução global e a API Address Validation não está disponível em todas as regiões de destino.

A seguir, alguns exemplos que demonstram os recursos da API Address Validation em comparação com a API Geocoding.

Exemplo de endereço inválido

Avenida Exemplo, 1 – Mountain View, CA 94043, EUA

A API Address Validation divide essa entrada em componentes de endereço individuais (rua, cidade, estado etc.). Ela também pode fornecer feedback granular sobre por que o endereço não é válido até um nível PREMISE.

A Avenida Exemplo não existe em Mountain View, CA, e a API Address Validation reflete isso nos detalhes do componente retornado:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

A propriedade importante a ser inspecionada nesse caso é confirmationLevel. Ao retornar UNCONFIRMED_BUT_PLAUSIBLE para a Avenida Exemplo, a API determinou que seria possível que uma rua tivesse esse nome, mas não é possível fazer a correspondência com os dados de endereço de suporte.

Usando o resultado da API como feedback, é possível deduzir que o componente de rua dessa entrada (Avenida Exemplo) está com falha.

Usando o mesmo endereço com a API Geocoding, é possível fazer uma correspondência em "Califórnia", como você pode ver na captura de tela da ferramenta de geocodificação que pode ser testada aqui:

No entanto, o resultado é um geocódigo de todo o estado, com feedback mínimo sobre quais componentes da entrada estavam potencialmente com falha.

Exemplo de erro de ortografia

Avenida Exemplo, 76, Londn, SW1W 9TQ, GB

O endereço acima contém alguns erros de ortografia, um no nome da rua e outro na localidade.

As APIs Address Validation e Geocoding podem corrigir esses erros e alcançar o resultado da Avenida Exemplo, 76, Londres, SW1W 9TQ. No entanto, a API Address Validation pode fornecer mais informações sobre o processo.

Confira um dos componentes de endereço que foi escrito incorretamente na entrada:

{
  "componentName": {
    "text": "Buckingham Palace Road",
    "languageCode": "en"
        },
        "componentType": "route",
        "confirmationLevel": "CONFIRMED",
        "spellCorrected": true
     }
}

A API Address Validation retorna uma flag para indicar que uma correção foi feita no campo. A lógica de negócios pode ser implementada nessa flag para verificar a correção com o provedor de dados, como um cliente em um checkout de e-commerce.

Exemplo de dados ausentes e erro de ortografia

Bollschestraße 86, 12587, DE

O endereço acima tem um erro de ortografia no nome da rua e não tem a cidade (localidade) de Berlim.

A API Address Validation pode corrigir esses dois erros e retorna um PREMISE geocódigo de nível e um endereço verificado no nível PREMISE:

Bölschestraße 86, 12587 Berlin, DE

A API Geocoding não consegue superar os erros de entrada nesse caso e retorna um resultado de ZERO_RESULTS.

Exemplo de metadados de endereço adicionais

Avenida Exemplo, 111, Ste 123, Nova York, NY 10011-5201, EUA

Esse endereço está correto, exceto pelo número da unidade (Ste 123), que não existe no prédio.

A API Address Validation pode validar o endereço para o PREMISE (Avenida Exemplo, 111) e fornecer alguns metadados sobre a propriedade, incluindo que ela é comercial

instalações:

"business": true

Além disso, o valor dpvConfirmation retornado como parte do uspsData na resposta é S:

"dpvConfirmation": "S"

Um dpvConfirmation valor de S indica que o endereço é validado no nível PREMISE, mas o número da unidade fornecido na entrada não está associado a esse endereço.

A API Geocoding não pode fornecer essas informações.

Entender a resposta da API Geocoding

Visão geral

Se você usar a API Geocoding, o resultado do geocódigo vai conter várias pistas na resposta que podem ser usadas para entender detalhes do endereço fornecido.

A API Geocoding funciona resolvendo componentes de endereço em uma hierarquia.

Por **exemplo, 123 Example Street, Chicago, 60007, USA é resolvido na seguinte ordem:

/ Example Street/ Chicago/ 60007/ USA será avaliado nessa ordem. A primeira correspondência nesse caso é Chicago e, mais especificamente, o 60007 CEP. Portanto, ele retorna o seguinte Place_id para esse CEP:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

A API Geocode contém as seguintes informações na resposta:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

A API Geocoding pode confirmar a que tipo de lugar esse endereço pertence. Uma lista de endereço types retornados pela API Geocoding pode ser encontrada aqui.

Se nenhum dos componentes da entrada for resolvido, a API retornará:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

Fazer uma solicitação apenas com o endereço da rua sem um número de casa retorna um resultado no formato:

"types": [
  "route"
]

Isso significa que a API Geocoding não conseguiu encontrar ou corresponder a um número de rua.

Observação: para saber se um endereço existe, verifique se algum dos parâmetros (como types, partial_match, results, status) está definido na resposta da API Geocoding. Isso vai aumentar gradualmente o nível de confiança de que um endereço pode existir, mas não o tornará 100% preciso. É por isso que precisamos da API Address Validation.

Você pode usar as técnicas acima para aumentar a confiança na precisão do endereço de uma resposta da API Geocoding. No entanto, ao contrário de um resultado da API Address Validation, a API Geocoding não vai retornar feedback exato para determinar a precisão do resultado.

Tipo de local

Para entender esta seção corretamente, você precisa entender os diferentes tipos de locais que podem ser retornados de uma resposta da API Geocoding:

• ROOFTOP indica que o resultado retornado é um geocódigo preciso para o qual temos informações de localização precisas até a precisão do endereço da rua.
• RANGE_INTERPOLATED indica que o resultado retornado reflete uma aproximação (normalmente em uma estrada) interpolada entre dois pontos precisos (como interseções). Resultados interpolados geralmente são retornados quando códigos geográficos de rooftop não estão disponíveis para um endereço.
• GEOMETRIC_CENTER indica que o resultado retornado é o centro geométrico de um resultado, como uma polilinha (por exemplo, uma rua) ou um polígono (região).
• APPROXIMATE indica que o resultado retornado não é nenhum dos acima.

Se uma API Geocoding retornar um location_type de ROOFTOP ou RANGE_INTERPOLATED, isso não significa necessariamente que o endereço existe. Da mesma forma, se uma API Geocoding retornar com a partial_match flag definida como true, ainda poderá ser o resultado certo para você.

Esse tipo de correspondência falsa é um problema muito difícil de resolver com a API Geocoding. No mínimo, considere implementar alguma validação básica de pós-processamento no país e na localidade da solicitação / resposta. Melhor ainda, compare os endereços reais para erros de ortografia e/ou um endereço incompleto.

Observação: se você decidir usar a API Geocoding, é recomendável realizar verificações de qualidade de dados entre a solicitação inicial e a resposta da API Geocoding regularmente.

Correspondência parcial e correspondência falsa

Se um endereço for uma correspondência parcial, ou seja, a API Geocoding não conseguiu identificar o endereço exatamente, a resposta vai conter:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

Ainda mais importante do que os tipos de local acima é considerar quando partial_match = true é na resposta. partial_match indica que a API Geocoding não retornou uma correspondência exata para a solicitação original, mas conseguiu corresponder parte do endereço solicitado.

Convém verificar se a solicitação original inclui um endereço incompleto. Correspondências parciais ocorrem com mais frequência para endereços que não existem na localidade especificada na solicitação. Elas também podem ser retornadas quando uma solicitação corresponde a dois ou mais locais na mesma localidade.

Por exemplo, "21 Henr St, Bristol, UK" retorna uma correspondência parcial para Henry Street e Henrietta Street. Se uma solicitação incluir um componente de endereço com um erro ortográfico, a API Geocoding poderá sugerir um endereço alternativo. Sugestões acionadas dessa maneira não serão marcadas como correspondências parciais.

Endereços sintéticos

A API Geocoding pode retornar locais para endereços "sintéticos" que não existem como locais precisos no banco de dados do Google.

Nesses cenários, o objeto de resposta geralmente contém um ID de lugar longo e a seguinte propriedade: geometry.location_type=APPROXIMATE.

Se você encontrar esses indicadores na resposta, marque o endereço de entrada como inválido e tente validá-lo novamente por outro meio.

Observação: este é outro exemplo em que, com a API Address Validation, você recebe feedback direto se um endereço não existe.

Entender a resposta da API Address Validation

Já existe uma ótima documentação sobre como entender as respostas da API Address Validation, então não vamos entrar em mais detalhes aqui.

• A visão geral do objeto de resposta pode ser encontrada aqui.
• A demonstração que ilustra os diferentes componentes da resposta está aqui.
• No documento Validação de endereço para checkout, há uma descrição detalhada de como diferenciar endereços bons e ruins.

Práticas recomendadas

Como especificar a região geográfica

Ao fazer chamadas para as APIs Address Validation ou Geocoding, é recomendável limitar a região geográfica em que pesquisar o endereço. As duas APIs implementam isso de duas maneiras diferentes:

• API Geocoding: direcionamento de região

  Se você souber que os geocódigos estarão em um determinado país, vai receber resultados muito melhores usando o direcionamento de região. Por exemplo, se você estiver geocodificando no Canadá, recomendamos adicionar &region=ca às suas solicitações para direcionar para o Canadá. O direcionamento de região apenas prefere resultados nessa região. Você ainda pode receber resultados fora da região.

• API Address Validation: código da região

  De maneira semelhante, a API Address Validation produz resultados mais precisos se um ISO2 código for transmitido na solicitação, usando o regionCode campo.

Armazenar IDs de lugar

Se quiser armazenar informações da Plataforma Google Maps sobre o local para solicitações futuras, pode armazenar o ID de lugar indefinidamente na sua base de dados como um atributo do local. Você só precisa fazer uma solicitação do Find Place uma vez por placeID. Também é possível pesquisar o ID de lugar sempre que um usuário solicitar detalhes da transação.

Para ter as informações mais atualizadas sempre, atualize os IDs de lugar a cada 12 meses usando uma solicitação de Place Details com o parâmetro place_id.

Observação: consulte também o guia de práticas recomendadas para geocodificação.

Conclusão

Este documento descreve as principais diferenças entre as APIs Address Validation e Geocoding. Em resumo, considere usar a API Address Validation quando:

• Um endereço de correspondência preciso é necessário, especialmente para fins de capacidade de entrega.
• Os dados de entrada são conhecidos por serem de baixa qualidade. A API Address Validation é mais tolerante a erros de entrada, destaca componentes de endereço não verificáveis e faz correções nos dados de entrada.
• Mais informações são necessárias para um endereço, como residencial x comercial (disponível em regiões selecionadas).

Próximas etapas

Faça o download do white paper Melhorar o checkout, a entrega e as operações com endereços confiáveis e assista ao webinar Melhorar o checkout, a entrega e as operações com a validação de endereço .

Leituras sugeridas:

• Validação de endereço para checkout de e-commerce
• Documentação do Place Autocomplete
• Documentação da API Address Validation
• Geração de relatórios da Plataforma Google Maps

Colaboradores

O Google mantém este artigo. Os colaboradores a seguir escreveram o artigo originalmente.

Autores principais:

Henrik Valve | Engenheiro de soluções

Thomas Anglaret | Engenheiro de soluções

Sarthak Ganguly | Engenheiro de soluções