Cercare destinazioni

Sviluppatori dello Spazio economico europeo (SEE)

Un Destination si riferisce a un punto di interesse significativo o a una posizione specifica che un utente intende raggiungere o verso cui intende navigare. Una Destination può includere informazioni come punti di navigazione, punti di riferimento, ingressi e contorni degli edifici.

L'endpoint 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 di destinazioni

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

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

Trasmetti tutti i parametri nel corpo della richiesta JSON o nelle intestazioni nell'ambito 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/v4beta/geocode/destinations

Puoi specificare la posizione in cui cercare una destinazione in tre modi:

  • Indirizzo
  • ID luogo
  • Coordinate di latitudine e longitudine

Cercare 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 un comportamento non specificato. Ecco alcuni esempi di query non supportate:

Tipo di query Esempio
Coordinate di latitudine e longitudine. Utilizza invece una query sulla località. "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 John Smith 123 Main Street"
"P.O. Box 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 "Ritiro del caricatore"
Nomi storici non più in uso "Middlesex Regno Unito"
Elementi o intenti non geospaziali "Quante barche ci sono nel porto di Ventura?"
Nomi non ufficiali o personalizzati "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/v4beta/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/v4beta/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/v4beta/geocode/destinations

ID luogo supportati

L'endpoint Cerca destinazioni 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 posizioni 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.

Per garantire la compatibilità quando utilizzi il completamento automatico di Places per trovare gli ID luogo, valuta la possibilità di filtrare i risultati per tipo. Puoi utilizzare il parametro includedPrimaryTypes nelle richieste Autocomplete per includere solo i tipi supportati elencati sopra:

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

In questo modo, gli ID luogo restituiti dal completamento automatico dei luoghi sono più compatibili con il metodo Search Destinations. Tieni presente che il tipo establishment è generico. Sebbene necessario per acquisire molte sedi aziendali, questo filtro può includere anche risultati di completamento automatico di Place per tipi di natural_feature, che hanno solo un supporto limitato in Destinazioni di ricerca.

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/v4beta/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 l'endpoint Destinations:

  • https://www.googleapis.com/auth/maps-platform.geocode — Utilizza con tutti gli endpoint dell'API Geocoding.

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

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

Risposta alla ricerca di destinazioni

La risposta di Search Destinations fornisce un contesto ricco e iperlocale sulla posizione.

Questa sezione descrive i campi di risposta chiave. Per tutti i dettagli su tutti i campi di risposta, consulta il riferimento API.

primary

Il luogo principale identificato dalla query nella richiesta.

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 descrivono 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 ingresso 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 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'atrio principale, ma se un ingresso fornisce l'accesso solo a un negozio sul lato dell'edificio, non sarà un ingresso "PREFERRED".

structureType

Il tipo di struttura rappresentato da questo luogo.

  • POINT

    Una posizione puntuale.

  • SECTION

    Una sezione 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. Nello specifico, 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 che contiene 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 di punti di navigazione.
  • location contiene il valore di latitudine e longitudine del punto di navigazione. Questa posizione sarà sempre molto vicina alla rete stradale e rappresenta un punto di partenza o di arrivo ideale per raggiungere 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 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 degli utilizzi supportati dal punto di navigazione. Gli utilizzi possono essere:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

arrivalSummary

Approfondimenti basati sull'AI per assisterti all'arrivo. Consulta Riassunti basati sull'AI.

landmarks

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

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

  • Nella richiesta API deve essere presente uno dei tre parametri seguenti, che specifica l'indirizzo, il luogo o la posizione 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 posizione da cercare.

  • FieldMask

    Specifica l'elenco dei campi da restituire nella risposta creando una maschera del campo di risposta. Passa la maschera del campo di risposta al metodo utilizzando il parametro URL $fields o fields oppure utilizzando l'intestazione HTTP X-Goog-FieldMask. Ad esempio, la richiesta riportata di seguito 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/v4beta/geocode/destinations

    Nella risposta non è presente un elenco predefinito di campi restituiti. Se ometti la maschera del campo, il metodo restituisce un errore. Imposta la maschera del campo su * per restituire tutti i campi. Per ulteriori dettagli, consulta Scegliere 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 en come valore predefinito. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
    • L'API fa del suo meglio per fornire un indirizzo stradale leggibile sia per l'utente sia per gli abitanti del luogo. 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. Tutti i componenti dell'indirizzo vengono restituiti nella stessa lingua, 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 CLDR di due caratteri. Non esiste un valore predefinito. La maggior parte dei codici CLDR sono identici ai codici ISO 3166-1.

    Quando esegui la geocodifica di 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 posizione o di un luogo, geocodifica inversa o geocodifica di un luogo, 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 le destinazioni con indirizzi chiari.

    Filtrare per granularità strutturale

    Il filtro structureType ti 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 ottenere dettagli su una struttura specifica.
    • Comprendere i complessi: utilizza "structureType": "GROUNDS" per assicurarti che il risultato principale sia l'area complessiva. Questa opzione è utile quando si esegue una query per aree più grandi, come campus universitari o centri commerciali.
    • Concentrandosi su unità/sezioni: utilizza "structureType": "SECTION" per identificare le sezioni all'interno di un edificio.

    Garantire indirizzi utili

    Non tutti i luoghi hanno indirizzi a livello stradale 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". È utile per la navigazione o la visualizzazione, in cui un indirizzo chiaro è fondamentale.
    • Consenti indirizzi nelle sottodestinazioni: 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" assicura che almeno il luogo principale o una delle sue sottodestinazioni abbia un indirizzo.
    • Qualsiasi risultato: se la presenza dell'indirizzo non è pertinente al tuo caso d'uso, utilizza "addressability": "ANY".
    Esempio: filtro per gli 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/v4beta/geocode/destinations

Feedback

Si tratta di un endpoint sperimentale dell'API Geocoding. Apprezziamo il tuo feedback all'indirizzo geocoding-feedback-channel@google.com.