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 の整数を受け入れます。
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
- フォト リクエストを実行する際の写真のリソース名を含む文字列。この文字列の形式は次のとおりです。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 オプションに慣れるためにサンプル リクエストを行うことができます。
リクエストを行うには:
- ページの右側にある API アイコン を選択します。
name
パラメータを以下のように設定します。places/PLACE_ID/photos/PHOTO_RESOURCE/media
- リクエストが JSON レスポンスを返すように、
skipHttpRedirect
をtrue
に設定します。デフォルトでは、リクエストは画像を返しますが、これは API Explorer では表示できません。 - [Execute] ボタンを選択します。ポップアップで、リクエストに使用するアカウントを選択します。
[API Explorer] パネルで展開アイコン を選択して、[API Explorer] ウィンドウを展開します。