ジオコーディング リクエストを行う場合は、フィールド マスクを使用して、レスポンスで返されるフィールドのリストを指定できます。 フィールド マスクを使用すると、不要なデータをリクエストしないようにすることで、レスポンスのレイテンシを短縮できます。
住所のジオコーディング、位置情報のジオコーディング、プレイス ジオコーディングの各メソッドでは、レスポンス オブジェクトのすべてのフィールドがデフォルトで返されます。フィールド マスクは必須ではありませんが、レスポンスのレイテンシを短縮するために使用することを強くおすすめします。
レスポンス フィールド マスクを定義する
レスポンス フィールド マスクは、スペースを含まないパスのカンマ区切りのリストです。各パスは、レスポンス オブジェクトの一意のフィールドを指定します。パスは最上位のレスポンス フィールドから始まり、ドット区切りのパスを使用して指定されたフィールドに移動します。
レスポンス フィールド マスクをリクエストに渡すには、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/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 をご覧ください。