Completamento Automatico dei Luoghi
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
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
apikey |
string | Sì | La tua chiave di autenticazione API |
q |
string | Sì | Quello che l'utente ha digitato. Minimo 2 caratteri |
country |
string | No | Limita i risultati a un paese: id interno, ISO-2, ISO-3 o nome |
types |
string | No | Livelli da cercare, separati da virgola: country, state, city. Predefinito: tutti e tre |
limit |
number | No | Numero di suggerimenti, 1-20. Predefinito: 5 |
lang |
string | No | Lingua dei nomi restituiti. Predefinito: en |
sessiontoken |
string | No | Raggruppa tutti i tasti premuti in un campo in un'unica sessione fatturabile |
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 —
avilatrovaÁvila,munchentrovaMünchen. - Insensibile alla punteggiatura —
hospitalettrovaL'Hospitalet de Llobregat. - Qualsiasi parola corrisponde —
yorktrovaNew 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
| Campo | Tipo | Descrizione |
|---|---|---|
suggestions[].id |
string | Da passare a /v1/places/details |
suggestions[].type |
string | country, state o city |
suggestions[].name |
string | Nome nella lingua richiesta |
suggestions[].description |
string | Pronto da mostrare: "Madrid, Comunità di Madrid, Spagna" |
suggestions[].match |
string | exact, prefix o word |
suggestions[].components |
object | Gerarchia risolta: city, state, country |
session |
object | Presente solo se hai inviato un sessiontoken. billed indica se questa chiamata è stata addebitata |
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:
- Genera un token quando il campo indirizzo riceve il focus.
- Invialo a ogni chiamata di
/autocomplete. Solo la prima viene addebitata. - Invialo nella chiamata a
/detailsper il suggerimento scelto dall'utente. Quella chiamata è gratuita e chiude la sessione. - 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
- Applica un debounce di circa 150 ms. Meno richieste, stessa sensazione.
- Richiedi 2-3 caratteri prima di lanciare la ricerca. Query più corte non sono utili.
- Passa
countryquando lo conosci già. Meno suggerimenti, e migliori. - Passa
types=cityse il campo riguarda specificamente una città. - 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
Confronta piani e prezzi: Vedi i prezzi di CountryDataAPI