Documentação

Autocompletar Endereços

De um input vazio a um endereço validado e salvo

Este guia constrói a etapa de endereço de um checkout: o usuário digita, escolhe uma cidade, e os campos de país, província e código postal se preenchem sozinhos e são validados. Cerca de 60 linhas de JavaScript.

Três endpoints fazem o trabalho:

  1. /v1/places/autocomplete — sugestões enquanto se digita
  2. /v1/places/details — a ficha completa do que foi escolhido
  3. /v1/places/validate — verificação final antes de salvar

Primeiro, o token de sessão

Um autocompletar envia uma requisição por tecla. Para manter o custo previsível, gere um sessiontoken quando o campo receber o foco e reutilize-o em todas as requisições desse campo, incluindo a chamada final a details. O campo inteiro custa 1 token, por mais que o usuário digite.

let session = crypto.randomUUID();

input.addEventListener('focus', () => {
  session = crypto.randomUUID(); // uma sessão para cada endereço que o usuário informar
});

As sessões duram 3 minutos. Se você omitir o token, cada requisição custa 1 token.

JavaScript puro

<input id="city" placeholder="Comece a digitar sua cidade..." autocomplete="off" />
<ul id="suggestions"></ul>

<input id="country" readonly />
<input id="state" readonly />
<input id="zip" placeholder="Código postal" />
<p id="zip-error"></p>

const API_KEY = 'sua-chave-api';
const BASE = 'https://api.countrydataapi.com/v1/places';

const input = document.getElementById('city');
const list = document.getElementById('suggestions');

let session = crypto.randomUUID();
let timer;
let postal = null;

input.addEventListener('focus', () => { session = crypto.randomUUID(); });

// Debounce: uma requisição por pausa, não por tecla.
input.addEventListener('input', () => {
  clearTimeout(timer);
  const q = input.value.trim();
  if (q.length < 2) { list.innerHTML = ''; return; }

  timer = setTimeout(() => search(q), 150);
});

async function search(q) {
  const params = new URLSearchParams({
    apikey: API_KEY,
    q,
    types: 'city',
    limit: '5',
    lang: 'pt',
    sessiontoken: session,
  });

  const response = await fetch(`${BASE}/autocomplete?${params}`);
  const { suggestions } = await response.json();

  list.innerHTML = '';
  suggestions.forEach((suggestion) => {
    const item = document.createElement('li');
    item.textContent = suggestion.description; // "Madri, Comunidade de Madri, Espanha"
    item.onclick = () => choose(suggestion);
    list.appendChild(item);
  });
}

async function choose(suggestion) {
  list.innerHTML = '';
  input.value = suggestion.name;

  const params = new URLSearchParams({
    apikey: API_KEY,
    id: suggestion.id,
    type: suggestion.type,
    lang: 'pt',
    sessiontoken: session, // encerra a sessão: esta chamada é gratuita
  });

  const response = await fetch(`${BASE}/details?${params}`);
  const { place } = await response.json();

  document.getElementById('country').value = place.components.country?.name ?? '';
  document.getElementById('state').value = place.components.state?.name ?? '';

  // As regras de código postal do país, para validar o próximo campo no navegador.
  postal = place.postal;
  document.getElementById('zip').placeholder = postal.example ?? 'Código postal';
}

document.getElementById('zip').addEventListener('blur', (event) => {
  const error = document.getElementById('zip-error');
  if (!postal?.regex) { error.textContent = ''; return; }

  const ok = new RegExp(postal.regex).test(event.target.value.trim());
  error.textContent = ok ? '' : `Formato esperado: ${postal.example ?? postal.format}`;
});

Essa é toda a interação. O campo description já vem formatado para um dropdown, então não há strings a montar.

React

import { useEffect, useRef, useState } from 'react';

const API_KEY = 'sua-chave-api';
const BASE = 'https://api.countrydataapi.com/v1/places';

