Documentazione API - Endpoint ed Esempi

Cerca paesi, regioni e città mentre l'utente digita

L'endpoint /v1/places/autocomplete alimenta il campo indirizzo di un checkout, di un modulo di registrazione o di un calcolatore di spese di spedizione. Invii quello che l'utente ha digitato finora e ricevi suggerimenti ordinati per pertinenza, ognuno già con la sua gerarchia completa, così puoi mostrare Madrid, Comunità di Madrid, Spagna senza una seconda chiamata.

Copre i livelli paese, regione e città. Non copre gli indirizzi a livello di via né i punti di interesse come attività commerciali, orari di apertura o recensioni.

Endpoint

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

Parametri di Query

Come funziona la corrispondenza

La query viene normalizzata prima della ricerca, così l'utente non deve combattere con la tastiera:

• Insensibile a maiuscole e accenti — avila trova Ávila, munchen trova München.
• Insensibile alla punteggiatura — hospitalet trova L'Hospitalet de Llobregat.
• Qualsiasi parola corrisponde — york trova New York, non solo i nomi che iniziano con York.

I risultati sono ordinati per qualità della corrispondenza (nome esatto, poi inizio del nome, poi inizio di una parola interna), quindi dal livello amministrativo più ampio al più specifico e infine per lunghezza del nome. Il campo match di ogni suggerimento indica quale regola è scattata, utile per evidenziare il testo.

Esempio di Richiesta

curl "https://api.countrydataapi.com/v1/places/autocomplete?apikey=la-tua-chiave-api&q=mad&country=ES&limit=5&lang=it"

JavaScript

const API_KEY = 'la-tua-chiave-api';

async function search(query, sessionToken) {
  const params = new URLSearchParams({
    apikey: API_KEY,
    q: query,
    limit: '5',
    lang: 'it',
    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': 'la-tua-chiave-api',
        'q': 'mad',
        'country': 'ES',
        'limit': 5,
        'lang': 'it',
    },
)
data = response.json()

SDK TypeScript

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

const api = new CountryDataApi({ apiKey: 'la-tua-chiave-api' });
const session = Places.createSession();

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

Formato della Risposta

{
  "success": true,
  "query": "mad",
  "suggestions": [
    {
      "id": "66c7a6c9e4bda21f4ab1a0f1",
      "type": "city",
      "name": "Madrid",
      "description": "Madrid, Comunità di Madrid, Spagna",
      "match": "prefix",
      "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": "🇪🇸"
        }
      }
    }
  ],
  "count": 1,
  "session": { "token": "6f9e...", "billed": true, "ttl_seconds": 180 },
  "tokens_used": 1,
  "remaining_tokens": 4871
}

Campi della Risposta

Consumo di Token: si paga per sessione, non per tasto

Un completamento automatico invia una richiesta a ogni tasto. Addebitare per richiesta farebbe costare un singolo campo indirizzo 8-10 token e trasformerebbe la tua fattura in una funzione della velocità di digitazione dei tuoi utenti.

Invia un sessiontoken — un UUID qualsiasi, generato quando il campo riceve il focus — e l'intera sessione costa 1 token, indipendentemente da quante richieste sono servite:

1. Genera un token quando il campo indirizzo riceve il focus.
2. Invialo a ogni chiamata di /autocomplete. Solo la prima viene addebitata.
3. Invialo nella chiamata a /details per il suggerimento scelto dall'utente. Quella chiamata è gratuita e chiude la sessione.
4. Genera un nuovo token per il campo indirizzo successivo.

Le sessioni scadono dopo 3 minuti. Senza sessiontoken, ogni richiesta costa 1 token.

// Una sessione per ogni campo indirizzo
let session = crypto.randomUUID();

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

// ...ogni tasto riusa `session`, quindi l'intero campo costa 1 token

Risposta di Errore

{
  "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."
}

A differenza degli endpoint più vecchi, /v1/places/* restituisce un vero codice HTTP (400, 401, 402, 404) insieme a un error.code stabile. Consulta la documentazione dei codici di errore.

Chiamate dal browser

/v1/* invia Access-Control-Allow-Origin: *, quindi puoi chiamare il completamento automatico direttamente dal tuo frontend senza un proxy. Tieni presente che la chiave API sarà allora visibile a chiunque apra gli strumenti per sviluppatori: usa una chiave con un budget che ti va bene esporre, oppure passa dal tuo backend se la cosa ti preoccupa.

Consigli pratici

1. Applica un debounce di circa 150 ms. Meno richieste, stessa sensazione.
2. Richiedi 2-3 caratteri prima di lanciare la ricerca. Query più corte non sono utili.
3. Passa country quando lo conosci già. Meno suggerimenti, e migliori.
4. Passa types=city se il campo riguarda specificamente una città.
5. Non memorizzare nulla per utente — ma sei libero di salvare e mettere in cache i dati restituiti per tutto il tempo che vuoi. Non c'è alcuna restrizione sulla loro conservazione.

Endpoint Correlati

• GET /v1/places/details - Scheda completa di un suggerimento
• GET /v1/places/validate - Validare un indirizzo completo
• GET /v1/places/postal-format - Formato del codice postale per paese

Guida all'Integrazione Completa

• Completamento automatico degli indirizzi, dall'inizio alla fine