場所の写真

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

プレイスフォト サービスは、Places API の一部であり、質の高い写真コンテンツをアプリケーションに追加できる読み取り専用の API です。プレイスフォト サービスを使えば、プレイス データベースに保存されている数百万の写真を利用できます。Place Details リクエストを使って場所の情報を検索すると、関連する写真コンテンツに対する写真のリファレンスが返されます。Find Place、Nearby Search、Text Search のリクエストでも、関連する写真コンテンツがあれば、プレイスごとに 1 つの写真のリファレンスが返されます。フォトサービスでは、参照された写真にアクセスできるだけでなく、アプリケーションに最適なサイズに合わせて画像のサイズを変更できます。

プレイス フォト リクエスト

プレイスフォト リクエストは、次の形式の HTTP URL です。

https://maps.googleapis.com/maps/api/place/photo?parameters

検索リクエストを開始するには、必須のパラメータがいくつかあります。URL の標準規則と同様に、すべてのパラメータはアンパサンド（&）文字を使用して区切ります。各パラメータと有効な値のリストを次に示します。

Required parameters

  • photo_reference

    A string identifier that uniquely identifies a photo. Photo references are returned from either a Place Search or Place Details request.

  • maxheight or maxwidth

    maxheight specifies the maximum desired height, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.

    maxwidth specifies the maximum desired width, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.

    Both the maxheight and maxwidth properties accept an integer between 1 and 1600.

    You must specify either maxheight, or maxwidth, or both.

写真のリファレンス

プレイスフォト サービスでは、プレイス検索リクエスト、周辺検索リクエスト、テキスト検索リクエスト、プレイス詳細リクエストへのレスポンスで返される photo_reference を、すべてのリクエストに含める必要があります。該当プレイスに関連する写真コンテンツがある場合は、どのリクエストへのレスポンスにも photos[] フィールドが含まれます。

注: 返される写真の数はリクエストによって異なります。

  • Find Place、Nearby Search、Text Search のリクエストでは、配列に 1 つのみ photo 要素が返されます。
  • プレイス詳細リクエストでは、最大 10 個の photo 要素が返されます。

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

  • photo_reference - フォト リクエストを実行する際に写真を識別するための文字列です。
  • height - 画像の最大高さ。
  • width - 画像の最大幅。
  • html_attributions[] - 必要な属性情報が含まれます。このフィールドは常に存在しますが、値が空の場合もあります。

フォトサービスによって返される写真の提供元は、お店やサービスの所有者、ユーザーの投稿などさまざまです。こういった写真は、帰属情報なしで使用できる場合や、必要な帰属情報が画像内にあらかじめ記載されている場合がほとんどです。ただし、返された photo 要素の html_attributions フィールドに値が含まれる場合は、アプリケーション内でその画像を表示するすべての箇所で、追加の帰属情報として組み込む必要があります。

次の例は、Place Details リクエストを示しています。

curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"

レスポンスの photos[] 配列の例を次に示します。

...
"photos" : [
   {
      "html_attributions" : [],
      "height" : 853,
      "width" : 1280,
      "photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
   }
...

Place Photo の例

リクエストの例を以下に示します。このリクエストでは、幅が 400 ピクセル以下になるようにサイズ変更されて、参照された画像が返されます。

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q&key=YOUR_API_KEY

プレイスフォト レスポンス

プレイスフォト リクエストが成功すると、レスポンスとして画像が返されます。画像のタイプは、送信された元の写真のタイプに依存します。

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

割り当て超過のイメージ

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

  • 送信された写真のリファレンスが正しく指定されていない。
  • リクエストに maxwidth パラメータまたは maxheight パラメータが含まれていない。
  • maxwidth パラメータまたは maxheight パラメータの値が null に設定されています。
  • photo_reference の有効期限が切れています。photo_reference が期限切れになった場合は、Place Details、Find Place、Nearby Search、Text Search にリクエストを送信して、更新された photo_reference 値を取得します。