export function useAddressAutocomplete() {
  const [query, setQuery] = useState('');
  const [suggestions, setSuggestions] = useState([]);
  const [address, setAddress] = useState(null);
  const session = useRef(crypto.randomUUID());

  useEffect(() => {
    if (query.trim().length < 2) {
      setSuggestions([]);
      return;
    }

    // Aborta as requisições em andamento para que uma resposta lenta não sobrescreva uma mais recente.
    const controller = new AbortController();
    const timer = setTimeout(async () => {
      const params = new URLSearchParams({
        apikey: API_KEY,
        q: query.trim(),
        types: 'city',
        limit: '5',
        lang: 'pt',
        sessiontoken: session.current,
      });

      try {
        const response = await fetch(`${BASE}/autocomplete?${params}`, {
          signal: controller.signal,
        });
        const data = await response.json();
        setSuggestions(data.suggestions ?? []);
      } catch (error) {
        if (error.name !== 'AbortError') throw error;
      }
    }, 150);

    return () => {
      clearTimeout(timer);
      controller.abort();
    };
  }, [query]);

  async function select(suggestion) {
    const params = new URLSearchParams({
      apikey: API_KEY,
      id: suggestion.id,
      type: suggestion.type,
      lang: 'pt',
      sessiontoken: session.current,
    });

    const response = await fetch(`${BASE}/details?${params}`);
    const { place } = await response.json();

    setAddress(place);
    setSuggestions([]);
    setQuery(place.name);
    session.current = crypto.randomUUID(); // próximo endereço, próxima sessão
  }

  return { query, setQuery, suggestions, address, select };
}

function AddressField() {
  const { query, setQuery, suggestions, address, select } = useAddressAutocomplete();

  return (
    <div>
      <input
        value={query}
        onChange={(event) => setQuery(event.target.value)}
        placeholder="Comece a digitar sua cidade..."
        autoComplete="off"
      />

      {suggestions.length > 0 && (
        <ul>
          {suggestions.map((suggestion) => (
            <li key={suggestion.id} onClick={() => select(suggestion)}>
              {suggestion.description}
            </li>
          ))}
        </ul>
      )}

      {address && (
        <>
          <input readOnly value={address.components.country?.name ?? ''} />
          <input readOnly value={address.components.state?.name ?? ''} />
          <input placeholder={address.postal.example ?? 'Código postal'} />
        </>
      )}
    </div>
  );
}

Validação final no servidor

A validação no navegador é para a comodidade do usuário. Antes de salvar ou enviar qualquer coisa, confirme a combinação completa no servidor:

const params = new URLSearchParams({
  apikey: process.env.COUNTRY_DATA_API_KEY,
  country: form.country,
  state: form.state,
  city: form.city,
  zipcode: form.zip,
  lang: 'pt',
});

const response = await fetch(
  `https://api.countrydataapi.com/v1/places/validate?${params}`
);
const { result } = await response.json();

if (!result.valid && result.has_corrections) {
  // Ofereça a correção em vez de rejeitar o formulário de imediato.
  return { needsConfirmation: result.corrections };
}

// Salve a forma canônica, não o que o usuário digitou.
await orders.save({
  country: result.normalized.country?.name,
  state: result.normalized.state?.name,
  city: result.normalized.city?.name,
  zipcode: result.normalized.zipcode,
});

Salvar result.normalized em vez da entrada bruta é o que torna seus dados de endereço consultáveis depois: sem um Cataluna ao lado de um Cataluña, sem um MADRID ao lado de um Madrid.

Pedir menos

Se o seu formulário só tem código postal e cidade, você não precisa do campo de província: o código postal o resolve.

const { result } = await api.places.validate({ country: 'ES', zipcode: '28001' });
result.normalized.state?.name; // "Comunidade de Madri"

Um campo a menos melhora a conversão de um checkout de forma mensurável.

Quanto isso custa

Ação Tokens
Um campo de endereço completo (quantas teclas forem + details) 1
Validação no servidor do formulário enviado 1
Formatos postais de todos os países (faça cache) 1, uma vez

Ou seja, um endereço de checkout concluído custa 2 tokens, e não importa a velocidade com que o usuário digita.

O que isto não faz

O conjunto de dados é administrativo: países, estados, cidades e códigos postais. Não há dados em nível de rua, nem coordenadas abaixo do nível de país, nem pontos de interesse — nem estabelecimentos, nem horários, nem avaliações, nem fotos. Se você precisa geocodificar um endereço completo com rua ou buscar um restaurante, esta não é a ferramenta certa.

Relacionado