Autocompletar Lugares

Busque países, estados e cidades enquanto o usuário digita

O endpoint /v1/places/autocomplete é o motor do campo de endereço de um checkout, de um formulário de cadastro ou de uma calculadora de frete. Você envia o que o usuário digitou até agora e recebe sugestões ordenadas por relevância, cada uma já com sua hierarquia completa para que você possa exibir Madri, Comunidade de Madri, Espanha sem uma segunda chamada.

Cobre os níveis país, estado e cidade. Não cobre endereços em nível de rua nem pontos de interesse como estabelecimentos, horários de funcionamento ou avaliações.

Endpoint

GET https://api.countrydataapi.com/v1/places/autocomplete

Parâmetros de Consulta

Como funciona a correspondência

A consulta é normalizada antes da busca, para que o usuário não precise brigar com o teclado:

• Insensível a maiúsculas e acentos — avila encontra Ávila, munchen encontra München.
• Insensível à pontuação — hospitalet encontra L'Hospitalet de Llobregat.
• Qualquer palavra corresponde — york encontra New York, não apenas os nomes que começam com York.

Os resultados são ordenados pela qualidade da correspondência (nome exato, depois início do nome, depois início de uma palavra interna), em seguida do nível administrativo mais amplo ao mais específico e, por último, pelo tamanho do nome. O campo match de cada sugestão indica qual regra foi aplicada, o que é útil para destacar o texto.

Exemplo de Requisição

curl "https://api.countrydataapi.com/v1/places/autocomplete?apikey=sua-chave-api&q=mad&country=ES&limit=5&lang=pt"

JavaScript

const API_KEY = 'sua-chave-api';

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

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

Python

import requests

response = requests.get(
    'https://api.countrydataapi.com/v1/places/autocomplete',
    params={
        'apikey': 'sua-chave-api',
        'q': 'mad',
        'country': 'ES',
        'limit': 5,
        'lang': 'pt',
    },
)
data = response.json()

SDK de TypeScript

import { CountryDataApi, Places } from '@countrydataapi/sdk';

const api = new CountryDataApi({ apiKey: 'sua-chave-api' });
const session = Places.createSession();

const { suggestions } = await api.places.autocomplete({
  q: 'mad',
  country: 'ES',
  lang: 'pt',
  sessiontoken: session,
});

Formato da Resposta

{
  "success": true,
  "query": "mad",
  "suggestions": [
    {
      "id": "66c7a6c9e4bda21f4ab1a0f1",
      "type": "city",
      "name": "Madri",
      "description": "Madri, Comunidade de Madri, Espanha",
      "match": "prefix",
      "components": {
        "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madri" },
        "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Comunidade de Madri" },
        "country": {
          "id": "66c7a6c9e4bda21f4ab10ef2",
          "name": "Espanha",
          "iso2": "ES",
          "iso3": "ESP",
          "phone_code": "+34",
          "flag": "🇪🇸"
        }
      }
    }
  ],
  "count": 1,
  "session": { "token": "6f9e...", "billed": true, "ttl_seconds": 180 },
  "tokens_used": 1,
  "remaining_tokens": 4871
}

Campos da Resposta

Consumo de Tokens: paga-se por sessão, não por tecla

Um autocompletar dispara uma requisição a cada tecla. Cobrar por requisição faria com que um único campo de endereço custasse 8-10 tokens e transformaria sua fatura em uma função da velocidade de digitação dos seus usuários.

Envie um sessiontoken — qualquer UUID, gerado quando o campo recebe o foco — e a sessão inteira custa 1 token, não importa quantas requisições foram necessárias:

1. Gere um token quando o campo de endereço receber o foco.
2. Envie-o em todas as chamadas a /autocomplete. Apenas a primeira é cobrada.
3. Envie-o na chamada a /details da sugestão escolhida pelo usuário. Essa chamada é gratuita e encerra a sessão.
4. Gere um novo token para o próximo campo de endereço.

As sessões expiram após 3 minutos. Sem sessiontoken, cada requisição custa 1 token.

// Uma sessão por campo de endereço
let session = crypto.randomUUID();

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

// ...cada tecla reutiliza `session`, então o campo inteiro custa 1 token

Resposta de Erro

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter \"q\" is required and must be at least 2 characters long.",
    "status": 400
  },
  "message": "Parameter \"q\" is required and must be at least 2 characters long."
}

Diferente dos endpoints mais antigos, /v1/places/* retorna um código HTTP real (400, 401, 402, 404) junto de um error.code estável. Consulte a documentação de códigos de erro.

Chamadas a partir do navegador

/v1/* envia Access-Control-Allow-Origin: *, então você pode chamar o autocompletar diretamente do seu frontend sem um proxy. Tenha em mente que a chave da API fica então visível para qualquer pessoa que abra as ferramentas de desenvolvedor: use uma chave com um orçamento que você se sinta confortável em expor, ou faça a chamada através do seu próprio backend se isso for importante para você.

Dicas práticas

1. Use debounce de cerca de 150 ms. Menos requisições, mesma sensação.
2. Exija 2-3 caracteres antes de disparar a busca. Consultas mais curtas não são úteis.
3. Passe country quando você já souber qual é. Menos sugestões e melhores.
4. Passe types=city se o campo for especificamente de cidade.
5. Não faça cache por usuário — mas você é livre para armazenar e cachear os dados retornados pelo tempo que quiser. Não há nenhuma restrição quanto à sua retenção.

Endpoints Relacionados

• GET /v1/places/details - Ficha completa de uma sugestão
• GET /v1/places/validate - Validar um endereço completo
• GET /v1/places/postal-format - Formato de código postal por país

Guia de Integração Completo

• Autocompletar endereços, do início ao fim