Quando effettui una richiesta di geocodifica, puoi utilizzare una maschera di campo per specificare l'elenco di campi da restituire nella risposta. Le maschere di campo aiutano a ridurre la latenza della risposta, garantendo che non vengano richiesti dati non necessari.
Per i metodi di geocodifica di base (Geocodifica un indirizzo, Geocodifica una località e Geocodifica di un luogo), per impostazione predefinita vengono restituiti tutti i campi dell'oggetto di risposta, a differenza di Cerca destinazioni, dove è necessario specificare una maschera di campo. Sebbene non sia richiesta una maschera di campo per i metodi di base, ti consigliamo vivamente di utilizzarne una per ridurre la latenza della risposta.
Definisci una maschera di campo della risposta
La maschera dei campi di risposta è un elenco di percorsi separati da virgole senza spazi, in cui ogni percorso specifica un campo univoco nell'oggetto di risposta. Il percorso inizia dal campo di risposta di primo livello e utilizza un percorso separato da punti per un campo specificato.
Passa la maschera di campo della risposta a una richiesta utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP o gRPC X-Goog-FieldMask.
Esempi di maschere di campo
Di seguito è riportata la risposta completa di una richiesta di geocodifica diretta:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE", "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "location": { "latitude": 37.422010799999995, "longitude": -122.08474779999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.420656719708511, "longitude": -122.08547523029148 }, "high": { "latitude": 37.4233546802915, "longitude": -122.0827772697085 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", ... }
Crea le maschere di campo utilizzando la gerarchia dei campi di risposta, nel formato:
topLevelField[.secondLevelField][.thirdLevelField][...]
Maschere di campo per le destinazioni di ricerca
Quando chiami SearchDestinations,
specifica gli attributi esatti della destinazione di cui hai bisogno, come i dettagli del luogo
principale, gli ingressi, i punti di navigazione, i contorni degli edifici (displayPolygon) e
i punti di riferimento:
curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations
Maschere di campo di geocodifica di base
Ad esempio, per restituire solo il campo placeId in una risposta GeocodeAddress, utilizza una maschera di campo:
curl -X GET -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: results.placeId' \ -H "X-Goog-Api-Key: API_KEY" \ https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
La risposta ora è:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE" } ] }
Per restituire il campo viewport, la maschera di campo è:
-H 'X-Goog-FieldMask: results.viewport'
La risposta ora è:
{ "results": [ { "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Per restituire entrambi:
-H 'X-Goog-FieldMask: results.placeId,results.viewport'
La risposta ora è:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Maschere di campo gRPC
Per gRPC, imposta una variabile contenente la maschera di campo della risposta. Puoi quindi passare la variabile alla richiesta.
const ( fieldMask = "results.placeId,results.viewport" )
Considerazioni sul percorso del campo
Includi nella risposta solo i campi che ti servono per restituire solo i campi di cui hai bisogno:
- Riduce i tempi di elaborazione, in modo che i risultati vengano restituiti con una latenza inferiore.
- Garantisce prestazioni di latenza stabili. Se selezioni tutti i campi o se selezioni tutti i campi al livello più alto, potresti riscontrare un peggioramento delle prestazioni quando vengono aggiunti nuovi campi che vengono poi inclusi automaticamente nella risposta.
- Risultati in una dimensione di risposta inferiore, che si traduce in un throughput di rete più elevato.
Per maggiori dettagli sulla creazione di una maschera di campo, consulta field_mask.proto.