場所の写真(新規)

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

Place Details、Nearby Search、Text Search のリクエストを使用して場所情報を取得する場合は、関連する写真コンテンツの写真リソースをリクエストすることもできます。フォトサービスを使用すると、参照されている写真にアクセスし、アプリケーションに最適なサイズに画像のサイズを変更できます。

API Explorer を使用すると、ライブ リクエストを行って、API と API オプションについての理解を深めることができます。

試してみる

Place Photo のリクエスト

Place Photo リクエストは、次の形式の URL に対する HTTP GET リクエストです。
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

次のパラメータは必須です。

  • NAME には、写真のリソース名が含まれます。
  • API_KEY には API キーが含まれます。
  • PARAMETERS には、maxHeightPx パラメータ、maxWidthPx パラメータ、またはその両方が含まれます。

必須パラメータと省略可能なパラメータの一覧については、下記をご覧ください。

必須パラメータ

写真の名前

写真を一意に識別する文字列 ID。写真名は、photos[] 配列の各要素の name プロパティで Place Details(新規)リクエスト、Nearby Search(新規)リクエスト、またはテキスト検索(新規)リクエストから返されます。

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

maxHeightPx と maxWidthPx

画像の高さと幅の最大値をピクセル単位で指定します。画像が指定された値より小さい場合は、元の画像が返されます。いずれかのサイズが大きい画像は、2 つのサイズのうち小さい方と一致するように拡大縮小され、元のアスペクト比に制限されます。maxheight プロパティと maxwidth プロパティはどちらも 1 ~ 4,800 の整数を受け入れます。

maxHeightPxmaxWidthPx のいずれか、または両方を指定する必要があります。

省略可能なパラメータ

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 - フォト リクエストを実行する際の写真のリソース名を含む文字列。この文字列の形式は次のとおりです。

    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

Place Photo リクエストが成功した場合のレスポンスは画像です。画像の種類は、送信された元の写真の種類によって異なります。

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

割り当て量オーバーの画像

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

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

試してみよう:

API Explorer では、API と API オプションに慣れるためにサンプル リクエストを行うことができます。

リクエストを行うには:

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