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 includereregionCode
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®)1 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.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. ↩