Documentação

Detalhes do Lugar

Tudo o que você precisa assim que o usuário escolhe uma sugestão

O endpoint /v1/places/details recebe o id de uma sugestão do autocompletar e retorna a ficha completa: toda a hierarquia, o formato de código postal do país e os dados que um formulário costuma precisar em seguida — código telefônico, moeda, fusos horários.

Endpoint

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

Parâmetros de Consulta

Parâmetro Tipo Obrigatório Descrição
apikey string Sim Sua chave de autenticação da API
id string Sim O id retornado por /v1/places/autocomplete
type string Sim country, state ou city — o type da sugestão
lang string Não Idioma dos nomes retornados. Padrão: en
sessiontoken string Não O token de sessão usado durante o autocompletar. Torna esta chamada gratuita

Exemplo de Requisição

curl "https://api.countrydataapi.com/v1/places/details?apikey=sua-chave-api&id=66c7a6c9e4bda21f4ab1a0f1&type=city&lang=pt"

JavaScript

async function getDetails(suggestion, sessionToken) {
  const params = new URLSearchParams({
    apikey: 'sua-chave-api',
    id: suggestion.id,
    type: suggestion.type,
    lang: 'pt',
    sessiontoken: sessionToken,
  });

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

SDK de TypeScript

const { place } = await api.places.details({
  id: suggestion.id,
  type: suggestion.type,
  sessiontoken: session,
});

place.components.country?.phone_code; // "+34"
place.postal.regex;                   // "^\\d{5}$"

Formato da Resposta

{
  "success": true,
  "place": {
    "id": "66c7a6c9e4bda21f4ab1a0f1",
    "type": "city",
    "name": "Madri",
    "description": "Madri, Comunidade de Madri, Espanha",
    "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": "🇪🇸"
      }
    },
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345"
    },
    "location": null,
    "country_info": {
      "currencies": [{ "code": "EUR", "name": "Euro", "symbol": "€" }],
      "languages": ["Espanhol"],
      "timezones": ["UTC+01:00"],
      "continent": "EU",
      "region": "Europe"
    }
  },
  "tokens_used": 0,
  "remaining_tokens": 4871
}

Campos da Resposta

Campo Tipo Descrição
place.components object Hierarquia completa: city, state, country
place.postal.format string Modelo: # é um dígito, @ é uma letra
place.postal.regex string Padrão oficial de código postal do país
place.postal.example string Valor de exemplo derivado de format e verificado contra regex
place.location object Coordenadas — veja a observação abaixo
place.country_info object Moedas, idiomas, fusos horários, continente e região

Sobre location

location só vem preenchido para type=country, onde traz o centroide do país e "precision": "country".

Para estados e cidades é null. O conjunto de dados é administrativo e não possui coordenadas por cidade, e retornar o centroide do país rotulado como se fosse a cidade seria pior do que não retornar nada. Se você precisa de coordenadas em nível de cidade ou de geocodificação, este endpoint não é a ferramenta certa.

Consumo de Tokens

  • 0 tokens quando sessiontoken corresponde a uma sessão de autocompletar aberta. A sessão já foi cobrada na primeira tecla, e esta chamada a encerra.
  • 1 token nos demais casos.

Isso significa que um campo de endereço completo — todas as teclas necessárias mais a consulta final dos detalhes — custa um único token.

Resposta de Erro

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No city found with id \"abc\".",
    "status": 404
  },
  "message": "No city found with id \"abc\"."
}

Endpoints Relacionados