Eseguire la migrazione dalle funzionalità v3 all'endpoint SearchDestinations

Sviluppatori dello Spazio economico europeo (SEE)

Le seguenti funzionalità dell'API Geocoding v3 vengono sostituite dall'endpoint SearchDestinations dell'API Geocoding v4:

  • Entrate
  • Punti di navigazione
  • Contorni degli edifici
  • Terreni

Se utilizzavi l'API Geocoding v3 per le funzionalità sopra indicate, utilizza questo documento per utilizzare invece l'endpoint SearchDestinations e ottenere queste funzionalità. Questo documento spiega in quale punto della risposta dell'API SearchDestinations trovare queste funzionalità e le differenze nel modo in cui queste funzionalità sono rappresentate nelle risposte dell'API tra l'API Geocoding v3 e l'endpoint SearchDestinations dell'API Geocoding v4.

Entrate

Per ottenere gli ingressi associati a un destination, utilizza il campo destination.entrances.

Tieni presente che il formato di un entrance è leggermente diverso dal formato dell'ingresso nell'API Geocoding v3. Ogni ingresso in destination.entrances ha i seguenti campi:

  • displayName: questo è un nuovo campo facoltativo che conterrà un nome leggibile per l'ingresso, ad esempio "Cancello B".
  • location: si tratta di una località di tipo LatLng, che è diverso dal formato utilizzato nell'API Geocoding v3.
  • tags: è uguale al campo tags degli ingressi dell'API Geocoding v3.
  • place: analogo al campo buildingPlaceId degli ingressi dell'API Geocoding v3. Tuttavia, l'ID luogo in questo campo potrebbe essere per un luogo di qualsiasi tipo, non necessariamente solo un edificio.

Per ottenere i punti di navigazione associati a un destination, utilizza il campo destination.navigationPoints.

Tieni presente che il formato di un navigationPoint è leggermente diverso dal formato del punto di navigazione nell'API Geocoding v3. Ogni punto di navigazione in destination.navigationPoints ha i seguenti campi:

  • displayName: questo è un nuovo campo facoltativo che avrà un nome leggibile per il punto di navigazione, ad esempio "5th Ave".
  • location: si tratta di una località di tipo LatLng, che è diverso dal formato utilizzato nell'API Geocoding v3.
  • travelModes: questo campo è simile a restrictedTravelModes dei punti di navigazione dell'API Geocoding v3. I valori enum possibili sono gli stessi, l'unica differenza è che questo campo ora rappresenta le modalità di viaggio accettabili per il punto di navigazione, anziché quelle con limitazioni.
  • usage: questo è un nuovo campo che contiene i casi d'uso supportati dal punto di navigazione. Tieni presente che la maggior parte dei punti di navigazione avrà un utilizzo di UNKNOWN, ma ciò non significa necessariamente che l'utilizzo del punto di navigazione sia limitato in alcun modo.

Contorni degli edifici

Per ottenere i contorni degli edifici associati a un destination, devi utilizzare il campo displayPolygon degli oggetti placeView nel destination che rappresentano gli edifici. Per ogni placeView, puoi verificare se si tratta di un edificio con il campo placeView.structureType. Se il tipo di struttura è BUILDING, puoi ottenere la struttura dal campo placeView.displayPolygon. placeView avrà anche campi aggiuntivi per l'edificio che non erano presenti nell'API Geocoding v3.

Un destination può avere un oggetto placeView che rappresenta un edificio nei seguenti campi:

  • destination.primary: questo è il luogo principale per la destinazione.
  • destination.containingPlaces: si tratta di un campo ripetuto che può contenere luoghi più grandi che "contengono" il luogo principale. Ad esempio, se il luogo principale è un subpremise, containingPlaces di solito contiene placeView che rappresenta l'edificio.
  • destination.subDestinations: si tratta di un campo ripetuto che può contenere le destinazioni secondarie del luogo principale. Ad esempio, singole unità di un edificio. Questo campo in genere non contiene un placeView che rappresenta un edificio.

Si noti che il formato di placeView.displayPolygon corrisponde al formato del contorno dell'edificio nella Geocoding API v3, ovvero il formato GeoJSON, utilizzando il formato RFC 7946.

Terreni

Analogamente alla creazione di strutture, per ottenere i motivi associati a un destination, devi utilizzare il campo displayPolygon degli oggetti placeView in destination che rappresentano i motivi. Per ogni placeView, puoi verificare se si tratta di un motivo con il campo placeView.structureType. Se il tipo di struttura è GROUNDS, puoi ottenere la struttura dal campo placeView.displayPolygon. placeView avrà anche campi aggiuntivi per i motivi che non erano presenti nell'API Geocoding v3.

Un destination può avere un oggetto placeView che rappresenta un motivo nei seguenti campi:

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

Tieni presente che il formato di placeView.displayPolygon corrisponde al formato del contorno del terreno nell'API Geocoding v3, che è il formato GeoJSON, utilizzando il formato RFC 7946.

Utilizza una maschera di campo per richiedere queste funzionalità

L'endpoint SearchDestinations richiede una maschera di campo, come spiegato in Scegliere i campi da restituire. La maschera del campo può essere impostata su * per restituire tutti i campi oppure puoi impostarla sui campi specifici che vuoi ricevere. Ad esempio, la seguente richiesta API imposta la maschera di campo per ricevere tutti i campi necessari per ottenere gli ingressi, i punti di navigazione, i contorni degli edifici e i terreni di una destinazione:

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,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations