Place Photo（新版）サービスは、高品質の写真コンテンツをアプリケーションに追加するための読み取り専用 API です。プレイスフォト サービスを使えば、プレイス データベースに保存されている数百万件の写真を利用できます。
Place Details、Nearby Search、Text Search のいずれかのリクエストで場所の情報を取得する場合は、関連する写真コンテンツ用の写真リソースもリクエストできます。フォトサービスでは、参照された写真にアクセスできるだけでなく、アプリケーションに最適なサイズに合わせて画像のサイズを変更できます。
API Explorer では、ライブ リクエストを実行して、API と API オプションを把握できます。
試してみるプレイス フォト リクエスト
プレイスフォト リクエストは、次の形式の URL に対する HTTP GET リクエストです。https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS
ここで、次のパラメータが必要です。
- NAME には写真のリソース名が含まれます。
- API_KEY には API キーが含まれます。
- PARAMETERS には、
maxHeightPxパラメータ、maxWidthPxパラメータ、またはその両方が含まれます。
必須パラメータとオプション パラメータの一覧を以下に示します。
必須パラメータ
写真の名前
写真を一意に識別する文字列 ID です。写真名は、Place Details（新版）、Nearby Search（新版）、Text Search（新版） リクエストの photos[] 配列の各要素の name プロパティで返されます。
例については、写真の名前を取得するをご覧ください。
maxHeightPx と maxWidthPx
画像の高さと幅の最大値をピクセル単位で指定します。画像が指定された値よりも小さい場合は、元の画像が返されます。画像の高さまたは幅が大きい場合は、元のアスペクト比に合わせて高さまたは幅のどちらか小さい方と一致するように縮小されます。maxheight プロパティと maxwidth プロパティのどちらも、1 ～ 4800 の整数を取ります。
maxHeightPx、maxWidthPx、またはその両方を指定する必要があります。
オプション パラメータ
skipHttpRedirect
false（デフォルト）の場合、画像に HTTP リダイレクトを行い、画像を返します。true の場合、リダイレクトをスキップして、画像の詳細を含む JSON レスポンスを返します。例:
{ "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media", "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo" }
このオプションは、HTTP 以外のリクエストでは無視されます。
写真の名前を取得する
プレイスフォト サービスでは、周辺検索リクエスト、テキスト検索リクエスト、プレイス詳細リクエストへのレスポンスで返される写真リソース名を、すべてのリクエストに含める必要があります。該当プレイスに関連する写真コンテンツがある場合は、どのリクエストへのレスポンスにも photos[] 配列が含まれます。
photo[] の各要素には、次のフィールドが含まれています。
name- フォト リクエストを実行する際に写真のリソース名を含む文字列。この文字列の形式は次のとおりです。places/PLACE_ID/photos/PHOTO_RESOURCE
heightPx- 画像の最大高さ（ピクセル単位）。widthPx- 画像の最大幅（ピクセル単位）。authorAttributions[]- 必要な帰属表示。このフィールドは常に存在しますが、空の場合があります。
フォトサービスによって返される写真の提供元は、お店やサービスの所有者、ユーザーの投稿などさまざまです。こういった写真は、帰属情報なしで使用できる場合や、必要な帰属情報が画像内にあらかじめ記載されている場合がほとんどです。ただし、返された photo 要素の authorAttributions フィールドに値が含まれる場合は、アプリケーション内でその画像を表示するすべての箇所で、追加の帰属情報として組み込む必要があります。
次の例は、フィールドマスクに photos を含めて、レスポンスに photos[] 配列が含まれるようにした Place Details リクエストを示しています。
curl -X GET \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,photos" \ https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
photos[] 配列の例を次に示します。
... "photos" : [ { "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1", "widthPx": 6000, "heightPx": 4000, "authorAttributions": [ { "displayName": "John Smith", "uri": "//maps.google.com/maps/contrib/101563", "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo" } ] }, ...
場所の写真をリクエストする
以下のリクエスト例では、リソース name を使用して画像を返し、縦と横が 400 ピクセル以下になるようにサイズを変更します。
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY
プレイスフォト リクエストが成功すると、レスポンスとして画像が返されます。画像のタイプは、送信された元の写真のタイプに依存します。
リクエストが利用可能な割り当て量を超えると、サーバーは HTTP 403 ステータス コードを返し、割り当て量を超えたことを示す次の画像が表示されます。
サーバーがリクエストを認識できない場合、HTTP 400 ステータス コードを返します。これは、リクエストが無効であることを示します。無効なリクエストの最も一般的な理由は次のとおりです。
- 送信された写真の名前が正しく指定されていません。
- リクエストに
maxHeightPxパラメータまたはmaxWidthPxパラメータが含まれていない。 maxHeightPxパラメータまたはmaxWidthtPxパラメータの値がnullに設定されています。nameの有効期限が切れています。nameが期限切れになった場合は、Place Details（新版）、Nearby Search（新版）、Text Search（新版） にリクエストして、新しいnameを取得します。
試してみよう:
API Explorer では、サンプル リクエストを実行して、API と API オプションを把握できます。
リクエストを行うには:
- ページの右側にある API アイコン
を選択します。 nameパラメータを次のように設定します。places/PLACE_ID/photos/PHOTO_RESOURCE/media- リクエストが JSON レスポンスを返すように、
skipHttpRedirectをtrueに設定します。デフォルトでは、リクエストは画像を返します。この画像は API Explorer で表示できません。 - [Execute] ボタンを選択します。ポップアップで、リクエストに使用するアカウントを選択します。
[API Explorer] パネルで展開アイコン
を選択して、[API Explorer] ウィンドウを展開します。