Quando effettui una richiesta di geocodifica, puoi utilizzare una maschera di campo per specificare l'elenco dei campi da restituire nella risposta. Le maschere di campo contribuiscono alla latenza della risposta assicurandoti di non richiedere dati non necessari.
Per i metodi Geocode an address, Geocode a location e Place geocoding, tutti i campi nell'oggetto della risposta vengono restituiti per impostazione predefinita. Sebbene una maschera di campo non sia obbligatoria, ti consigliamo vivamente di utilizzarla per ridurre la latenza della risposta.
Definire una maschera di campo della risposta
La maschera di campo della risposta è un elenco di percorsi separati da virgole senza spazi, in cui ogni percorso specifica un campo univoco nell'oggetto della risposta. Il percorso inizia dal campo della risposta di primo livello e utilizza un percorso separato da punti a un campo specificato.
Passa la maschera di campo della risposta a una richiesta utilizzando il parametro URL $fields
o fields oppure utilizzando l'intestazione HTTP o gRPC X-Goog-FieldMask.
Esempi di maschere di campo
Di seguito è riportata la risposta completa a 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", ... }
Costruisci le maschere di campo utilizzando la gerarchia dei campi della risposta, nel formato:
topLevelField[.secondLevelField][.thirdLevelField][...]
Ad esempio, per restituire solo il campo placeId nella risposta, utilizza una maschera di campo di:
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 questa variabile alla richiesta.
const ( fieldMask = "results.placeId,results.viewport" )
Considerazioni sul percorso del campo
Includi solo i campi necessari nella risposta per restituire solo i campi di cui hai bisogno:
- Riduce i tempi di elaborazione, quindi i risultati vengono restituiti con una latenza inferiore.
- Garantisce prestazioni di latenza stabili. Se selezioni tutti i campi o tutti i campi di primo livello, potresti riscontrare un peggioramento delle prestazioni quando vengono aggiunti nuovi campi e poi inclusi automaticamente nella risposta.
- Comporta una dimensione della risposta inferiore, che si traduce in una maggiore velocità di trasmissione della rete.
Per maggiori dettagli sulla creazione di una maschera di campo, consulta il field_mask.proto.