Cercare destinazioni

Sviluppatori dello Spazio economico europeo (SEE)

Una Destination si riferisce a una posizione o un luogo specifico che un utente intende raggiungere o verso cui intende 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, San Francisco"
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 "Consegna del caricabatterie"
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 City"
"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

o 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.

Cercare 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 Cerca destinazioni funziona meglio con gli ID luogo che rappresentano destinazioni specifiche e raggiungibili. 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à discrete, come quelli dedotti da intervalli di indirizzi (ad esempio "10-20 Main St"), sezioni di un percorso senza un numero specifico o plus code non sono supportati. Gli ID luogo per i risultati che coprono un'area troppo grande (ad esempio "Oceano Pacifico") non sono supportati.

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 il completamento automatico (nuovo), 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 completamento automatico (nuovo).

Cercare 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 da utilizzare 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 della ricerca delle destinazioni

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

Gli oggetti PlaceView all'interno della risposta Cerca destinazioni (ad esempio 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 stringa per types e primaryType sono tratti dalla tabella A e dalla tabella B nella pagina Tipi di luogo (nuovo).

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 componenti separati applicabili a questo indirizzo.

Ogni componente dell'indirizzo in genere contiene 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 di "Alaska" e un shortText di "AK" utilizzando l'abbreviazione postale di due lettere.
  • languageCode è la lingua utilizzata per formattare questo componente, nella notazione CLDR.

containingPlaces

Entità più grandi di cui fa parte la destinazione principale (ad esempio, un centro commerciale che contiene un negozio).

subDestinations

Località più specifiche all'interno della destinazione principale (ad esempio, appartamenti in un edificio).

entrances

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

  • 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 a striscia, gli ingressi "PREFERRED" saranno quelli che conducono al ristorante stesso, mentre gli altri ingressi restituiti saranno altri ingressi dell'edificio, ad esempio ingressi di altri ristoranti nel centro commerciale a striscia.

    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 principale dell'atrio, 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 che rappresenta 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 un 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 il routing e l'esperienza fluviale nella tua app. Per maggiori informazioni, consulta Percorso con token punto 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 sosta ideale per la navigazione da e verso un luogo. Il punto è intenzionalmente leggermente spostato rispetto alla linea centrale della strada per indicare chiaramente il lato della strada in cui si trova il luogo.
  • travelModes è un elenco di modalità di trasporto 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 auto principale.

  • altitude_meters contiene l'altitudine del punto di navigazione in metri rispetto all'ellissoide WGS-84. Nei casi in cui sono presenti tratti di strada sovrapposti verticalmente, utilizza il campo altitude_meters per scegliere il tratto di strada migliore per la navigazione del sistema.

landmarks

Luoghi nelle vicinanze di interesse per aiutare gli utenti a comprendere i dintorni della destinazione.

Ogni punto di riferimento contiene i seguenti campi:

  • place è l'oggetto PlaceView che rappresenta questo punto di riferimento.
  • relationalDescription è una descrizione leggibile da una persona del rapporto tra la destinazione e il 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 spicco a livello locale che può essere utilizzato per identificare la posizione generale 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

Approfondimenti basati sull'AI per assistere all'arrivo. Consulta la sezione Riepiloghi basati sull'AI.

parkingOptions

Informazioni dettagliate sul parcheggio.

Formato della risposta

SearchDestinations restituisce un SearchDestinationsResponse del 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": [
        {
          "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 dei campi da restituire nella risposta creando una maschera del campo di 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 del 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, quindi 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 stradali nella lingua locale, traslitterati in un sistema di scrittura 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 geocodifichi un indirizzo, 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 le destinazioni che sono edifici o solo quelle 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.
    • Comprendere i complessi: utilizza "structureType": "GROUNDS" per assicurarti che il risultato principale sia il complesso nel suo insieme. Questa opzione è utile quando si eseguono query per aree più ampie, come campus universitari o centri commerciali.
    • Concentrati su unità/sezioni: utilizza "structureType": "SECTION" per identificare le sezioni all'interno di un edificio.

    Garantire indirizzi utili

    Non tutti i luoghi hanno indirizzi chiari a livello stradale. 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". È utile per la navigazione o la 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 di indirizzi non è pertinente al tuo caso d'uso, utilizza "addressability": "ANY". Questa opzione è 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