Questa pagina è stata tradotta dall'API Cloud Translation.

Convalidare un indirizzo

Per convalidare un indirizzo utilizzando l'API Address Validation, chiama il metodo validateAddress (REST) o il metodo ValidateAddress (gRPC). Questa documentazione utilizza REST per i suoi esempi, ma l'approccio è simile a gRPC.

Dopo aver convalidato un indirizzo, puoi facoltativamente restituire a Google informazioni sull'esito della convalida dell'indirizzo chiamando il metodo fornireValidationFeedback o REST (ValidateValidationFeedback). Per informazioni ed esempi, consulta Fornire un feedback di convalida dell'indirizzo.

Richiesta di convalida dell'indirizzo

Convalida un indirizzo inviando una richiesta POST al metodo validateAddress:

https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY

Passa un corpo JSON alla richiesta che definisce l'indirizzo da convalidare:

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"

Il campo address nel corpo della richiesta, di tipo AddressAddress, deve contenere almeno una voce in addressLines.

Il campo regionCode è facoltativo. Se omessa, l'API deduce l'area geografica dall'indirizzo. Tuttavia, per prestazioni ottimali, ti consigliamo di includere regionCode se lo conosci. Per l'elenco delle regioni supportate, consulta la pagina relativa alle regioni supportate.
La lunghezza totale del campo address è limitata a 280 caratteri.

Facoltativamente, puoi abilitare CASSTM durante la convalida di un indirizzo

Il servizio postale degli Stati Uniti® (USPS®)¹ gestisce il CodingPrecision Support System (CASSTM) per supportare e certificare i fornitori di servizi di convalida degli indirizzi. Un servizio CASS CertifiedTM, come l'API Address Validation, è stato confermato per la sua possibilità di inserire informazioni mancanti in un indirizzo, standardizzarlo e aggiornarlo per darti l'indirizzo più attuale e preciso.

Solo per le regioni "US" e "PR", puoi abilitare l'elaborazione CASS impostando enableUspsCass su true nel corpo della richiesta.

Per ottenere i migliori risultati quando utilizzi CASS, fornisci un indirizzo che includa la via e il numero civico, oltre alla città, alla provincia e al codice postale:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

Puoi anche specificare un indirizzo completo come due stringhe nell'array addressLines:

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
  "enableUspsCass": true
}

Risposta di convalida dell'indirizzo

Se la richiesta ha esito positivo, il server risponde con un codice di stato HTTP 200 OK e un corpo di risposta contenente informazioni sull'indirizzo convalidato.

Il campo result della risposta contiene un oggetto ValidationResult. Questo oggetto include:

Un campo address, di tipo Indirizzo, contenente informazioni dettagliate sull'indirizzo.
Un campo geocode, di tipo Geocode, contenente le informazioni geografiche per l'indirizzo.

Nota: per informazioni sulle differenze tra address e geocode, consulta Confronto tra indirizzo e geocodifica.
Un campo verdict, di tipo Verdict, contenente il risultato dell'indirizzo e la codifica geografica.
Un campo metadata, di tipo AddressMetadata, contenente i metadati per l'indirizzo.
Un campo uspsData, di tipo USPSData, contenente i dati USPS relativi all'indirizzo. Questi dati sono disponibili solo per gli indirizzi negli Stati Uniti e a Portorico.

Poiché la seguente risposta contiene addressComplete impostato su true, la risposta indica che questo indirizzo è completamente valido, quindi non è necessaria alcuna ulteriore convalida. Se la risposta indica che parte dell'indirizzo non è valida, chiedi all'utente di verificare e confermare la voce dell'indirizzo.

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600",
            "languageCode": "en"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4223878,
        "longitude": -122.0841877
      },
      "plusCode": {
        "globalCode": "849VCWC8+X8"
      },
      "bounds": {
        "low": {
          "latitude": 37.4220699,
          "longitude": -122.084958
        },
        "high": {
          "latitude": 37.4226618,
          "longitude": -122.0829302
        }
      },
      "featureSizeMeters": 116.538734,
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
      "placeTypes": [
        "premise"
      ]
    },
    "metadata": {
      "business": false,
      "poBox": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRoute": "C909",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S"
    }
  },
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Convalidare un indirizzo aggiornato

In alcuni casi, potrebbe essere necessario effettuare più chiamate all'API Address Validation per un singolo indirizzo. Ad esempio, l'utente potrebbe apportare modifiche o correggere il proprio indirizzo dopo aver visto i risultati della prima convalida. Successivamente, esegui una seconda convalida all'indirizzo aggiornato.

Ogni chiamata all'API Address Validation restituisce un valore univoco nel campo responseId della risposta. Se un indirizzo che stai cercando di convalidare deve essere convalidato, trasmetti responseId dalla prima risposta di convalida nel campo previousResponseId per tutte le richieste di follow-up all'API Address Validation.

Se includi il campo previousResponseId nella nuova richiesta, puoi aiutarci a migliorare la precisione complessiva dell'API.

Ad esempio, la risposta mostrata sopra include il campo responseId:

  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"

Successivamente, vuoi convalidare nuovamente l'indirizzo modificando il numero civico dal numero 1600 al numero 1500. Quando riconvalidi l'indirizzo, includi il campo previousResponseId con il valore di responseId della prima risposta:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Per una richiesta con CASS:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
  "enableUspsCass": true

}

I risultati di ogni chiamata successiva restituiscono un nuovo valore nel campo responseId. Tuttavia, continua a trasmettere il valore responseId dalla prima risposta nel campo previousResponseId in tutte le chiamate successive per aggiornare l'indirizzo.

Gestione degli errori

L'API Address Validation restituisce messaggi di errore come parte della risposta a una chiamata di metodo. Ad esempio, se ometti la chiave API dalla richiesta, il metodo restituisce:

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

Se ometti un parametro del corpo obbligatorio, come addressLines, il metodo restituisce:

{
  "error": {
    "code": 400,
    "message": "Address lines missing from request.",
    "status": "INVALID_ARGUMENT"
  }
}

Per maggiori informazioni sugli errori e sulla relativa gestione, consulta Errori.

Google Maps Platform è un licenziatario non esclusivo degli Stati Uniti postal Service®. I seguenti marchi sono di proprietà degli Stati Uniti Postal Service® e utilizzati con autorizzazione: United States Postal Service®, CASSTM, CASS CertifiedTM. ↩