Documentazione API - Endpoint ed Esempi

Validazione degli Indirizzi

Verifica che un indirizzo esista e recuperalo in forma canonica

L'endpoint /v1/places/validate riceve il paese, la regione, la città e il codice postale digitati da un utente e ti dice se quella combinazione esiste davvero — componente per componente —, restituendo la grafia canonica e, quando qualcosa non torna, la correzione più vicina.

È l'ultimo passo prima di salvare un indirizzo di spedizione: il completamento automatico guida l'utente, questo conferma dove è andato a finire, inclusi gli indirizzi digitati a mano o importati da altrove.

Endpoint

GET  https://api.countrydataapi.com/v1/places/validate
POST https://api.countrydataapi.com/v1/places/validate

Entrambi accettano gli stessi campi. GET è una richiesta CORS semplice, quindi funziona dal browser senza preflight; POST li riceve in un corpo JSON.

Parametri

Parametro Tipo Obbligatorio Descrizione
apikey string Sì La tua chiave di autenticazione API
country string Sì Id interno, ISO-2, ISO-3 o nome
state string No Nome della regione o della provincia
city string No Nome della città
zipcode string No Codice postale
lang string No Lingua dei nomi restituiti. Predefinito: en

I componenti che non invii tornano con il verdetto not_provided: niente di ciò che ometti può invalidare l'indirizzo.

Esempio di Richiesta

curl "https://api.countrydataapi.com/v1/places/validate?apikey=la-tua-chiave-api&country=ES&state=Madrid&city=Madrid&zipcode=28001&lang=it"

POST con corpo JSON

const response = await fetch(
  'https://api.countrydataapi.com/v1/places/validate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      apikey: 'la-tua-chiave-api',
      country: 'ES',
      state: 'Madrid',
      city: 'Madrid',
      zipcode: '28001',
      lang: 'it',
    }),
  }
);
const { result } = await response.json();

SDK TypeScript

const { result } = await api.places.validate({
  country: 'ES',
  zipcode: '28001',
  lang: 'it',
});

result.normalized.state?.name; // "Comunità di Madrid"

Formato della Risposta

{
  "success": true,
  "result": {
    "valid": true,
    "has_corrections": false,
    "verdict": {
      "country": "confirmed",
      "state": "confirmed",
      "city": "confirmed",
      "zipcode": "confirmed"
    },
    "normalized": {
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "Spagna",
        "iso2": "ES",
        "iso3": "ESP",
        "phone_code": "+34",
        "flag": "🇪🇸"
      },
      "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Comunità di Madrid" },
      "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madrid" },
      "zipcode": "28001"
    },
    "corrections": [],
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345",
      "matches_format": true
    }
  },
  "tokens_used": 1,
  "remaining_tokens": 4870
}

Verdetti

Verdetto Significato
confirmed Il valore esiste e corrisponde esattamente a quanto inviato
corrected Il componente è stato risolto, ma non a partire da quanto inviato — vedi corrections
unconfirmed Il valore non è stato verificabile
not_provided Non hai inviato questo componente

valid è true solo quando tutti i componenti che hai inviato tornano come confirmed. Usa has_corrections per decidere se mostrare all'utente un "intendevi...?" invece di un errore.

Un codice postale da solo risolve la regione

Il caso tipico di un checkout: hai chiesto solo codice postale e città.

curl "https://api.countrydataapi.com/v1/places/validate?apikey=la-tua-chiave-api&country=ES&zipcode=28001&lang=it"

La risposta riempie normalized.state a partire dal codice postale, così puoi compilare il campo provincia al posto dell'utente invece di chiederglielo. Funziona anche al contrario: invia una città e la regione torna risolta.

Quando il codice postale non è nel nostro elenco

La copertura dei codici postali non è completa per tutti i paesi. Se un codice non è elencato ma corrisponde al formato ufficiale del paese, il verdetto è corrected invece di unconfirmed, e postal.matches_format vale true. Trattalo come "plausibile, accettalo", a meno che il tuo caso d'uso non richieda certezza.

matches_format è null quando il paese non ha un'espressione ufficiale registrata.

Esempio di correzione

{
  "valid": false,
  "has_corrections": true,
  "verdict": { "country": "confirmed", "state": "unconfirmed", "city": "confirmed", "zipcode": "not_provided" },
  "corrections": [
    { "component": "state", "input": "Cataluna", "suggestion": "Cataluña" }
  ]
}

Consumo di Token

Questo endpoint consuma 1 token per richiesta, indipendentemente da quanti componenti invii.

Endpoint Correlati