POST /api/v1/search

Google MapsスクレイパーAPI

キーワードと地域でビジネスを検索します。同じJSONレスポンスで最大20件の構造化ビジネスレコードを受け取り、アプリケーションや調査ワークフローですぐに使えます。

リクエスト例

完全な仕様については、APIドキュメントをご覧ください。

curl https://gmapscrawl.com/api/v1/search \
  -H "Authorization: Bearer $GMSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seattle-coffee-search-001" \
  -d '{"q":"coffee shops in Seattle","page":1,"extra":false}'

例示用の空のレスポンスです。ライブ検索では利用可能なビジネスが返ります。APIキーはサーバーサイドに保管し、新しい処理には新しい冪等キーを使い、変更しないリトライでは同じキーを保持してください。

レスポンス

例示用のJSON
{
  "data": {
    "total": 0,
    "params": {
      "q": "coffee shops in Seattle",
      "page": 1,
      "hl": "en",
      "extra": false
    },
    "businesses": []
  },
  "request_id": "req_example",
  "schema_version": "2026-09-22"
}

APIは同じレスポンス内でJSONを返します。タイムアウト後は、変更していないボディを同じIdempotency-Keyで再試行してください。テスト用認証情報では、実際の利用枠を消費せずにシミュレートされたデータが返ります。

構造化ビジネスデータ

Maps検索から使えるレコードへ。

レスポンスからdata.businessesを読み取ります。各ビジネスのリスティングフィールドはplace以下にグループ化されており、フィールドの有無はソースに依存します。

01

ビジネス情報と位置

ビジネス名、カテゴリ、整形済み住所、座標、Maps URLを使って、地域ビジネスのデータセットを整理します。

02

連絡先と評判

利用可能な電話番号、Webサイト、評価、レビュー数を読み取ります。extraを有効にすると、メールやソーシャルの連絡先エンリッチメントをリクエストできます。

03

識別子と観測日

レビューや写真の検索用にplace.dataIdを保持します。place.observedAtとcontactsCheckedAtを確認して、データがいつ観測されたかを把握します。

欠損データや古いデータを可視化する

利用できないフィールドはnullまたは空になる場合があり、エンリッチメントはnot_foundやfailedを返すことがあります。レコードがあってもメールアドレスやWebサイトが存在するとは限りません。Mapsの詳細情報は元の観測タイムスタンプとともに最大730日間再利用される場合があるため、レコードを使用する前に鮮度を評価してください。

データの鮮度について →

焦点を絞ったリクエスト

クエリ、ページ、エンリッチメントを選択。

サーバーサイドのAPIキーをauthorizationヘッダーに設定し、JSONボディを送信します。必須なのはqのみです。

Google Maps Search APIのパラメータ
パラメータ要件目的
q必須ビジネスキーワードと地域(例:シアトルのコーヒーショップ)。2〜200文字で指定します。
pageデフォルト: 11〜10の番号付き検索ページ。各リクエストは最大20件のビジネスを返します。
ll任意検索地域を指定する@47.6062,-122.3321,12z形式のMapsビューポート。
hlデフォルト: en検索に使用する言語コード。
gl任意クエリを限定する2文字の国コード。厳密な地理フィルターではありません。
extraデフォルト: falsetrueに設定すると、利用可能なメール・ソーシャル連絡先エンリッチメントをリクエストします。時間がかかる場合があります。

レスポンスは正規化されたパラメータをdata.paramsに返します。data.totalはこのレスポンス内のビジネス数であり、Google Maps上の全ビジネス数ではありません。ワークフローでさらに結果が必要な場合は、明示的に別のページを指定してください。

最初の統合を構築

1つのリクエスト。有用な次の一歩。

Search APIは同期型です:HTTPレスポンスから直接結果を読み取ります。

01

APIキーを作成

APIワークスペースでscrapes:write権限を持つキーを作成します。キーはサーバー環境に保管し、リクエストでAuthorization: Bearerを送信します。

