Cercare destinazioni

Sviluppatori dello Spazio economico europeo (SEE)

Una Destination si riferisce a una località o un luogo specifico che un utente intende raggiungere o verso cui vuole navigare. Un Destination include anche una raccolta di informazioni relative alla località o al luogo, come punti di navigazione, punti di riferimento, ingressi e sagome degli edifici.

Il metodo SearchDestinations dell'API Geocoding ti consente di recuperare informazioni dettagliate su varie destinazioni in base a diversi criteri di input, come un indirizzo, un ID luogo o coordinate di latitudine e longitudine.

Richiesta di ricerca delle destinazioni

Una richiesta di ricerca delle destinazioni è una richiesta POST HTTP a un URL nel formato:

https://geocode.googleapis.com/v4/geocode/destinations

Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni come parte della richiesta POST. Ad esempio:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

Puoi specificare la località in cui cercare una destinazione in uno dei tre modi seguenti:

  • Indirizzo
  • ID luogo
  • Coordinate di latitudine e longitudine

Cerca una destinazione per indirizzo

Puoi specificare l'indirizzo come stringa non strutturata. La geocodifica degli indirizzi non risolve le coordinate di latitudine e longitudine o altre stringhe non strutturate che non rappresentano un indirizzo. Le richieste che utilizzano queste stringhe non sono supportate e potrebbero generare risposte di errore o comportamenti non specificati. Ecco alcuni esempi di query non supportate:

Tipo di query Esempio
Coordinate di latitudine e longitudine. Utilizza invece una query sulla posizione. "37.422131,-122.084801"
Troppi concetti o vincoli, ad esempio i nomi di più luoghi, strade o città in una singola query "Market Street San Francisco San Jose Airport"
Elementi dell'indirizzo postale non rappresentati su Google Maps "C/O Mario Rossi, Via Roma 123"
"Casella postale 13, Roma"
Nomi di attività, catene o categorie combinati con località in cui queste entità non sono disponibili "Tesco vicino a Dallas, Texas"
Query ambigue con più interpretazioni "Charger drop-off"
Nomi storici non più in uso "Middlesex United Kingdom"
Elementi o intenti non geospaziali "Quante barche ci sono nel porto di Ventura?"
Nomi non ufficiali o vanity "The Jenga"
"The Helter Skelter"
Grandi entità politiche (città, stati, paesi) "New York"
"California"
"USA"
Percorsi senza indirizzi specifici "1st Ave., NYC, NY"
"I-95" 
curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

oppure come postalAddress:

