場所の写真（新規）

プラットフォームを選択: Android iOS ウェブサービス

Place Photo (New) サービスは、高品質の写真コンテンツをアプリに追加できる読み取り専用 API です。Place Photo サービスを使用すると、プレイス データベースに保存されている数百万の写真にアクセスできます。

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 パラメータ、またはその両方が含まれます。

必須パラメータと省略可能なパラメータの一覧を以下に示します。

必須パラメータ

写真名

写真を一意に識別する文字列識別子。写真名は、Place Details（新版）、Nearby Search（新版）、Text Search（新版） リクエストから、photos[] 配列の各要素の name プロパティで返されます。

例については、写真の名前を取得するをご覧ください。

maxHeightPx と maxWidthPx

画像の最大高さと幅をピクセル単位で指定します。画像が指定された値より小さい場合は、元の画像が返されます。画像のいずれかのサイズが指定されたサイズより大きい場合は、元のアスペクト比に制限され、2 つのサイズのうち小さい方に合わせて画像がスケーリングされます。maxheight プロパティと maxwidth プロパティの両方には、1 ～ 4,800 の整数を指定できます。

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 以外のリクエストでは無視されます。

写真の名前を取得する

Place Photo サービスへのすべてのリクエストには、Nearby Search、Text Search、または Place Details リクエストのレスポンスで返される写真リソース名を含める必要があります。場所に関連する写真コンテンツがある場合、これらのリクエストのレスポンスには photos[] 配列が含まれます。

photo[] の各要素には、次のフィールドが含まれています。

  • name - Photo リクエストを実行したときの写真のリソース名を含む文字列。この文字列の形式は次のとおりです。

    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 オプションを把握できます。

リクエストを行うには:

  1. ページの右側にある API アイコン api を選択します。
  2. name パラメータを次のように設定します。 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. リクエストが JSON レスポンスを返すように、skipHttpRedirect を true に設定します。デフォルトでは、リクエストは画像を返します。この画像は API Explorer で表示できません。
  4. [Execute] ボタンを選択します。ポップアップで、リクエストに使用するアカウントを選択します。

  5. API Explorer パネルで、全画面表示アイコン fullscreen を選択して API Explorer ウィンドウを開きます。