ジオコーディング リクエストを行う際に、フィールド マスクを使用して、レスポンスで返すフィールドのリストを指定できます。住所のジオコーディング、位置のジオコーディング、プレイス ジオコーディングのエンドポイントでは、レスポンス オブジェクトのすべてのフィールドがデフォルトで返されます。目的地を検索エンドポイントでは、API リクエストでフィールド マスクを指定する必要があります。
フィールド マスクを使用すると、不要なデータをリクエストしないようにできます。これにより、レスポンス レイテンシを短縮できます。
レスポンス フィールド マスクを定義する
レスポンス フィールド マスクは、スペースなしのパスのカンマ区切りのリストです。各パスは、レスポンス オブジェクトの一意のフィールドを指定します。パスは最上位のレスポンス フィールドから始まり、指定されたフィールドへのドット区切りのパスを使用します。
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][...]
たとえば、レスポンスで 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/v4beta/"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 をご覧ください。