ビジネス情報と位置
ビジネス名、カテゴリ、整形済み住所、座標、Maps URLを使って、地域ビジネスのデータセットを整理します。
完全な仕様については、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キーはサーバーサイドに保管し、新しい処理には新しい冪等キーを使い、変更しないリトライでは同じキーを保持してください。
{
"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で再試行してください。テスト用認証情報では、実際の利用枠を消費せずにシミュレートされたデータが返ります。
構造化ビジネスデータ
レスポンスからdata.businessesを読み取ります。各ビジネスのリスティングフィールドはplace以下にグループ化されており、フィールドの有無はソースに依存します。
ビジネス名、カテゴリ、整形済み住所、座標、Maps URLを使って、地域ビジネスのデータセットを整理します。
利用可能な電話番号、Webサイト、評価、レビュー数を読み取ります。extraを有効にすると、メールやソーシャルの連絡先エンリッチメントをリクエストできます。
レビューや写真の検索用にplace.dataIdを保持します。place.observedAtとcontactsCheckedAtを確認して、データがいつ観測されたかを把握します。
利用できないフィールドはnullまたは空になる場合があり、エンリッチメントはnot_foundやfailedを返すことがあります。レコードがあってもメールアドレスやWebサイトが存在するとは限りません。Mapsの詳細情報は元の観測タイムスタンプとともに最大730日間再利用される場合があるため、レコードを使用する前に鮮度を評価してください。
データの鮮度について →焦点を絞ったリクエスト
サーバーサイドのAPIキーをauthorizationヘッダーに設定し、JSONボディを送信します。必須なのはqのみです。
| パラメータ | 要件 | 目的 |
|---|---|---|
| q | 必須 | ビジネスキーワードと地域(例:シアトルのコーヒーショップ)。2〜200文字で指定します。 |
| page | デフォルト: 1 | 1〜10の番号付き検索ページ。各リクエストは最大20件のビジネスを返します。 |
| ll | 任意 | 検索地域を指定する@47.6062,-122.3321,12z形式のMapsビューポート。 |
| hl | デフォルト: en | 検索に使用する言語コード。 |
| gl | 任意 | クエリを限定する2文字の国コード。厳密な地理フィルターではありません。 |
| extra | デフォルト: false | trueに設定すると、利用可能なメール・ソーシャル連絡先エンリッチメントをリクエストします。時間がかかる場合があります。 |
レスポンスは正規化されたパラメータをdata.paramsに返します。data.totalはこのレスポンス内のビジネス数であり、Google Maps上の全ビジネス数ではありません。ワークフローでさらに結果が必要な場合は、明示的に別のページを指定してください。
最初の統合を構築
Search APIは同期型です:HTTPレスポンスから直接結果を読み取ります。
APIワークスペースでscrapes:write権限を持つキーを作成します。キーはサーバー環境に保管し、リクエストでAuthorization: Bearerを送信します。
APIキーを開くカテゴリと地域を選び、ページ1をリクエストして、返されたリスティングフィールドを確認します。市場比較には、比較したい地域ごとに個別の検索を実行します。
一致したビジネスのplace.dataIdをfidとして使用し、レビューページやギャラリーページを取得します。これらは別のリクエストで、独自のレコードを返します。
Reviews APIを見る実際のリクエストに備える
成功したライブ検索ページは、空の結果を含めて1ページにつき1 APIリクエストユニットを消費します。RESTとMCPはAPI利用枠を共有します。OnlineスクレイパーとExtensionサブスクリプションは別の利用枠です。レート制限、認証情報、サービス容量、ソースの可用性も引き続き適用されます。
APIプランを比較 →HTTPクライアントでは最大180秒を許容してください。タイムアウトになると、リクエストユニットが予約されたまま処理が続行される場合があります。同一のボディとIdempotency-Keyを再利用してそのリクエストをリトライしてください。新しい試行を始める前に、エラーの詳細とリトライ可否を確認してください。
リトライを理解する →ワークフローを続ける
feature IDを使って、場所の公開レビューや写真・動画メタデータを取得します。
ギャラリーデータを見る対応するAIクライアントに、API認証情報で検索・レビュー・写真ツールを検出させます。
MCPを設定エージェントにワークフロー手順、オペレーションリファレンス、Google Maps調査用のRESTフォールバックを提供します。
スキルを見るdata.businesses、data.total、正規化されたdata.params、request_id、schema_versionを含むJSONエンベロープを返します。ビジネスには、名前、住所、カテゴリ、連絡先情報、評価、Maps識別子などの利用可能なリスティングフィールドが含まれます。
はい。エンドポイントはJSONとBearer認証を使った標準的なHTTP POSTリクエストを受け付けます。上記の例ではPython標準ライブラリとサーバーサイドのJavaScript fetchを使用しています。これらのヘッダーとボディを送信できるHTTPクライアントなら統合できます。
検索ページは0〜20件のビジネスを返します。pageパラメータは1〜10を受け付けます。成功したライブページは、空のページを含めて1ページにつき1 APIリクエストユニットを消費します。検索ですべてのページに20件あるとは限りません。
はい。ビジネスのplace.dataIdをコピーし、fidとして別のReviewsまたはPhotos APIに渡します。これらのエンドポイントはリクエストごとに1つの限定されたページを返します。API概要ページには、各エンドポイントのフィールド、例、ページネーションルールへのリンクがあります。
いいえ。extraをtrueに設定すると、利用可能な連絡先エンリッチメントをリクエストできます。Webサイト、メール、ソーシャルプロフィールは欠損している場合があります。enrichmentStateとfieldStatesを確認し、利用できないデータをアプリケーションで明示的に扱ってください。
テスト用認証情報をお持ちの場合、そのレスポンスはシミュレートされ、ライブAPI利用枠を消費しません。これらの結果にはシミュレートであることを明記してください。ライブキーには有効なAPI権限と利用可能なサービス容量が必要で、成功したライブ呼び出しはリクエストユニットを消費します。