ジオコーディング リクエストを行う際に、フィールド マスクを使用して、レスポンスで返すフィールドのリストを指定できます。フィールド マスクを使用すると、不要なデータをリクエストしないようにすることで、レスポンスのレイテンシを短縮できます。
基本的なジオコーディング メソッド（住所をジオコーディングする、場所をジオコーディングする、プレイスをジオコーディングする）の場合、フィールド マスクの指定が必要な目的地の検索とは異なり、レスポンス オブジェクトのすべてのフィールドがデフォルトで返されます。基本的なメソッドではフィールド マスクは必須ではありませんが、レスポンスのレイテンシを短縮するために使用することを強くおすすめします。
レスポンス フィールド マスクを定義する
レスポンス フィールド マスクは、スペースなしのカンマ区切りのリストのパスです。各パスは、レスポンス オブジェクトの一意のフィールドを指定します。パスは、最上位のレスポンス フィールドから始まり、指定されたフィールドへのドット区切りのパスを使用します。
レスポンス フィールド マスクをリクエストに渡すには、URL パラメータ $fields または fields を使用するか、HTTP または gRPC ヘッダー X-Goog-FieldMask を使用します。
フィールド マスクの例
以下は、フォワード ジオコーディング リクエストに対する完全なレスポンスです。
{ "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", ... }
レスポンス フィールドの階層を使用して、次の形式でフィールド マスクを作成します。
topLevelField[.secondLevelField][.thirdLevelField][...]
宛先フィールド マスクを検索する
SearchDestinations を呼び出すときに、必要な目的地の属性（Place Details、入り口、ナビゲーション ポイント、建物の輪郭（displayPolygon）、ランドマークなど）を正確に指定します。
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
コア ジオコーディングのフィールド マスク
たとえば、GeocodeAddress レスポンスで placeId フィールドのみを返すには、次のフィールド マスクを使用します。
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
レスポンスは次のようになります。
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE" } ] }
viewport フィールドを返すには、フィールド マスクを次のようにします。
-H 'X-Goog-FieldMask: results.viewport'
レスポンスは次のようになります。
{ "results": [ { "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
両方を返品する場合:
-H 'X-Goog-FieldMask: results.placeId,results.viewport'
レスポンスは次のようになります。
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
gRPC フィールド マスク
gRPC の場合は、レスポンス フィールド マスクを含む変数を設定します。その後、その変数をリクエストに渡すことができます。
const ( fieldMask = "results.placeId,results.viewport" )
フィールドパスに関する考慮事項
必要なフィールドのみを返すには、レスポンスに必要なフィールドのみを含めます。
- 処理時間を短縮して、結果がより短いレイテンシで返されるようにします。
- 安定したレイテンシ パフォーマンスを確保する。すべてのフィールドを選択した場合、または最上位レベルですべてのフィールドを選択した場合、新しいフィールドが追加されてレスポンスに自動的に含まれると、パフォーマンスが低下する可能性があります。
- レスポンス サイズが小さくなり、ネットワーク スループットが向上します。
フィールド マスクの作成方法の詳細については、field_mask.proto をご覧ください。