場所の写真（新規）

プラットフォームを選択: Android iOS ウェブサービス
欧州経済領域（EEA）のデベロッパー

はじめに

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

Place Details（新版）、Nearby Search（新版）、またはテキスト検索（新版）のリクエストを使用して場所の情報を取得する際に、関連する写真コンテンツの写真リソースをリクエストすることもできます。Place Photos (New) を使用すると、参照された写真にアクセスできるだけでなく、そうした画像をアプリケーションに最適なサイズに変更できます。

API Explorer を使用すると、ライブ リクエストを行って、API と API オプションを理解できます。

Place Photos（新規）リクエスト

Place Photos（New）リクエストは、次の形式の 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 ～ 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 以外のリクエストでは無視されます。

写真の名前を取得する

Place Photos（新版）に対するすべてのリクエストには、Nearby Search（新版）、テキスト検索（新版）、または Place Details（新版）リクエストに対するレスポンスで返される写真リソース名を含める必要があります。これらのリクエストに対するレスポンスには、場所に関連する写真コンテンツがある場合、photos[] 配列が含まれます。

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

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

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx - 画像の高さの最大値（ピクセル単位）。
  • widthPx - 画像の最大幅（ピクセル単位）。
  • authorAttributions[] - 必要な帰属表示。このフィールドは常に存在しますが、空の場合があります。

Place Photo (New) によって返される写真の提供元は、お店やサービスの所有者、ユーザーの投稿などさまざまです。こういった写真は、帰属情報なしで使用できる場合や、必要な帰属情報が画像内にあらかじめ記載されている場合がほとんどです。ただし、返された 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/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

Place Photos (New) リクエストが成功した場合のレスポンスは画像です。

エラーコード

Place Photos（新版）リクエストは、次のエラーコードを返すことがあります。

割り当てを超過しました（403）

リクエストが使用可能な割り当てを超えると、サーバーは HTTP 403 ステータスを返し、次の画像を表示して割り当てを超過したことを示します。

割り当て超過の通知

無効なリクエスト（404）

サーバーがリクエストを理解できない場合、無効なリクエストを示す HTTP 400 ステータスが返されます。無効なリクエストの最も一般的な理由は次のとおりです。

  • 送信された写真の名前が正しく指定されていませんでした。
  • リクエストに maxHeightPx パラメータまたは maxWidthPx パラメータが含まれていませんでした。
  • maxHeightPx パラメータまたは maxWidthtPx パラメータの値が null に設定されました。
  • name の有効期限が切れています。name が期限切れになった場合は、Place Details（新版）、Nearby Search（新版）、またはテキスト検索（新版）にリクエストを送信して、新しい name を取得します。

リクエストが多すぎます（429）

Google は、写真をオンデマンドで読み込むことをおすすめします。ある場所のすべての画像を一度に表示しようとすると、サーバーから HTTP 429 ステータスが返されることがあります。これは、同時に読み込む写真が多すぎることを示しています。このエラー メッセージが表示された場合は、サポートに連絡して割り当ての増加をリクエストします。

試してみよう:

API Explorer を使用すると、サンプル リクエストを作成して、API と API オプションについて理解を深めることができます。

リクエストを行うには:

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

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