Adicione preenchimento automático por código postal a um formulário de entrega

Um formulário de entrega com campos separados para código postal, cidade e estado pede ao cliente que digite informações que um único código postal muitas vezes já indica.

Consultando o código

Assim que o cliente terminar de digitar um código postal e selecionar um país, ou se o país já for conhecido pela conta dele, envie ambos para /v1/postcode.

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", "country": "GB"}}
  ]
}

Preenchendo os campos do formulário

Preencha os campos de cidade e estado diretamente a partir do objeto components do resultado e deixe o cliente confirmá-los ou corrigi-los, em vez de bloquear os campos por completo, já que um código postal às vezes cruza uma divisa ou abrange mais de um nome de lugar de uso comum.

Um segundo exemplo: preenchendo previamente a região de cobrança para fins fiscais

A mesma consulta serve para um formulário de cadastro ou de cobrança que precisa da região do cliente para cálculo de impostos, e não apenas para um formulário de entrega. Disparar a mesma consulta de código postal assim que um código postal de cobrança é inserido preenche o campo de região de forma consistente nos dois contextos, usando a mesma requisição e a mesma estrutura de resposta, de modo que o mesmo código de tratamento no cliente e no servidor pode atender aos dois formulários.

Disparando a consulta no momento certo

Execute a consulta quando o campo de código postal perder o foco, ou quando atingir o comprimento esperado para o país selecionado, e não a cada tecla pressionada, já que só faz sentido consultar um código postal depois que ele está completo. Isso mantém o recurso em uma requisição por preenchimento completo do campo, e não uma por caractere digitado.

Um erro comum a evitar

Não fixe no código um comprimento esperado único para o formato de código postal de todos os países. Uma suposição de cinco dígitos que funciona para um país vai disparar a consulta cedo demais, ou nunca, para um país que usa outro comprimento ou um formato alfanumérico como o do exemplo acima. Dispare na perda de foco independentemente do comprimento ou mantenha uma pequena tabela de comprimentos por país se quiser disparar antes para os países que você atende com mais frequência.

Lidando com um código não reconhecido

Um array results vazio significa que o código não foi reconhecido para aquele país, na maioria das vezes por causa de um erro de digitação. Deixe os campos de cidade e estado em branco e permita que o cliente os preencha manualmente, em vez de bloquear o envio do formulário, já que rejeitar o campo por uma falha no preenchimento automático é uma experiência pior do que simplesmente pedir o preenchimento manual nesse caso específico.

Um caso extremo: um código que abrange mais de um nome de lugar

Alguns códigos postais abrangem legitimamente uma área conhecida localmente por mais de um nome, ou ficam exatamente na divisa entre dois nomes de cidade de uso comum. Quando isso acontece, mostrar o valor retornado como uma sugestão editável, e não como um rótulo fixo, permite que o cliente o corrija para o nome que ele realmente usa, sem tratar nenhum dos dois como mais ou menos oficial que o outro.

Obtendo coordenadas exatas quando o endereço estiver completo

O preenchimento automático a partir de um código postal fornece uma localização em nível de área, o que basta para os campos de cidade e estado, mas quando o cliente digita também o endereço completo, passar esse endereço inteiro por /v1/forward fornece as coordenadas precisas de que uma etiqueta de envio ou um sistema de roteirização de entregas realmente precisa.

Quanto custa

Cada campo de código postal preenchido dispara uma requisição. Um formulário de entrega que processa muitos pedidos por dia ainda usa este recurso em ritmo moderado, uma consulta por pedido e não por tecla, o que o mantém bem dentro das 2.500 requisições gratuitas por dia incluídas em cada chave para a maioria das lojas.

Preencher automaticamente cidade e estado a partir de um código postal reduz um formulário de entrega em dois campos para a grande maioria dos clientes que digitam um código válido. As definições completas dos campos estão na documentação da consulta de código postal.