APIキーを開く
02

範囲を限定した地域を検索

カテゴリと地域を選び、ページ1をリクエストして、返されたリスティングフィールドを確認します。市場比較には、比較したい地域ごとに個別の検索を実行します。

03

場所の識別子をたどる

一致したビジネスのplace.dataIdをfidとして使用し、レビューページやギャラリーページを取得します。これらは別のリクエストで、独自のレコードを返します。

Reviews APIを見る

実際のリクエストに備える

予測可能なページ。明示的な上限。

使用量と可用性

成功したライブ検索ページは、空の結果を含めて1ページにつき1 APIリクエストユニットを消費します。RESTとMCPはAPI利用枠を共有します。OnlineスクレイパーとExtensionサブスクリプションは別の利用枠です。レート制限、認証情報、サービス容量、ソースの可用性も引き続き適用されます。

APIプランを比較 →

タイムアウトとリトライ

HTTPクライアントでは最大180秒を許容してください。タイムアウトになると、リクエストユニットが予約されたまま処理が続行される場合があります。同一のボディとIdempotency-Keyを再利用してそのリクエストをリトライしてください。新しい試行を始める前に、エラーの詳細とリトライ可否を確認してください。

リトライを理解する →

ワークフローを続ける

同じビジネスデータをさらに活用する方法。

01

レビューとギャラリーデータ

feature IDを使って、場所の公開レビューや写真・動画メタデータを取得します。

ギャラリーデータを見る
02

MCPクライアントを接続

対応するAIクライアントに、API認証情報で検索・レビュー・写真ツールを検出させます。

MCPを設定
03

Agent Skillをインストール

エージェントにワークフロー手順、オペレーションリファレンス、Google Maps調査用のRESTフォールバックを提供します。

スキルを見る

よくある質問

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

data.businesses、data.total、正規化されたdata.params、request_id、schema_versionを含むJSONエンベロープを返します。ビジネスには、名前、住所、カテゴリ、連絡先情報、評価、Maps識別子などの利用可能なリスティングフィールドが含まれます。

PythonやJavaScriptからAPIを使えますか?

はい。エンドポイントはJSONとBearer認証を使った標準的なHTTP POSTリクエストを受け付けます。上記の例ではPython標準ライブラリとサーバーサイドのJavaScript fetchを使用しています。これらのヘッダーとボディを送信できるHTTPクライアントなら統合できます。

1回のリクエストで何件のビジネスが返りますか?

検索ページは0〜20件のビジネスを返します。pageパラメータは1〜10を受け付けます。成功したライブページは、空のページを含めて1ページにつき1 APIリクエストユニットを消費します。検索ですべてのページに20件あるとは限りません。

個別のレビューや写真を取得できますか?

はい。ビジネスのplace.dataIdをコピーし、fidとして別のReviewsまたはPhotos APIに渡します。これらのエンドポイントはリクエストごとに1つの限定されたページを返します。API概要ページには、各エンドポイントのフィールド、例、ページネーションルールへのリンクがあります。

すべてのビジネスにメールアドレスは含まれますか?

いいえ。extraをtrueに設定すると、利用可能な連絡先エンリッチメントをリクエストできます。Webサイト、メール、ソーシャルプロフィールは欠損している場合があります。enrichmentStateとfieldStatesを確認し、利用できないデータをアプリケーションで明示的に扱ってください。

統合をテストするにはどうすればよいですか?

テスト用認証情報をお持ちの場合、そのレスポンスはシミュレートされ、ライブAPI利用枠を消費しません。これらの結果にはシミュレートであることを明記してください。ライブキーには有効なAPI権限と利用可能なサービス容量が必要で、成功したライブ呼び出しはリクエストユニットを消費します。

次のステップへ

最初のGoogle Maps検索を構築しましょう。

APIキーを作成し、クエリと地域を1つ選んで、同じレスポンスで構造化ビジネスデータを読み取ります。