POST /api/v2/photos

Google MapsフォトスクレイパーAPI

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はプレースホルダーです。実行中のリクエストをリトライする際は、同じ冪等キーとボディを保持してください。

レスポンス

例示用のJSON
{
  "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つの場所の画像・動画メタデータをリクエストします。

Google MapsフォトスクレイパーAPIのリクエストパラメータ
フィールド意味
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はその場所のギャラリーにリンクします。

Google MapsフォトスクレイパーAPIのレスポンスフィールド
フィールド意味
photoUrl利用可能な写真URL、または動画項目のプレビュー画像。
videoUrl任意の動画URL。動画ソースを含む動画レコードに存在します。
urlリクエストした場所のGoogle MapsギャラリーURL。
next別の番号付きギャラリーページが利用可能かどうか。
totalこのレスポンスの件数(0〜20)。これは場所のギャラリー全体のサイズではありません。
paramsこのレスポンスに使用された正規化されたfidとpage。

エンドポイントはこのページオブジェクトをJSONとして直接返します。トップレベルからphotosを読み取ってください。APIはメタデータとメディアリンクを返します。画像や動画の有無はソースに依存し、ギャラリー項目があってもダウンロード可能な動画があるとは限りません。

一度に1ページずつ

各レスポンスで最大20件のギャラリー項目を取得。

返されたnextフラグで、ワークフローにもう1リクエスト必要かを判断します。

01

ページ1から開始

場所のfidとページ1を送信します。レコードはその場所のギャラリーが提供する順序に従います。

02

現在のページを確認

totalはこのレスポンスで返されたギャラリー項目数を数えます。空のページも有効な結果です。レコードを分析に追加する前に利用可能なフィールドを確認してください。

03

慎重に続行

nextがtrueの場合、pageを増やし、同じfidを維持してください。nextがfalseになったら、またはワークフローに十分なメディアレコードが集まったら停止します。

場所を視覚的に探索

ギャラリーメタデータを調査ワークフローに取り込む。

01

ビジネスリスティング調査

選択したビジネスに関連するギャラリーを確認し、返されたレコードの横にソースのギャラリーリンクを保持します。

02

写真と動画の整理

任意のvideoUrlフィールドを使って写真レコードと動画レコードを分け、独自の調査インターフェースで利用可能なプレビュー画像を表示します。

03

エージェント支援のギャラリー確認

接続したエージェントにギャラリーメタデータの1ページを取得させ、さらなる確認用に利用可能なメディアリンクをリストアップさせます。

認証と使用量

各ページでAPIキーを使用。

共有API利用枠

scrapes:writeを許可するキーでAuthorization: Bearerを送信します。成功したライブページは、空のページを含めて1ページにつき1 APIリクエストユニットを消費します。RESTとMCPは同じAPI利用枠を使用します。テスト用認証情報をお持ちの場合、そのレスポンスはシミュレートされ、ライブ利用枠を消費しません。

APIプランと上限を見る →

リトライをリクエストに紐付ける

最初のリクエストで任意のIdempotency-Keyを送信し、タイムアウトのリトライでは同一ボディとともに保持してください。処理のタイムアウトでユニットが予約されたままになる場合があります。エラーが試行の終了を報告する場合は、新しいキーで新しい試行を作成する前に、そのリトライガイダンスに従ってください。

エラーとリトライのガイダンスを読む →

よくある質問

Google MapsフォトスクレイパーAPIは何を返しますか?

各JSONレスポンスで、1つの場所につき最大20件の写真・動画メタデータレコードを返します。各レコードにはphotoUrlがあり、動画レコードにはvideoUrlも含まれる場合があります。トップレベルのurlはその場所のギャラリーにリンクします。

場所のギャラリー用feature IDはどう取得しますか?

Search APIレスポンスで一致したビジネスのplace.dataIdを使い、fidとして送信します。既存のMaps feature IDを指定することもできます。追加のギャラリーページをリクエストする際も同じfidを送信してください。

Photos APIは画像や動画ファイルをダウンロードしますか?

このエンドポイントはJSONでメタデータとメディアURLを返します。アプリケーションで利用可能なリンクとギャラリーソースを確認できます。ソースの可用性がどのレコードやURLが返されるかを決定します。photoUrlは動画のプレビュー画像の場合があります。

Google Mapsギャラリーをページネーションするには?

ページ1から始めます。totalはそのレスポンス内のレコード数を数えます。nextがtrueの場合、同じfidと新しい冪等キーで次のページをリクエストします。nextがfalseになったら、またはワークフローに十分なレコードが集まったら停止します。

ギャラリーの順序は設定できますか?

Photos APIはfidとpageを受け取ります。ソースが提供するギャラリー順で項目を返し、レビューのようなsort_byパラメータは提供していません。

AIエージェントでギャラリーメタデータを取得できますか?

はい。対応するMCPクライアントを接続し、API認証情報でget_google_maps_photosを使えます。Agent Skillはワークフロー手順とRESTフォールバックを追加します。成功したライブギャラリーページは共有API利用枠を消費します。

次のステップへ

1つの場所のギャラリーを探索しましょう。

APIキーを作成し、場所のfeature IDを指定して、構造化された写真・動画メタデータを取得します。