Method: validateAddress

Convalida un indirizzo.

Richiesta HTTP

POST https://addressvalidation.googleapis.com/v1:validateAddress

L'URL utilizza la sintassi di transcodifica gRPC.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
Campi
address

object (PostalAddress)

obbligatorio. L'indirizzo in fase di convalida. Gli indirizzi non formattati devono essere inviati tramite addressLines.

La lunghezza totale dei campi in questo input non deve superare i 280 caratteri.

Le regioni supportate sono disponibili qui.

Il valore languageCode nell'indirizzo di input è riservato per utilizzi futuri e viene ignorato oggi. Il risultato dell'indirizzo convalidato verrà compilato in base alla lingua preferita per l'indirizzo specificato, come identificato dal sistema.

L'API Address Validation ignora i valori in recipients e organization. I valori in questi campi verranno eliminati e non verranno restituiti. Non impostarle.

previousResponseId

string

Questo campo deve essere vuoto per la prima richiesta di convalida dell'indirizzo. Se sono necessarie più richieste per convalidare completamente un singolo indirizzo (ad esempio, se le modifiche apportate dall'utente dopo la convalida iniziale devono essere riconvalidate), ogni richiesta di follow-up deve completare questo campo con il valore responseId della prima risposta della sequenza di convalida.

enableUspsCass

boolean

Attiva la modalità compatibile con USPS CASS. Questo influisce solo sul campo google.maps.addressvalidation.v1.ValidationResult.usps_data di google.maps.addressvalidation.v1.ValidationResult. Nota: per le richieste abilitate per USPS CASS per indirizzi a Portorico, è necessario fornire un google.type.PostalAddress.region_code di address come "PR" oppure un google.type.PostalAddress.administrative_area di address come "Portorico" (senza distinzione tra maiuscole e minuscole) o "PR".

Si consiglia di utilizzare un oggetto address componente o in alternativa specificare almeno due google.type.PostalAddress.address_lines, dove la prima riga contiene il numero civico e il nome e la seconda contiene la città, la provincia e il codice postale.

languageOptions

object (LanguageOptions)