curl -X POST -d '{
  "addressQuery": {
    "address": {
      "addressLines": ["601 S Bernardo Ave"],
      "locality": "Sunnyvale",
      "postalCode": "94087",
      "administrativeArea": "CA",
      "regionCode": "US"
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

In genere, utilizzi il formato postalAddress quando elabori i componenti dell'indirizzo acquisiti in un modulo HTML.

Cerca una destinazione per ID luogo

Puoi recuperare una destinazione fornendo un ID luogo:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

ID luogo supportati

Il metodo Search Destinations funziona meglio con gli ID luogo che rappresentano destinazioni specifiche e navigabili. Gli ID luogo per tipi come establishment, point_of_interest, premise, street_address e subpremise sono generalmente supportati. Gli ID luogo che non rappresentano località distinte, come quelle dedotte da intervalli di indirizzi (ad esempio "10-20 Main St"), sezioni di un percorso senza un numero specifico o Plus Code non sono supportati. Inoltre, non sono supportati gli ID luogo per i risultati con un'area troppo grande (ad esempio, "Oceano Pacifico").

Utilizza Autocomplete (New) con Search Destinations

Per garantire la compatibilità, utilizza Autocomplete (New) per trovare gli ID luogo da utilizzare con Search Destinations. Quando utilizzi Autocomplete (New), devi filtrare i risultati per tipo utilizzando il parametro includedPrimaryTypes. Gli ID luogo restituiti da Autocomplete (New) utilizzando il seguente filtro consigliato sono supportati da Search Destinations:

"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]

Inoltre, non devi impostare il flag include_pure_service_area_businesses su true nella richiesta di Autocomplete (New).

Cerca una destinazione per località

Puoi cercare una destinazione fornendo le coordinate di latitudine e longitudine:

curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

Utilizza OAuth per effettuare una richiesta

L'API Geocoding v4 supporta OAuth 2.0 per l'autenticazione. Per utilizzare OAuth con l'API Geocoding, al token OAuth deve essere assegnato l'ambito corretto. L'API Geocoding supporta i seguenti ambiti per l'utilizzo con il metodo Destinations:

  • https://www.googleapis.com/auth/maps-platform.geocode - Da utilizzare con tutti i metodi dell'API Geocoding.

Inoltre, puoi utilizzare l'ambito generale https://www.googleapis.com/auth/cloud-platform per tutti i metodi dell'API Geocoding. Questo ambito è utile durante lo sviluppo, ma non in produzione, perché è un ambito generale che consente l'accesso a tutti i metodi.

Per ulteriori informazioni ed esempi, consulta la sezione Utilizza OAuth.

Risposta di Search Destinations

La risposta di Search Destinations fornisce un contesto iperlocale dettagliato sulla località.

Gli oggetti PlaceView all'interno della risposta di Search Destinations (come primary, gli elementi in containingPlaces e landmarks) utilizzano i campi per indicare il tipo di luogo:

  • types: un array di stringhe che indica i tipi di luogo.
  • primaryType: una stringa che indica il tipo principale del luogo.

I possibili valori di stringa per types e primaryType sono tratti dalla Tabella A e dalla Tabella B della pagina Tipi di luoghi (nuova).

Questa sezione descrive i campi di risposta principali. Per informazioni dettagliate su tutti i campi della risposta, consulta il Riferimento API.

primary

Il luogo principale identificato dalla query nella richiesta.

addressComponents

Un array contenente i singoli componenti applicabili a questo indirizzo.

Ogni componente dell'indirizzo contiene in genere i seguenti campi:

  • types[] è un array che indica il tipo di componente dell'indirizzo. Consulta l'elenco dei tipi supportati.
  • longText è la descrizione testuale completa o il nome del componente dell'indirizzo restituito dal geocodificatore.
  • shortText è un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere un longText "Alaska" e un shortText "AK" utilizzando l'abbreviazione postale di due lettere.
  • languageCode è la lingua utilizzata per formattare questo componente, nella notazione CLDR.

containingPlaces

Un array di oggetti PlaceView che rappresentano entità spaziali più grandi che racchiudono o contengono la destinazione principale. Ad esempio:

  • Se la destinazione principale è un negozio o un ristorante all'interno di un centro commerciale, containingPlaces include il centro commerciale (structureType: GROUNDS).
  • Se la destinazione principale è un singolo appartamento (subpremise), containingPlaces include l'edificio residenziale che lo contiene (structureType: BUILDING) e, se applicabile, il complesso di appartamenti più ampio (structureType: GROUNDS).

Ogni PlaceView in containingPlaces include i propri displayName, placeId, location, structureType e displayPolygon (se disponibili), consentendoti di visualizzare l'intero campus o il profilo del complesso insieme all'unità specifica.

subDestinations

Un array di oggetti PlaceView che rappresentano località più specifiche contenute all'interno della destinazione principale. Ad esempio:

  • Quando esegui una query su un centro commerciale, un aeroporto o un campus universitario, subDestinations elenca i singoli negozi, terminal, gate o edifici del campus.
  • Quando esegui una query su un edificio residenziale o commerciale con più unità, subDestinations elenca le singole suite o unità di appartamenti.

Puoi utilizzare containingPlaces e subDestinations insieme per creare selettori gerarchici interattivi che aiutano gli utenti a risolvere le ambiguità delle località di arrivo complesse.

Gerarchia delle destinazioni e comportamento delle risposte

Quando interpreti una risposta Destination, tieni presente le seguenti regole e relazioni strutturali:

  • primary: rappresenta l'entità più specifica risolta per la query (ad esempio un edificio o un locale secondario). Questo campo viene compilato nella maggior parte dei casi d'uso normali. Tuttavia, nelle aree rurali è possibile che una destinazione non abbia un'entità principale, pur avendo punti di navigazione o punti di riferimento.
  • containingPlaces rappresenta i genitori (antenati) che lo contengono: containingPlaces viene compilato quando il luogo principale è fisicamente contenuto all'interno di strutture spaziali più grandi. Per luoghi più specifici, come un'unità immobiliare, può elencare tutti i livelli principali della gerarchia. Può includere sezioni di edifici, il BUILDING e il campus o la società residenziale GROUNDS. Se una destinazione è un edificio autonomo indipendente o un segnaposto isolato, containingPlaces potrebbe essere vuoto.
  • subDestinations rappresenta i luoghi secondari contenuti (discendenti): subDestinations viene compilato quando la destinazione contiene fisicamente luoghi più granulari e può includere diversi tipi di strutture secondarie, ad esempio BUILDING secondari in un campus o in un terreno, oppure unità, sezioni e negozi interni a un edificio.

entrances

Gli oggetti nell'array entrances[] hanno i seguenti campi:

  • displayName

    Un oggetto LocalizedText contenente un nome leggibile per l'ingresso (ad esempio "South Bernardo Avenue" o "5th Avenue"), se disponibile.

  • location

    Una singola coppia di coordinate di latitudine/longitudine che definisce la posizione di un punto di ingresso e di uscita in un luogo.

  • entrance_tags[]

    Un array di tag di ingresso che descrive le caratteristiche dell'ingresso. È supportato il seguente valore:

    • "PREFERRED"

    Indica che questo ingresso probabilmente fornisce l'accesso fisico al luogo restituito. Un luogo può avere più ingressi preferiti. Se un'entrata non ha questo tag, significa che si trova fisicamente nello stesso edificio, ma non fornisce necessariamente l'accesso al luogo.

    Ad esempio, se il luogo restituito è un ristorante in un centro commerciale, gli ingressi "PREFERRED" saranno quelli che conducono al ristorante stesso, mentre gli altri ingressi restituiti saranno altri ingressi dell'edificio, ad esempio gli ingressi di altri ristoranti nel centro commerciale.

    Se il luogo restituito è un edificio, gli ingressi "PREFERRED" saranno quelli che conducono alla parte "principale" dell'edificio. Ad esempio, in un centro commerciale gli ingressi "PREFERRED" saranno quelli che consentono l'accesso all'area dell'atrio principale, ma se un ingresso consente l'accesso solo a un negozio sul lato dell'edificio, non sarà un ingresso "PREFERRED".

  • streetViewThumbnail e streetViewAnnotation

    Parametri per l'API Street View Static, che ti consentono di visualizzare immagini pertinenti per queste località. Scopri di più su questi campi.

structureType

Il tipo di struttura rappresentato da questo luogo.

  • POINT

    Una posizione puntuale.

  • SECTION

    Una sottosezione di un edificio.

  • BUILDING

    Un edificio.

  • GROUNDS

    Un'area di grandi dimensioni che in genere contiene più edifici, come un campus universitario, un complesso di appartamenti o un centro commerciale.

Il campo navigationPoints all'interno della risposta di geocodifica contiene un elenco di punti utili per raggiungere il luogo. In particolare, devono essere utilizzati come punti di partenza o di arrivo quando si calcola il percorso su una rete stradale da o verso il luogo.

Ogni punto di navigazione contiene i seguenti valori:

  • navigationPointToken è un token contenente le informazioni contestuali nel campo navigationPoints. Puoi inviare questo token alle API di routing e navigazione per migliorare l'esperienza di routing e di guida nella tua app. Per saperne di più, consulta Percorso utilizzando i token dei punti di navigazione.
  • location contiene il valore di latitudine e longitudine del punto di navigazione. Questa località sarà sempre molto vicina alla rete stradale e rappresenta un punto di partenza o di arrivo ideale per la navigazione da e verso un luogo. Il punto è intenzionalmente leggermente spostato rispetto alla linea centrale della strada per contrassegnare chiaramente il lato della strada in cui si trova il luogo.
  • travelModes è un elenco di modalità di viaggio da cui è accessibile il punto di navigazione:
    • "DRIVE" è la modalità di viaggio corrispondente alle indicazioni stradali.
    • "WALK" è la modalità di viaggio corrispondente alle indicazioni a piedi.
  • usages è un elenco di utilizzi supportati dal punto di navigazione. Gli utilizzi possono essere:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

Per i ritiri e le consegne, utilizza il punto di navigazione in cui la modalità di viaggio è DRIVE e l'utilizzo è PICKUP o DROPOFF. Se i punti di partenza o di arrivo non sono disponibili, utilizza il punto di navigazione principale.

  • altitude_meters contiene l'altitudine del punto di navigazione in metri rispetto all'ellissoide WGS-84. Nei casi in cui sono presenti segmenti stradali impilati verticalmente, utilizza il campo altitude_meters per scegliere il segmento stradale migliore verso cui il sistema deve navigare.

landmarks

Un array di oggetti Landmark che rappresentano Luoghi nelle vicinanze che aiutano gli utenti a orientarsi e a individuare la destinazione all'arrivo. Questa funzionalità sostituisce ed espande la funzionalità precedente dei descrittori di indirizzi v3.

Ogni oggetto Landmark contiene:

  • place: un oggetto PlaceView che descrive il punto di riferimento, inclusi displayName, placeId, location, types e displayPolygon.
  • relationalDescription: una stringa LocalizedText localizzata e leggibile che descrive la relazione spaziale tra la destinazione e il punto di riferimento (ad esempio, "Near Starbird Chicken", "Across from Central Park" o "Around the corner from the Empire State Building").
  • straightLineDistanceMeters: la distanza in linea d'aria in metri dal punto di riferimento alla destinazione.
  • travelDistanceMeters: la distanza di viaggio stimata in metri lungo la rete stradale o pedonale tra il punto di riferimento e la destinazione.
  • tags: tag contestuali che indicano il ruolo spaziale del punto di riferimento rispetto alla destinazione:
    • "ARRIVAL": punto di riferimento iperlocale immediatamente adiacente o di fronte alla destinazione (in genere entro 50-100 m), ideale per le indicazioni per l'arrivo dell'ultimo miglio.
    • "ADDRESS": punto di riferimento importante a livello locale nel quartiere circostante (in genere entro 100-500 m), ideale per l'orientamento prima del viaggio e la conferma dell'indirizzo.
    • I punti di riferimento possono contenere entrambi i tag se sono sia visibili localmente sia immediatamente adiacenti.

Ogni punto di riferimento contiene i seguenti campi:

  • place è l'oggetto PlaceView che rappresenta questo punto di riferimento.
  • relationalDescription è una descrizione leggibile dall'uomo di come la destinazione si riferisce al punto di riferimento, ad esempio "Vicino all'Empire State Building" o "Di fronte alla Casa Bianca".
  • tags[] è un array di tag che descrivono come il punto di riferimento può essere utilizzato nel contesto della destinazione:
    • "ADDRESS": un luogo di rilievo locale che può essere utilizzato per identificare la posizione generica della destinazione.
    • "ARRIVAL": un luogo che può essere utilizzato per raggiungere la destinazione, utile per la navigazione una volta che ci si trova nelle vicinanze.
  • straightLineDistanceMeters è la distanza in linea retta da questo punto di riferimento alla destinazione in metri.
  • travelDistanceMeters è la distanza a piedi in metri da questo punto di riferimento alla destinazione.

arrivalSummary

Insight basati sull'AI per facilitare l'arrivo. Visualizza i riepiloghi basati sull'AI.

parkingOptions

Informazioni dettagliate sul parcheggio.

Formato della risposta

SearchDestinations restituisce un SearchDestinationsResponse nel seguente formato JSON:

{
  "destinations": [
    {
      "primary": {
        "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w",
        "displayName": {
          "text": "Arby's",
          "languageCode": "en"
        },
        "primaryType": "fast_food_restaurant",
        "types": [
          "fast_food_restaurant",
          "sandwich_shop",
          "deli",
          "meal_takeaway",
          "food_delivery",
          "american_restaurant",
          "restaurant",
          "food_store",
          "store",
          "food",
          "point_of_interest",
          "establishment"
        ],
        "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA",
        "postalAddress": {
          "regionCode": "US",
          "languageCode": "en",
          "postalCode": "94087",
          "administrativeArea": "CA",
          "locality": "Sunnyvale",
          "addressLines": [
            "601 S Bernardo Ave"
          ]
        },
        "structureType": "BUILDING",
        "location": {
          "latitude": 37.3734545,
          "longitude": -122.05693269999998
        },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.056930138027,
                37.3735253692531
              ],
              [
                -122.056960139391,
                37.3735372663597
              ],
              [
                -122.056994129366,
                37.3734828786847
              ],
              [
                -122.056969677395,
                37.3734731161089
              ],
              [
                -122.057061762447,
                37.3733261309656
              ],
              [
                -122.056979388817,
                37.3732935577128
              ],
              [
                -122.056798860285,
                37.3735818838642
              ],
              [
                -122.056875858081,
                37.3736121235316
              ],
              [
                -122.056930138027,
                37.3735253692531
              ]
            ]
          ]
        }
      },
      "containingPlaces": [
        {
          "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw",
          "displayName": {
            "text": "Cherry Chase Shopping Center",
            "languageCode": "en"
          },
          "primaryType": "shopping_mall",
          "types": [
            "shopping_mall",
            "point_of_interest",
            "establishment"
          ],
          "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA",
          "postalAddress": {
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94087-1020",
            "administrativeArea": "CA",
            "locality": "Sunnyvale",
            "addressLines": [
              "663 S Bernardo Ave"
            ]
          },
          "structureType": "GROUNDS",
          "location": {
            "latitude": 37.3731231,
            "longitude": -122.0578211
          },
          "displayPolygon": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  -122.057112227103,
                  37.3714618008523
                ],
                [
                  -122.057076849821,
                  37.3715743611411
                ],
                [
                  -122.056963607756,
                  37.3719081793948
                ],
                [
                  -122.056865279559,
                  37.3722026053835
                ],
                [
                  -122.056687872374,
                  37.3727258358476
                ],
                [
                  -122.056580005889,
                  37.3730511370747
                ],
                [
                  -122.056498845827,
                  37.3732994782583
                ],
                [
                  -122.056338259713,
                  37.3737878663325
                ],
                [
                  -122.056618678291,
                  37.373887693582
                ],
                [
                  -122.056912102521,
                  37.3740010327191
                ],
                [
                  -122.057532418159,
                  37.3742476426462
                ],
                [
                  -122.057673926626,
                  37.3742441740031
                ],
                [
                  -122.057735663106,
                  37.3742328516943
                ],
                [
                  -122.057766531332,
                  37.3742220604378
                ],
                [
                  -122.057797572967,
                  37.37420520725
                ],
                [
                  -122.057828267759,
                  37.3741852342085
                ],
                [
                  -122.058060299297,
                  37.3740060842535
                ],
                [
                  -122.058199726081,
                  37.3737861673422
                ],
                [
                  -122.05836707267,
                  37.373524542556
                ],
                [
                  -122.058569622393,
                  37.3732018598683
                ],
                [
                  -122.0587638478,
                  37.3728890198039
                ],
                [
                  -122.058934661823,
                  37.3726036257774
                ],
                [
                  -122.059164956851,
                  37.3722498383629
                ],
                [
                  -122.058997784906,
                  37.3721804442035
                ],
                [
                  -122.057936479838,
                  37.3717605636234
                ],
                [
                  -122.057495827092,
                  37.3715860151634
                ],
                [
                  -122.057112227103,
                  37.3714618008523
                ]
              ]
            ]
          }
        }
      ],
      "landmarks": [
        {
          "place": {
            "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg",
            "displayName": {
              "text": "Chase Bank",
              "languageCode": "en"
            },
            "primaryType": "bank",
            "types": [
              "bank",
              "atm",
              "finance",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1234 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.373579,
              "longitude": -122.05752700000001
            }
          },
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 61.182193756103516,
          "travelDistanceMeters": 63.075645446777344
        },
        {
          "place": {
            "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "butcher_shop",
              "florist",
              "deli",
              "supermarket",
              "bakery",
              "food_delivery",
              "market",
              "manufacturer",
              "food_store",
              "store",
              "food",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "639 S Bernardo Ave"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3727912,
              "longitude": -122.0581172
            }
          },
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 158.65606689453125,
          "travelDistanceMeters": 131.1669921875
        },
        {
          "place": {
            "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk",
            "displayName": {
              "text": "Oil Changers",
              "languageCode": "en"
            },
            "types": [
              "car_repair",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1240 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743054,
              "longitude": -122.0584272
            }
          },
          "relationalDescription": {
            "text": "Down the road from Oil Changers",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL"
          ],
          "straightLineDistanceMeters": 140.52459716796875,
          "travelDistanceMeters": 143.24220275878906
        },
        {
          "place": {
            "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0",
            "displayName": {
              "text": "Apni Mandi Farmers Market Sunnyvale",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "cake_shop",
              "supermarket",
              "asian_grocery_store",
              "indian_restaurant",
              "meal_takeaway",
              "bakery",
              "manufacturer",
              "wholesaler",
              "restaurant",
              "food_store",
              "store",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1056",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1111 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3737199,
              "longitude": -122.0522958
            }
          },
          "relationalDescription": {
            "text": "Near Apni Mandi Farmers Market Sunnyvale",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 410.37435913085938,
          "travelDistanceMeters": 479.49893188476562
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "primaryType": "chicken_restaurant",
            "types": [
              "chicken_restaurant",
              "fast_food_restaurant",
              "restaurant",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1028",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1241 W El Camino Real"
              ]
            },
            "structureType": "BUILDING",
            "location": {
              "latitude": 37.3746764,
              "longitude": -122.05708860000001
            },
            "displayPolygon": {
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ],
              "type": "Polygon"
            }
          },
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 87.348007202148438,
          "travelDistanceMeters": 214.08084106445312
        }
      ],
      "entrances": [
        {
          "displayName": {
            "text": "South Bernardo Avenue",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.3735328,
            "longitude": -122.05694879999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4",
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "PARKING"
          ]
        }
      ]
    }
  ]
}

