Documentazione API - Endpoint ed Esempi

Dettaglio del Luogo

Tutto quello che ti serve appena l'utente sceglie un suggerimento

L'endpoint /v1/places/details riceve l'id di un suggerimento del completamento automatico e restituisce la scheda completa: l'intera gerarchia, il formato del codice postale del paese e i dati di cui un modulo ha di solito bisogno subito dopo — prefisso telefonico, valuta, fusi orari.

Endpoint

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

Parametri di Query

Parametro Tipo Obbligatorio Descrizione
apikey string Sì La tua chiave di autenticazione API
id string Sì L'id restituito da /v1/places/autocomplete
type string Sì country, state o city — il type del suggerimento
lang string No Lingua dei nomi restituiti. Predefinito: en
sessiontoken string No Il token di sessione usato durante il completamento automatico. Rende questa chiamata gratuita

Esempio di Richiesta

curl "https://api.countrydataapi.com/v1/places/details?apikey=la-tua-chiave-api&id=66c7a6c9e4bda21f4ab1a0f1&type=city&lang=it"

JavaScript

async function getDetails(suggestion, sessionToken) {
  const params = new URLSearchParams({
    apikey: 'la-tua-chiave-api',
    id: suggestion.id,
    type: suggestion.type,
    lang: 'it',
    sessiontoken: sessionToken,
  });

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

SDK 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 della Risposta

{
  "success": true,
  "place": {
    "id": "66c7a6c9e4bda21f4ab1a0f1",
    "type": "city",
    "name": "Madrid",
    "description": "Madrid, Comunità di Madrid, Spagna",
    "components": {
      "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madrid" },
      "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Comunità di Madrid" },
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "Spagna",
        "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": ["Spagnolo"],
      "timezones": ["UTC+01:00"],
      "continent": "EU",
      "region": "Europe"
    }
  },
  "tokens_used": 0,
  "remaining_tokens": 4871
}

Campi della Risposta

Campo Tipo Descrizione
place.components object Gerarchia completa: city, state, country
place.postal.format string Modello: # è una cifra, @ è una lettera
place.postal.regex string Espressione regolare ufficiale del codice postale del paese
place.postal.example string Valore di esempio ricavato da format e verificato contro regex
place.location object Coordinate — vedi la nota qui sotto
place.country_info object Valute, lingue, fusi orari, continente e regione

A proposito di location

location è valorizzato solo per type=country, dove contiene il centroide del paese e "precision": "country".

Per regioni e città vale null. Il set di dati è amministrativo e non ha coordinate per singola città, e restituire il centroide del paese spacciandolo per la città sarebbe peggio che non restituire nulla. Se ti servono coordinate a livello di città o geocodifica, questo endpoint non è lo strumento giusto.

Consumo di Token

  • 0 token quando sessiontoken corrisponde a una sessione di completamento automatico aperta. La sessione è già stata addebitata al primo tasto, e questa chiamata la chiude.
  • 1 token negli altri casi.

Vuol dire che un campo indirizzo completo — tutti i tasti che servono più la consultazione finale del dettaglio — costa un solo token.

Risposta di Errore

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

Endpoint Correlati