ページ1から開始
場所のfidとページ1を送信します。レコードはその場所のギャラリーが提供する順序に従います。
POST /api/v2/photos
1ページにつき1か所のギャラリー項目を最大20件取得します。ギャラリーに表示される順序で写真と動画のURLを取得できます。
完全な仕様については、APIドキュメントをご覧ください。
curl https://gmapscrawl.com/api/v2/photos \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: place-photos-page-1-example" \
-d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1}'例のfidを実際の場所のfeature IDに置き換えてください。レスポンスはシミュレートされたもので、example.comのメディアURLはプレースホルダーです。実行中のリクエストをリトライする際は、同じ冪等キーとボディを保持してください。
{
"photos": [
{
"photoUrl": "https://example.com/gallery-image.jpg"
},
{
"photoUrl": "https://example.com/gallery-preview.jpg",
"videoUrl": "https://example.com/gallery-video.mp4"
}
],
"next": false,
"total": 2,
"url": "https://www.google.com/maps/uv?pb=!1s0x89c259af336b3341:0xa4969e07ce3108de!15sCgIgAQ",
"params": {
"fid": "0x89c259af336b3341:0xa4969e07ce3108de",
"page": 1
}
}APIは同じレスポンス内でJSONを返します。タイムアウト後は、変更していないボディを同じIdempotency-Keyで再試行してください。テスト用認証情報では、実際の利用枠を消費せずにシミュレートされたデータが返ります。
場所から始める
feature IDを使って、1つの場所の画像・動画メタデータをリクエストします。
| フィールド | 意味 |
|---|---|
| fid · 必須 | Google Maps feature ID(例:0x89c259af336b3341:0xa4969e07ce3108de)。Search API結果のplace.dataIdまたはお持ちのfeature IDを使用します。 |
| page · デフォルト: 1 | 正の整数のページ番号。前のレスポンスでnext: trueの場合のみ増やしてください。 |
feature IDを確認するには、Google MapsスクレイパーAPIでビジネスを検索してください。data.businesses内の一致するエントリからplace.dataIdをコピーし、fidとして渡します。Place IDやビジネス名とは入力形式が異なります。
ギャラリーレコード
各項目には画像または動画プレビュー用のphotoUrlがあります。動画項目にはvideoUrlも含まれます。トップレベルのurlはその場所のギャラリーにリンクします。
| フィールド | 意味 |
|---|---|
| photoUrl | 利用可能な写真URL、または動画項目のプレビュー画像。 |
| videoUrl | 任意の動画URL。動画ソースを含む動画レコードに存在します。 |
| url | リクエストした場所のGoogle MapsギャラリーURL。 |
| next | 別の番号付きギャラリーページが利用可能かどうか。 |
| total | このレスポンスの件数(0〜20)。これは場所のギャラリー全体のサイズではありません。 |
| params | このレスポンスに使用された正規化されたfidとpage。 |
エンドポイントはこのページオブジェクトをJSONとして直接返します。トップレベルからphotosを読み取ってください。APIはメタデータとメディアリンクを返します。画像や動画の有無はソースに依存し、ギャラリー項目があってもダウンロード可能な動画があるとは限りません。
一度に1ページずつ
返されたnextフラグで、ワークフローにもう1リクエスト必要かを判断します。
場所のfidとページ1を送信します。レコードはその場所のギャラリーが提供する順序に従います。
totalはこのレスポンスで返されたギャラリー項目数を数えます。空のページも有効な結果です。レコードを分析に追加する前に利用可能なフィールドを確認してください。
nextがtrueの場合、pageを増やし、同じfidを維持してください。nextがfalseになったら、またはワークフローに十分なメディアレコードが集まったら停止します。
場所を視覚的に探索
選択したビジネスに関連するギャラリーを確認し、返されたレコードの横にソースのギャラリーリンクを保持します。
任意のvideoUrlフィールドを使って写真レコードと動画レコードを分け、独自の調査インターフェースで利用可能なプレビュー画像を表示します。
接続したエージェントにギャラリーメタデータの1ページを取得させ、さらなる確認用に利用可能なメディアリンクをリストアップさせます。
認証と使用量
scrapes:writeを許可するキーでAuthorization: Bearerを送信します。成功したライブページは、空のページを含めて1ページにつき1 APIリクエストユニットを消費します。RESTとMCPは同じAPI利用枠を使用します。テスト用認証情報をお持ちの場合、そのレスポンスはシミュレートされ、ライブ利用枠を消費しません。
最初のリクエストで任意のIdempotency-Keyを送信し、タイムアウトのリトライでは同一ボディとともに保持してください。処理のタイムアウトでユニットが予約されたままになる場合があります。エラーが試行の終了を報告する場合は、新しいキーで新しい試行を作成する前に、そのリトライガイダンスに従ってください。
各JSONレスポンスで、1つの場所につき最大20件の写真・動画メタデータレコードを返します。各レコードにはphotoUrlがあり、動画レコードにはvideoUrlも含まれる場合があります。トップレベルのurlはその場所のギャラリーにリンクします。
Search APIレスポンスで一致したビジネスのplace.dataIdを使い、fidとして送信します。既存のMaps feature IDを指定することもできます。追加のギャラリーページをリクエストする際も同じfidを送信してください。
このエンドポイントはJSONでメタデータとメディアURLを返します。アプリケーションで利用可能なリンクとギャラリーソースを確認できます。ソースの可用性がどのレコードやURLが返されるかを決定します。photoUrlは動画のプレビュー画像の場合があります。
ページ1から始めます。totalはそのレスポンス内のレコード数を数えます。nextがtrueの場合、同じfidと新しい冪等キーで次のページをリクエストします。nextがfalseになったら、またはワークフローに十分なレコードが集まったら停止します。
Photos APIはfidとpageを受け取ります。ソースが提供するギャラリー順で項目を返し、レビューのようなsort_byパラメータは提供していません。
はい。対応するMCPクライアントを接続し、API認証情報でget_google_maps_photosを使えます。Agent Skillはワークフロー手順とRESTフォールバックを追加します。成功したライブギャラリーページは共有API利用枠を消費します。