Campo facoltativo. Anteprima: questa funzionalità è in anteprima (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le Offerte pre-GA sono coperte dai Termini di servizio specifici per Google Maps Platform. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Consente all'API Address Validation di includere informazioni aggiuntive nella risposta.

sessionToken

string

Campo facoltativo. Una stringa che identifica una sessione di completamento automatico ai fini della fatturazione. Deve essere una stringa Base64 sicura per URL e nome file con al massimo 36 caratteri ASCII. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

La sessione inizia quando l'utente esegue una query di completamento automatico e si conclude quando seleziona un luogo e viene effettuata una chiamata a Place Details o Address Validation. Ogni sessione può avere più query di completamento automatico, seguite da una richiesta Dettagli luogo o Convalida indirizzo. Le credenziali utilizzate per ogni richiesta all'interno di una sessione devono appartenere allo stesso progetto della console Google Cloud. Al termine di una sessione, il token non è più valido; l'app deve generare un token nuovo per ogni sessione. Se il parametro sessionToken viene omesso o se riutilizzi un token di sessione, la sessione viene addebitata come se non fosse stato fornito un token di sessione (ogni richiesta viene fatturata separatamente).

Nota: Address Validation può essere utilizzata solo in sessioni con l'API Autocomplete (New) e non con l'API Autocomplete. Per maggiori dettagli, visita la pagina https://developers.google.com/maps/documentation/places/web-service/session-pricing.

Corpo della risposta

La risposta a una richiesta di convalida dell'indirizzo.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
Campi
result

object (ValidationResult)

Il risultato della convalida dell'indirizzo.

responseId

string

L'UUID che identifica questa risposta. Se l'indirizzo deve essere riconvalidato, questo UUID deve accompagnare la nuova richiesta.

PostalAddress

Rappresenta un indirizzo postale, ad esempio per la consegna postale o gli indirizzi per i pagamenti. Dato un indirizzo postale, un servizio postale può consegnare gli articoli a un locale, a una casella postale o simili. Non è destinata a modellare località geografiche (strade, città, montagne).

Nell'uso tipico, un indirizzo viene creato tramite l'input dell'utente o dall'importazione di dati esistenti, a seconda del tipo di processo.

Consigli per l'inserimento / modifica dell'indirizzo: - Usa un widget per indirizzi pronti per l'internazionalizzazione, come https://github.com/google/libaddressinput). Gli utenti non devono visualizzare elementi UI per l'inserimento o la modifica di campi al di fuori dei paesi in cui viene utilizzato questo campo.

Per ulteriori indicazioni su come utilizzare questo schema, consulta la pagina: https://support.google.com/business/answer/6397478

Rappresentazione JSON
{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}
Campi
revision

integer

La revisione dello schema di PostalAddress. Qualsiasi valore diverso da 0 farà sì che l'API restituisca un errore INVALID_ARGUMENT.

regionCode

string

Campo facoltativo. Codice regione CLDR del paese o della regione dell'indirizzo. Per maggiori dettagli, visita le pagine https://cldr.unicode.org/ e https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html. Esempio: "CH" per la Svizzera. Se non viene fornito il codice regione, verrà dedotto dall'indirizzo. Per ottenere prestazioni ottimali, ti consigliamo di includere il codice regione, se lo conosci. La presenza di regioni incoerenti o ripetute può causare un rendimento scarso. Ad esempio, se addressLines include già la regione, non specificare di nuovo il codice regione in questo campo. Le regioni supportate sono disponibili nella sezione Domande frequenti.

languageCode

string

Il codice lingua nell'indirizzo di input è riservato per utilizzi futuri e viene ignorato oggi. L'API restituisce l'indirizzo nella lingua appropriata per la posizione in cui si trova l'indirizzo.

postalCode

string

Campo facoltativo. Codice postale dell'indirizzo. Non tutti i paesi utilizzano o richiedono la presenza di codici postali; tuttavia, nel caso in cui vengano utilizzati, potrebbero attivare un'ulteriore convalida con altre parti dell'indirizzo (ad es. convalida stato/CAP negli Stati Uniti).

sortingCode

string

Campo facoltativo. Codice di ordinamento aggiuntivo specifico per il paese. Non è utilizzata nella maggior parte delle regioni. Quando viene utilizzato, il valore è una stringa come "CEDEX", facoltativamente seguita da un numero (ad es. "CEDEX 7") o solo un numero, che rappresenta il "codice di settore" (Giamaica), "indicatore dell'area di consegna" (Malawi) o "indicatore dell'ufficio postale" (ad es. Costa d'Avorio).

administrativeArea

string

Campo facoltativo. Suddivisione amministrativa massima utilizzata per gli indirizzi postali di un paese o di una regione. ad esempio uno stato, una provincia, un oblast o una prefettura. Nello specifico, per la Spagna questa è la provincia e non la comunità autonoma (ad es. "Barcellona" e non "Catalogna"). Molti paesi non utilizzano un'area amministrativa negli indirizzi postali. Ad esempio, in Svizzera il campo deve essere lasciato vuoto.

locality

string

Campo facoltativo. In genere si riferisce alla porzione di città dell'indirizzo. Esempi: città degli Stati Uniti, comune italiano, città del Regno Unito. Nelle regioni del mondo in cui le località non sono ben definite o non si adattano bene a questa struttura, lascia vuoto il campo delle località e utilizza le righe di indirizzo.

sublocality

string

Campo facoltativo. Circoscrizione dell'indirizzo. ad esempio quartieri, distretti e distretti.

addressLines[]

string

obbligatorio. Righe dell'indirizzo non strutturate che descrivono i livelli inferiori di un indirizzo.

Poiché i valori in addressLines non contengono informazioni sul tipo e a volte possono contenere più valori in un singolo campo (ad es. "Austin, TX"), è importante che l'ordine delle righe sia chiaro. L'ordine delle righe indirizzo deve essere "ordine busta" per il paese o la regione dell'indirizzo.

La rappresentazione strutturale minima consentita di un indirizzo è composta da tutte le informazioni inserite in addressLines. Se non viene fornito un valore regionCode, la regione viene dedotta dalle righe dell'indirizzo.

Creare un indirizzo contenente solo addressLines e poi la geocodifica è il modo consigliato per gestire indirizzi completamente non strutturati (invece di indovinare quali parti dell'indirizzo dovrebbero essere località o aree amministrative).

recipients[]

string

Evita di impostare questo campo. L'API Address Validation al momento non la utilizza. Anche se al momento l'API non rifiuterà le richieste con questo campo impostato, le informazioni verranno ignorate e non verranno restituite nella risposta.

organization

string

Evita di impostare questo campo. L'API Address Validation al momento non la utilizza. Anche se al momento l'API non rifiuterà le richieste con questo campo impostato, le informazioni verranno ignorate e non verranno restituite nella risposta.

LanguageOptions

Anteprima: questa funzionalità è in anteprima (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le Offerte pre-GA sono coperte dai Termini di servizio specifici per Google Maps Platform. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Consente all'API Address Validation di includere informazioni aggiuntive nella risposta.

Rappresentazione JSON
{
  "returnEnglishLatinAddress": boolean
}
Campi
returnEnglishLatinAddress

boolean

Anteprima: restituisci un google.maps.addressvalidation.v1.Address in inglese. Per informazioni dettagliate, visita la pagina google.maps.addressvalidation.v1.ValidationResult.english_latin_address.

ValidationResult

Il risultato della convalida di un indirizzo.

Rappresentazione JSON
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
Campi
verdict

object (Verdict)

Flag di esito complessivo

address

object (Address)

Informazioni sull'indirizzo stesso anziché sul geocodice.

geocode

object (Geocode)

Informazioni sulla località e sul luogo a cui è stato geocodificato l'indirizzo.

metadata

object (AddressMetadata)

Altre informazioni pertinenti per l'invio di contenuti. Non è garantito che metadata venga compilato completamente per ogni indirizzo inviato all'API Address Validation.

uspsData

object (UspsData)

Segnalazioni di consegna extra fornite da USPS. Fornita solo nella regione US e PR.

englishLatinAddress

object (Address)

Anteprima: questa funzionalità è in anteprima (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le Offerte pre-GA sono coperte dai Termini di servizio specifici per Google Maps Platform. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

L'indirizzo viene tradotto in inglese.

Gli indirizzi tradotti non sono riutilizzabili come input dell'API. Il servizio le fornisce in modo che l'utente possa utilizzare la propria lingua madre per confermare o rifiutare la convalida dell'indirizzo fornito in origine.

Se parte dell'indirizzo non include una traduzione in inglese, il servizio restituisce quella parte in una lingua alternativa che utilizza il latino. Leggi qui per una spiegazione di come viene selezionata la lingua alternativa. Se parte dell'indirizzo non contiene traduzioni o traslitterazioni in una lingua che utilizza la scrittura latina, il servizio restituisce quella parte nella lingua locale associata all'indirizzo.

Abilita questo output utilizzando il flag google.maps.addressvalidation.v1.LanguageOptions.return_english_latin_address.

Nota: i campi google.maps.addressvalidation.v1.Address.unconfirmed_component_types in englishLatinAddress e google.maps.addressvalidation.v1.AddressComponent.confirmation_level in englishLatinAddress.address_components non vengono compilati.

Esito

Panoramica generale del risultato della convalida dell'indirizzo e del geocodice.

Rappresentazione JSON
{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}
Campi
inputGranularity

enum (Granularity)

La granularità dell'indirizzo di input. Questo è il risultato dell'analisi dell'indirizzo di input e non fornisce indicatori di convalida. Per gli indicatori di convalida, consulta la sezione validationGranularity di seguito.

Ad esempio, se l'indirizzo di input include un numero di appartamento specifico, inputGranularity qui sarà SUB_PREMISE. Se non è possibile trovare una corrispondenza con il numero dell'appartamento nei database o se il numero dell'appartamento non è valido, è probabile che validationGranularity sia pari o inferiore a PREMISE.

validationGranularity

enum (Granularity)

Il livello di granularità per cui l'API può validate completamente l'indirizzo. Ad esempio, validationGranularity pari a PREMISE indica che è possibile convalidare tutti i componenti dell'indirizzo a livello di PREMISE o più approssimativo.

Il risultato della convalida del componente per indirizzo è disponibile in google.maps.addressvalidation.v1.Address.address_components.

geocodeGranularity

enum (Granularity)

Informazioni sulla granularità di geocode. Può essere inteso come il significato semantico di quanto sia approssimativa o precisa la posizione geocodificata.

Questo valore a volte può differire dai validationGranularity riportati sopra. Ad esempio, il nostro database potrebbe registrare l'esistenza di un numero di appartamento ma non avere una posizione esatta dell'appartamento all'interno di un grande complesso di appartamenti. In questo caso, il valore di validationGranularity sarà SUB_PREMISE, mentre geocodeGranularity sarà PREMISE.

addressComplete

boolean

L'indirizzo è considerato completo se non sono presenti token non risolti e non sono presenti componenti imprevisti o mancanti dell'indirizzo. Se non viene configurato, indica che il valore è false. Per ulteriori dettagli, vedi i campi missingComponentTypes, unresolvedTokens o unexpected.

hasUnconfirmedComponents

boolean

Almeno un componente dell'indirizzo non può essere classificato o convalidato. Consulta google.maps.addressvalidation.v1.Address.address_components per i dettagli.

hasInferredComponents

boolean

È stato dedotto (aggiunto) almeno un componente dell'indirizzo che non era presente nell'input. Consulta google.maps.addressvalidation.v1.Address.address_components per i dettagli.

hasReplacedComponents

boolean

È stato sostituito almeno un componente dell'indirizzo. Consulta google.maps.addressvalidation.v1.Address.address_components per i dettagli.

Granularità

Le varie granularità che un indirizzo o un geocodice può avere. Quando vengono utilizzati per indicare la granularità di un indirizzo, questi valori indicano il grado di granularità dell'identificazione di una destinazione di distribuzione da parte dell'indirizzo. Ad esempio, un indirizzo come "Via Roma 123, Fiumicino - RM 00194" identifica un identificativo PREMISE, mentre un indirizzo LOCALITY Tuttavia, se non riusciamo a trovare un codice geografico per "123 Main Street" a Redwood City, il codice geografico restituito potrebbe essere di granularità LOCALITY anche se l'indirizzo è più granulare.

Enum
GRANULARITY_UNSPECIFIED Valore predefinito. Questo valore non è utilizzato.
SUB_PREMISE Sotto il risultato al livello dell'edificio, ad esempio un appartamento.
PREMISE Risultato a livello di edificio.
PREMISE_PROXIMITY Un codice geografico che indica in modo approssimativo la posizione dell'indirizzo a livello dell'edificio.
BLOCK L'indirizzo o il codice geografico indica un blocco. Utilizzata solo nelle regioni con indirizzi a livello di blocco, come il Giappone.
ROUTE Il codice geografico o l'indirizzo è granulare per il percorso, ad esempio una strada, una strada o un'autostrada.
OTHER Tutte le altre granularità, che vengono raggruppate insieme in quanto non possono essere fornite.

Indirizzo

Dettagli dell'indirizzo post-elaborato. La post-elaborazione include la correzione delle parti dell'indirizzo con errori ortografici, la sostituzione di parti errate e la deduzione delle parti mancanti.

Rappresentazione JSON
{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}
Campi
formattedAddress

string

L'indirizzo post-elaborato, formattato come indirizzo di una sola riga che segue le regole di formattazione dell'indirizzo della regione in cui si trova l'indirizzo.

postalAddress

object (PostalAddress)

L'indirizzo post-elaborato rappresentato come indirizzo postale.

addressComponents[]

object (AddressComponent)

Elenco non ordinato. I singoli componenti dell'indirizzo formattato e corretto, insieme alle informazioni di convalida. Fornisce informazioni sullo stato di convalida dei singoli componenti.

I componenti dell'indirizzo non sono ordinati in un modo particolare. Non fare ipotesi sull'ordine dei componenti dell'indirizzo nell'elenco.

missingComponentTypes[]

string

I tipi di componenti che dovevano essere presenti in un indirizzo postale formattato correttamente, ma che non sono stati trovati nell'input E non è stato possibile dedurre. I componenti di questo tipo non sono presenti in formattedAddress, postalAddress o addressComponents. Un esempio potrebbe essere ['street_number', 'route'] per un input simile a "Boulder, Colorado, 80301, USA". L'elenco dei possibili tipi è disponibile qui.

unconfirmedComponentTypes[]

string

I tipi di componenti presenti in addressComponents, ma di cui non è stato possibile confermare la correttezza. Questo campo è fornito per comodità: i suoi contenuti equivalgono all'iterazione tramite addressComponents per trovare i tipi di tutti i componenti in cui confirmationLevel non è CONFIRMED o il flag inferred non è impostato su true. L'elenco dei possibili tipi è disponibile qui.

unresolvedTokens[]

string

Eventuali token nell'input che non è stato possibile risolvere. Potrebbe trattarsi di un input che non è stato riconosciuto come parte valida di un indirizzo (ad esempio, in un input come "123235253253 Main St, San Francisco, CA, 94105", i token non risolti potrebbero essere simili a ["123235253253"] poiché non sembra un numero civico valido.

AddressComponent

Rappresenta un componente dell'indirizzo, come una strada, una città o una provincia.

Rappresentazione JSON
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
Campi
componentName

object (ComponentName)

Il nome di questo componente.

componentType

string

Il tipo di componente dell'indirizzo. Consulta la Tabella 2: tipi aggiuntivi restituiti dal servizio Places per un elenco dei tipi possibili.

confirmationLevel

enum (ConfirmationLevel)

Indica il livello di certezza che il componente è corretto.

inferred

boolean

Indica che il componente non faceva parte dell'input, ma lo abbiamo dedotto per la posizione dell'indirizzo e riteniamo che debba essere fornito per un indirizzo completo.

spellCorrected

boolean

Indica una correzione a un errore di ortografia nel nome del componente. L'API non segnala sempre le modifiche da una variante ortografica a un'altra, ad esempio quando si cambia "center" in "center". Inoltre, non segnala sempre errori di ortografia comuni, come la modifica di "Amphitheater Pkwy" in "Amphitheatre Pkwy".

replaced

boolean

Indica che il nome del componente è stato sostituito con uno completamente diverso, ad esempio un codice postale errato che è stato sostituito con uno corretto per l'indirizzo. Non si tratta di una modifica formale, il componente di input è stato sostituito con uno diverso.

unexpected

boolean

Indica un componente dell'indirizzo che non dovrebbe essere presente in un indirizzo postale per la regione specificata. Le abbiamo conservate solo perché facevano parte dell'input.

ComponentName

Un wrapper per il nome del componente.

Rappresentazione JSON
{
  "text": string,
  "languageCode": string
}
Campi
text

string

Il testo del nome. Ad esempio, "5th Avenue" per il nome di una via o "1253" per un numero civico.

languageCode

string

Il codice lingua BCP-47. Non sarà presente se il nome del componente non è associato a una lingua, come un numero civico.

ConfirmationLevel

I diversi valori possibili per i livelli di conferma.

Enum
CONFIRMATION_LEVEL_UNSPECIFIED Valore predefinito. Questo valore non è utilizzato.
CONFIRMED Abbiamo potuto verificare che questo componente esista e abbia senso nel contesto del resto dell'indirizzo.
UNCONFIRMED_BUT_PLAUSIBLE Non è stato possibile confermare questo componente, ma è plausibile che esista. Ad esempio, un numero civico compreso in un intervallo valido noto di una via in cui non sono noti numeri civici specifici.
UNCONFIRMED_AND_SUSPICIOUS Questo componente non è stato confermato ed è probabile che sia errato. Ad esempio, un quartiere che non corrisponde al resto dell'indirizzo.

Geocodifica

Contiene informazioni sul luogo in cui è stato geocodificato l'input.

Rappresentazione JSON
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
Campi
location

object (LatLng)

La posizione geocodificata dell'input.

È preferibile utilizzare gli ID luogo rispetto a indirizzi, coordinate di latitudine/longitudine o plus code. L'utilizzo delle coordinate per il calcolo degli itinerari o delle indicazioni stradali comporta sempre l'agganciamento del punto alla strada più vicina a queste coordinate. Potrebbe non essere una strada che condurrà rapidamente o in sicurezza alla destinazione e potrebbe non essere vicina a un punto di accesso alla proprietà. Inoltre, se una località viene geocodificata in modo inverso, non vi è alcuna garanzia che l'indirizzo restituito corrisponda all'originale.

plusCode

object (PlusCode)

Il plus code corrispondente a location.

bounds

object (Viewport)

I confini del luogo geocodificato.

featureSizeMeters

number

Le dimensioni del luogo geocodificato in metri. Si tratta di un'altra misura della ruvidità della posizione geocodificata, ma in termini di dimensioni fisiche anziché di significato semantico.

placeId

string

Il PlaceID del luogo in cui viene geocodificato questo input.

Per ulteriori informazioni sugli ID luogo, visita questa pagina.

placeTypes[]

string

Il tipo o i tipi di luogo in cui è stato geocodificato l'input. Ad esempio, ['locality', 'political']. L'elenco completo dei tipi è disponibile qui.

LatLng

Un oggetto che rappresenta una coppia latitudine/longitudine. Questo valore è espresso come una coppia di doppi per rappresentare i gradi di latitudine e i gradi di longitudine. Se non diversamente specificato, questo oggetto deve essere conforme allo standard WGS84. I valori devono essere compresi negli intervalli normalizzati.

Rappresentazione JSON
{
  "latitude": number,
  "longitude": number
}
Campi
latitude

number

Latitudine in gradi. Deve essere compreso nell'intervallo [-90,0, +90,0].

longitude

number

Longitudine in gradi. Deve essere compreso nell'intervallo [-180,0, +180,0].

PlusCode

Il Plus Code (http://plus.codes) è un riferimento di località con due formati: codice globale che definisce un rettangolo di 14 x 14 m (1/8000 di grado) e un codice composto, che sostituisce il prefisso con una posizione di riferimento.

Rappresentazione JSON
{
  "globalCode": string,
  "compoundCode": string
}
Campi
globalCode

string

Il codice globale (completo) del luogo, ad esempio "9FWM33GV+HQ ", che rappresenta un'area di 1/8000 di 1/8000 gradi (~14 x 14 metri).

compoundCode

string

Codice composto del luogo, ad esempio "33GV+HQ, Ramberg, Norvegia ", contenente il suffisso del codice globale e sostituendo il prefisso con il nome formattato di un'entità di riferimento.

Area visibile

Un'area visibile con latitudine e longitudine, rappresentata da due punti diagonali opposti di low e high. Un'area visibile è considerata una regione chiusa, ovvero include i confini. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi, mentre i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi. Ecco alcuni casi:

  • Se low = high, l'area visibile è composta da quel singolo punto.

  • Se low.longitude > high.longitude, l'intervallo di longitudine viene invertito (l'area visibile si sovrappone alla linea di longitudine di 180 gradi).

  • Se low.longitude = -180 gradi e high.longitude = 180 gradi, l'area visibile include tutte le longitudini.

  • Se low.longitude = 180 gradi e high.longitude = -180 gradi, l'intervallo di longitudine è vuoto.

  • Se low.latitude > high.latitude, l'intervallo di latitudine è vuoto.

È necessario compilare entrambi i campi low e high e la casella rappresentata non può essere vuota (come specificato dalle definizioni precedenti). Un'area visibile vuota causerà un errore.

Ad esempio, questa area visibile racchiude completamente New York City:

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

Rappresentazione JSON
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Campi
low

object (LatLng)

obbligatorio. Il punto basso dell'area visibile.

high

object (LatLng)

obbligatorio. Il punto più alto dell'area visibile.

AddressMetadata

I metadati dell'indirizzo. Non è garantito che metadata venga compilato completamente per ogni indirizzo inviato all'API Address Validation.

Rappresentazione JSON
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
Campi
business

boolean

Indica che questo è l'indirizzo di un'attività commerciale. Se non viene configurato, indica che il valore è sconosciuto.

poBox

boolean

Indica l'indirizzo di una casella postale. Se non viene configurato, indica che il valore è sconosciuto.

residential

boolean

Indica che questo è l'indirizzo di una residenza. Se non viene configurato, indica che il valore è sconosciuto.

UspsData

I dati USPS per l'indirizzo. Non è garantito che uspsData venga compilato completamente per ogni indirizzo statunitense o PR inviato all'API Address Validation. Ti consigliamo di integrare i campi dell'indirizzo di backup nella risposta se utilizzi uspsData come parte principale della risposta.

Rappresentazione JSON
{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": string,
  "dpvNoStatReasonCode": integer,
  "dpvDrop": string,
  "dpvThrowback": string,
  "dpvNonDeliveryDays": string,
  "dpvNonDeliveryDaysValues": integer,
  "dpvNoSecureLocation": string,
  "dpvPbsa": string,
  "dpvDoorNotAccessible": string,
  "dpvEnhancedDeliveryCode": string,
  "carrierRoute": string,
  "carrierRouteIndicator": string,
  "ewsNoMatch": boolean,
  "postOfficeCity": string,
  "postOfficeState": string,
  "abbreviatedCity": string,
  "fipsCountyCode": string,
  "county": string,
  "elotNumber": string,
  "elotFlag": string,
  "lacsLinkReturnCode": string,
  "lacsLinkIndicator": string,
  "poBoxOnlyPostalCode": boolean,
  "suitelinkFootnote": string,
  "pmbDesignator": string,
  "pmbNumber": string,
  "addressRecordType": string,
  "defaultAddress": boolean,
  "errorMessage": string,
  "cassProcessed": boolean
}
Campi
standardizedAddress

object (UspsAddress)

Indirizzo standardizzato USPS.

deliveryPointCode

string

Codice punto di consegna a 2 cifre

deliveryPointCheckDigit

string

La cifra di controllo del punto di consegna. Questo numero viene aggiunto alla fine del delivery_point_barcode per la posta scansionata meccanicamente. Sommando tutte le cifre di delivery_point_barcode, deliveryPointCheckDigit, codice postale e ZIP+4 si dovrebbe ottenere un numero divisibile per 10.

dpvConfirmation

string

I valori possibili per la conferma DPV. Restituisce un singolo carattere o non restituisce alcun valore.

  • N: la conferma da parte del DPV delle informazioni relative al numero principale e agli eventuali numeri secondari non è riuscita.
  • D: il DPV dell'indirizzo è stato confermato solo per il numero principale e le informazioni sul numero secondario erano mancanti.
  • S: l'indirizzo è stato confermato solo per il numero principale e le informazioni sul numero secondario erano presenti, ma non confermate.
  • Y: l'indirizzo è stato confermato per i numeri primari e secondari.
  • Vuoto: se la risposta non contiene un valore dpvConfirmation, l'indirizzo non è stato inviato per la conferma della DPV.
dpvFootnote

string

Le note a piè di pagina della convalida del punto di consegna. Più note a piè di pagina possono essere unite nella stessa stringa.

  • AA: inserisci l'indirizzo che corrisponde al file ZIP+4
  • A1: l'indirizzo inserito non corrisponde al file ZIP+4
  • BB: corrispondenza con DPV (tutti i componenti)
  • CC: numero secondario non corrispondente e non obbligatorio
  • C1: numero secondario non corrispondente, ma obbligatorio
  • N1: indirizzo a un grattacielo senza numero secondario
  • M1: numero principale mancante
  • M3: numero principale non valido
  • P1: numero di casella PO, RR o HC nell'indirizzo di input mancante
  • P3: il numero di PO, RR o HC dell'indirizzo di input non è valido
  • F1: indirizzo di input corrispondente a un indirizzo militare
  • G1: inserisci l'indirizzo corrispondente a un indirizzo di consegna generale
  • U1: inserisci l'indirizzo che corrisponde a un codice postale univoco
  • PB: indirizzo di input corrispondente al record PBSA
  • RR: indirizzo confermato da DPV con informazioni PMB
  • R1: indirizzo confermato da DPV senza informazioni PMB
  • R7: record Route R777 o R779 dell'operatore
  • IA: indirizzo informato identificato
  • TA: numero principale corrispondente eliminando una lettera alfa finale
dpvCmra

string

Indica se l'indirizzo è una CMRA (Commercial Mail Receipt Agency), un'azienda privata che riceve posta per i clienti. Restituisce un singolo carattere.

  • Y: l'indirizzo è una CMRA
  • N: l'indirizzo non è una CMRA
dpvVacant

string

Questo luogo non è disponibile? Restituisce un singolo carattere.

  • Y: l'indirizzo è vacante
  • N: l'indirizzo non è vacante
dpvNoStat

string

È un indirizzo senza statistica o è attivo? Non si tratta di indirizzi per le statistiche che non sono continuamente occupati o che non vengono serviti dall'USPS. Restituisce un singolo carattere.

  • Y: l'indirizzo non è attivo
  • N: l'indirizzo è attivo
dpvNoStatReasonCode

integer

Indica il tipo NoStat. Restituisce un codice motivo come int.

  • 1: IDA (Internal Drop Address) - Indirizzi che non ricevono posta direttamente dall'USPS, ma vengono consegnati a un indirizzo di consegna che li fornisce.
  • 2: CDS - Indirizzi che non sono ancora stati consegnati. Ad esempio, una nuova suddivisione in cui sono stati determinati lotti e numeri primari, ma non esiste ancora una struttura per il numero di persone.
  • 3: collisione - indirizzi che non confermano effettivamente il DPV.
  • 4: CMZ (università, forze armate e altri tipi), - ZIP + 4 record che USPS ha incorporato nei dati.
  • 5: normale: indica gli indirizzi che non ricevono la consegna e che non vengono conteggiati come possibili consegne.
  • 6: secondario obbligatorio. L'indirizzo richiede informazioni secondarie.
dpvDrop

string

Il contrassegno indica che la posta viene recapitata a un singolo destinatario in un sito. Restituisce un singolo carattere.

  • Y: la posta viene recapitata a un unico destinatario presso un sito.
  • N: la posta non viene recapitata a un singolo destinatario in un sito.
dpvThrowback

string

Indica che la posta non viene recapitata alla via. Restituisce un singolo carattere.

  • Y: la posta non viene recapitata alla via.
  • N: la posta viene recapitata alla via.
dpvNonDeliveryDays

string

Il flag indica che il recapito della posta non viene eseguito tutti i giorni della settimana. Restituisce un singolo carattere.

  • Y: la consegna della posta non viene effettuata tutti i giorni della settimana.
  • N: non indica che il recapito della posta non viene eseguito ogni giorno della settimana.
dpvNonDeliveryDaysValues

integer

Numero intero che identifica i giorni di mancata consegna. Può essere interrogato usando i bit flag: 0x40 – Domenica è un giorno di mancata consegna 0x20 – Lunedì è un giorno di mancata consegna 0x10 – Martedì è un giorno di mancata consegna 0x08 – Mercoledì è un giorno di mancata consegna 0x04 – Giovedì è un giorno di mancata consegna 0x02 – Venerdì è un giorno di mancata consegna 0x01 –

dpvNoSecureLocation

string

Il flag indica che la porta è accessibile, ma il pacco non verrà lasciato per problemi di sicurezza. Restituisce un singolo carattere.

  • Y: il pacco non verrà lasciato per motivi di sicurezza.
  • N: nessuna indicazione che il pacco verrà lasciato per motivi di sicurezza.
dpvPbsa

string

Indica che l'indirizzo è stato abbinato al record PBSA. Restituisce un singolo carattere.

  • Y: l'indirizzo è stato abbinato al record PBSA.
  • N: l'indirizzo non corrisponde al record PBSA.
dpvDoorNotAccessible

string

La bandierina indica gli indirizzi a cui USPS non può bussare alla porta per recapitare la posta. Restituisce un singolo carattere.

  • Y: la porta non è accessibile.
  • N: nessuna segnalazione che la porta non è accessibile.
dpvEnhancedDeliveryCode

string

Indica che più di un codice restituito DPV è valido per l'indirizzo. Restituisce un singolo carattere.

  • Y: l'indirizzo è stato confermato per i numeri primari e secondari.
  • N: la conferma da parte del DPV delle informazioni relative al numero principale e agli eventuali numeri secondari non è riuscita.
  • S: il DPV dell'indirizzo è stato confermato solo per il numero principale e le informazioni sul numero secondario erano presenti da non confermate oppure è stata eliminata una singola alfa finale su un numero principale per rendere obbligatoria una corrispondenza DPV e le informazioni secondarie.
  • D: il DPV dell'indirizzo è stato confermato solo per il numero principale e le informazioni sul numero secondario erano mancanti.
  • R: indirizzo confermato ma assegnato alle route fantasma R777 e R779 e la consegna con USPS non è stata fornita.
carrierRoute

string

Il codice di percorso dell'operatore. Un codice a quattro caratteri composto da un prefisso di una lettera e un identificatore di percorso a tre cifre.

Prefissi:

  • C: percorso dell'operatore (o percorso cittadino)
  • R: percorso rurale
  • H: tratta del contratto autostradale
  • B: sezione casella postale
  • G: unità di consegna generale
carrierRouteIndicator

string

Indicatore di ordinamento della tariffa di percorso del corriere.

ewsNoMatch

boolean

L'indirizzo di consegna può corrispondere, ma il file EWS indica che sarà disponibile a breve una corrispondenza esatta.

postOfficeCity

string

Città dell'ufficio postale principale.

postOfficeState

string

Stato dell'ufficio postale principale.

abbreviatedCity

string

Città abbreviata.

fipsCountyCode

string

Codice contea FIPS.

county

string

Nome della contea.

elotNumber

string

Numero eLOT (Enhanced Line of Travel).

elotFlag

string

Flag eLOT crescente/decrescente (A/D).

poBoxOnlyPostalCode

boolean

solo il codice postale della casella postale.

pmbDesignator

string

Designatore di unità PMB (Private Mail Box).

pmbNumber

string

Numero PMB (Private Mail Box);

addressRecordType

string

Tipo del record dell'indirizzo che corrisponde all'indirizzo di input.

  • F: AZIENDA. Si tratta di una corrispondenza con un record fisso, che è il miglior livello di corrispondenza disponibile per un indirizzo.
  • G: CONSEGNA GENERALE. Questa è una corrispondenza con un record di consegna generale.
  • H: COSTRUZIONE / APPARTAMENTO. Questa è una corrispondenza con un record di edificio o appartamento.
  • P: QUADRO POST UFFICIO. Questa è una corrispondenza con una casella postale.
  • R: PERCORSO RURALE o CONTRATTO AUTOMATICO: corrisponde a un record di un percorso rurale o a un contratto autostradale, entrambi possono avere intervalli di numeri di casella associati.
  • S: RECORD DI STRADA: corrisponde a un record di strada contenente un intervallo di numeri principali valido.
defaultAddress

boolean

Indicatore che indica che è stato trovato un indirizzo predefinito, ma esistono indirizzi più specifici.

errorMessage

string

Messaggio di errore per il recupero dei dati USPS. Questo campo viene compilato quando l'elaborazione USPS viene sospesa a causa del rilevamento di indirizzi creati artificialmente.

I campi dei dati USPS potrebbero non essere compilati quando è presente questo errore.

cassProcessed

boolean

Indicatore che indica che la richiesta è stata elaborata dal CASS.

UspsAddress

Rappresentazione USPS di un indirizzo negli Stati Uniti.

Rappresentazione JSON
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
Campi
firstAddressLine

string

Prima riga dell'indirizzo.

firm

string

Nome dell'azienda.

secondAddressLine

string

Seconda riga indirizzo.

urbanization

string

Nome dell'urbanizzazione portoricana.

cityStateZipAddressLine

string

Città + stato + codice postale.

city

string

Nome della città.

state

string

Codice di stato di 2 lettere.

zipCode

string

Codice postale, ad esempio 10009.

zipCodeExtension

string

Estensione codice postale a 4 cifre, ad esempio 5023.