Parametri obbligatori

  • La richiesta API deve contenere uno dei seguenti tre parametri, che specifica l'indirizzo, il luogo o la località in cui cercare una destinazione:
    • addressQuery: l'indirizzo da cercare.
    • place: l'ID luogo del luogo da cercare.
    • locationQuery: le coordinate di latitudine e longitudine della località da cercare.

  • FieldMask

    Specifica l'elenco di campi da restituire nella risposta creando una maschera di campo della risposta. Passa la maschera di campo della risposta al metodo utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP X-Goog-FieldMask. Ad esempio, la richiesta seguente restituirà solo gli ingressi, i punti di navigazione e l'ID luogo della destinazione principale.

      curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
    -H "X-Goog-Api-Key: API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \
    https://geocode.googleapis.com/v4/geocode/destinations

    Non esiste un elenco predefinito di campi restituiti nella risposta. Se ometti la maschera di campo, il metodo restituisce un errore. Imposta la maschera di campo su * per restituire tutti i campi. Per maggiori dettagli, consulta Scegli i campi da restituire.

Parametri facoltativi

  • travelModes

    Specifica i tipi di navigationPoints da restituire. I punti di navigazione per altre modalità di viaggio verranno filtrati. Se travelModes non è impostato, possono essere restituiti i punti di navigazione di tutte le modalità di viaggio.

  • languageCode

    La lingua in cui restituire i risultati.

    • Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
    • Se languageCode non viene fornito, l'API utilizza per impostazione predefinita la lingua e lo script locali della località. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
    • L'API fa del suo meglio per fornire un indirizzo leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un alfabeto leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti nella stessa lingua, che viene scelta dal primo componente.
    • Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.
    • La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra.

  • regionCode

    Il codice regione come valore del codice CLDR di due caratteri. Non esiste un valore predefinito. La maggior parte dei codici CLDR è identica ai codici ISO 3166-1.

    Quando esegui la geocodifica di un indirizzo, ovvero la geocodifica diretta, questo parametro può influenzare, ma non limitare completamente, i risultati del servizio alla regione specificata. Quando esegui la geocodifica di una località o di un luogo, la geocodifica inversa o la geocodifica dei luoghi, questo parametro può essere utilizzato per formattare l'indirizzo. In tutti i casi, questo parametro può influire sui risultati in base alla legge vigente.

  • placeFilter

    Consente di filtrare i risultati di una ricerca locationQuery per soddisfare i tuoi requisiti, ad esempio restituendo solo destinazioni che sono edifici o solo destinazioni con indirizzi chiari.

    Filtra per granularità strutturale

    Il filtro structureType consente di specificare il tipo di strutture restituite dalla query:

    • Isolamento degli edifici: utilizza "structureType": "BUILDING" per mostrare i contorni degli edifici su una mappa o per ottenere dettagli su una struttura specifica.
    • Informazioni sui complessi: utilizza "structureType": "GROUNDS" per assicurarti che il risultato principale sia l'area complessiva. Questa opzione è utile quando si eseguono query per aree più grandi, come campus universitari o centri commerciali.
    • Concentrati su unità/sezioni: utilizza "structureType": "SECTION" per identificare le sezioni all'interno di un edificio.

    Assicurati che gli indirizzi siano utili

    Non tutti i luoghi hanno indirizzi stradali chiari. Il filtro addressability ti aiuta a controllare la qualità degli indirizzi nei risultati:

    • Richiedi un indirizzo principale chiaro: per assicurarti che il risultato della destinazione principale abbia sempre un indirizzo o un nome a livello di strada, utilizza "addressability": "PRIMARY". Questo è utile per scopi di navigazione o visualizzazione in cui un indirizzo chiaro è fondamentale.
    • Consenti indirizzi nelle destinazioni secondarie: nei casi in cui il luogo principale potrebbe non avere un indirizzo, ma le unità al suo interno sì (ad esempio gli appartamenti in un edificio), "addressability": "WEAK" garantisce che almeno il luogo principale o una delle sue destinazioni secondarie abbia un indirizzo.
    • Qualsiasi risultato: se la presenza dell'indirizzo non è pertinente al tuo caso d'uso, utilizza "addressability": "ANY". Questa opzione è vivamente consigliata quando hai bisogno solo di attributi geometrici come i contorni degli edifici e i punti di navigazione, in quanto migliora l'accuratezza di questi risultati.
    Esempio: filtro per edifici indirizzabili 
    curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "PRIMARY"
    }
  },
  "languageCode": "en"
}' \\
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\
-H "X-Goog-FieldMask: place" \\
https://geocode.googleapis.com/v4/geocode/destinations