My Geocode

Guias

Confira um endereço com o seu código postal

· 4 min de leitura · My Geocode · #postal-code#forward-geocoding#validation#shipping

Um cliente pode digitar um endereço real e um código postal real que, na verdade, não combinam, na maioria das vezes por trocar a ordem de dígitos ou copiar um código postal antigo para um endereço novo. Nenhum dos campos sozinho revela o problema, já que os dois são válidos individualmente.

Resolvendo cada campo de forma independente

Geocodifique o endereço completo com /v1/forward para ver a qual código postal ele realmente corresponde e, separadamente, consulte o código postal que o cliente digitou com /v1/postcode para ver qual área ele cobre.

GET /v1/forward?q=10 Downing Street, London&limit=1
{
  "status": "ok",
  "results": [
    {"formatted": "10 Downing Street, London, UK", "lat": 51.5033, "lon": -0.1276, "type": "address", "precision": "house", "confidence": 0.96, "place_id": "op678", "components": {"postcode": "SW1A 2AA", "city": "London"}}
  ]
}
GET /v1/postcode?code=SW1A 1AA&country=GB
{
  "status": "ok",
  "postcode": "SW1A 1AA",
  "country_code": "GB",
  "results": [{"lat": 51.5014, "lon": -0.1419, "components": {"city": "London", "region": "Greater London"}}]
}

Comparando os dois resultados

Se o componente de código postal da consulta de endereço não corresponder ao código postal que o cliente digitou, como neste exemplo, essa é uma divergência que vale a pena sinalizar, mesmo que o endereço e o código postal tenham sido confirmados como reais de forma independente. Comparar os dois componentes diretamente é mais confiável do que comparar a distância entre os dois conjuntos de coordenadas, já que a área de um código postal pode ser pequena o bastante para que mesmo uma correspondência genuína não fique exatamente sobre as coordenadas do endereço.

Um segundo exemplo: uma divergência maior, que vale a pena pegar mais cedo

A mesma verificação também detecta um erro muito mais óbvio: um código postal digitado para um país ou região totalmente diferente do endereço em si, como um código no formato do Reino Unido junto com um endereço que, na verdade, fica em outro país. Comparar o componente de país do resultado do endereço com o parâmetro de país usado na consulta de código postal, antes mesmo de chegar à comparação mais detalhada dos códigos postais, é uma primeira verificação barata que filtra cedo esse tipo de erro maior.

O que fazer com uma divergência

Mostre ao cliente os dois valores lado a lado e peça que ele confirme qual está correto, em vez de escolher um deles silenciosamente ou rejeitar o pedido de imediato. Um dígito trocado é fácil de corrigir quando apontado, e um caso extremo genuíno, em que um código postal cobre legitimamente uma fronteira entre dois valores comumente usados, é raro o bastante para ser resolvido com uma rápida confirmação manual.

Um erro comum a evitar

Não compare os dois conjuntos de coordenadas diretamente com um limite de distância como substituto da comparação dos próprios componentes de código postal. A área de um código postal pode ser geograficamente pequena o bastante para que mesmo uma correspondência totalmente correta mostre alguma distância entre o ponto representativo do código postal e as coordenadas específicas do prédio do endereço, e um código de área pequena também pode ser geograficamente grande o bastante para que um par realmente divergente ainda fique dentro de um limite de distância tolerante. Comparar o texto do código postal em si é uma verificação mais direta e confiável do que tentar deduzir uma correspondência pela distância.

Um caso extremo que vale a pena prever

Uma área de código postal que fica exatamente na fronteira entre duas regiões administrativas pode, legitimamente, retornar um conjunto de componentes um pouco diferente dependendo de qual endpoint a resolveu, mesmo quando os dois estão corretos. Trate uma correspondência textual próxima, mas não exata, como uma diferença apenas na forma de escrever o nome de uma região, com mais leveza do que um código postal completamente diferente.

Verificando muitos pedidos de uma vez

Para um lote de pedidos existentes, em vez de um único envio novo, os dois endpoints aceitam um array em um POST em lote, então um acúmulo de pedidos pode ser verificado enviando os endereços como uma requisição em lote para /v1/forward e os códigos postais como outra requisição em lote para /v1/postcode, e depois comparando os dois arrays de resultados por posição.

Custo das requisições

Essa verificação usa duas requisições por pedido, uma para o endereço e outra para o código postal, ambas contadas na sua cota diária da mesma forma que qualquer outra consulta. É um custo razoável para detectar um erro que, de outra forma, apareceria como uma entrega fracassada.

Detectar um código postal divergente antes que um pedido seja enviado vale a segunda requisição necessária para a verificação. Os detalhes dos dois endpoints estão na documentação da geocodificação direta e na documentação da consulta de código postal.

Mais em Guias