google-maps/
search

クエリと地域を指定して公開Google Mapsのスポットを検索し、正規化された名称、カテゴリ、住所、連絡先、評価、口コミ数、URL、座標を返します。

Google Maps Search API

クエリと地域で指定
任意の地理情報
取得件数1〜2,000件
正規化されたスポットレコード
結果1件あたり0.15クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

Google Maps Search

Google Maps検索は、ビジネス・カテゴリ・スポットのクエリと必須の地域から、構造化された公開スポットのレコードを生成します。保存される各結果はプロバイダーに依存しない PlaceItem スキーマを使用するため、取得可能な識別情報、住所、連絡先、評価、口コミ数、座標のフィールドを、ソース固有のレスポンスキーに縛られることなくリサーチや情報補完のシステムに取り込めます。

Google Maps Search API の主な機能

  • クエリと地域による検索coffee のような空でない必須の query と、New York, NY のような必須の location を組み合わせて、該当する公開スポットを検索します。
  • 任意の地理条件より明確な地理条件が必要な場合は、country、緯度・経度のペア、zoom_level を追加できます。省略した任意フィールドの値が補完されることはありません。
  • スポットの識別情報と連絡先の正規化取得可能な場合、ID、元URL、名称、カテゴリ、住所、公開電話番号、Webサイト、取得時刻を安定した PlaceItem フィールドとして受け取れます。
  • 評価と地理座標取得可能な評価、口コミ数、市区町村、地域、国、緯度、経度を各スポットとともに保持し、ソース側に存在しないフィールドも安全に処理します。

Google Maps Search API のパラメータ

パラメータ必須説明
query必須必須。スポット、ビジネス、カテゴリを表す空でない検索語です。
location必須必須。市区町村、地域、住所など、人が読める形式の空でない検索エリアです。座標を両方とも省略した場合は、query と組み合わせて検索に使われます。
country任意任意。地理情報として転送される、空でない国名または国コードです。
latitude任意任意。-90〜90の緯度です。longitude と一緒に指定する必要があります。
longitude任意任意。-180〜180の経度です。latitude と一緒に指定する必要があります。
zoom_level任意任意。0〜21の整数で指定する地図のズームレベルです。
results_limit任意保存するスポットレコードの最大件数です。デフォルトは100で、1〜2,000の整数を指定できます。

Google Maps Search API の使い方

クエリと地域を送信して非同期タスクを追跡し、正規化されたスポットレコードをカーソルページネーションで読み取ります。

  1. 空でない query と location を用意します。必要に応じて country、座標、zoom_level、1〜2,000の results_limit を追加します。
  2. リクエストを /v1/google-maps/search に POST し、返された task_id を保存します。
  3. タスクが成功するか失敗が報告されるまで /v1/tasks/{task_id} をポーリングします。
  4. data.results.items を読み取り、has_more が true の間は next_cursor をタスクエンドポイントに渡して続きを取得します。
curl -X POST "https://api.socq.ai/v1/google-maps/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Google Maps Search API の主なユースケース

  • 地域ビジネスの発見: 指定した市区町村、地区、住所エリアで、カテゴリやサービスに一致する公開ビジネスのリストを件数を区切って作成します。
  • 場所データの情報補完: CRMやリサーチ用のキューにすでにあるスポット候補に、取得可能な名称、カテゴリ、住所、電話番号、Webサイト、座標を追加します。
  • 市場とカバレッジのリサーチ: 個別に送信した地域ごとの検索結果について、取得したスポット数、カテゴリ、評価、口コミ件数を比較します。
  • スポット候補リストの作成: 公開URL、連絡先フィールド、評価、座標を使い、別途行う検証や詳細取得のワークフローの対象とするスポットを選定します。

Google Maps Search API 活用のヒント

  • 具体的なカテゴリやビジネスの語句を使い、location には市区町村、地区、住所を明確に指定してください。あいまいな組み合わせでは、広すぎる結果や判別しにくい結果になることがあります。
  • country、座標、zoom_level は、確認済みの地理情報がある場合にのみ送信してください。latitude と longitude は必ず一緒に指定し、両方の値を記載された範囲内に収めてください。
  • results_limit は必要なレコード数に近い値にしてください。results_limit は取得の上限を、タスクの GET の limit はレスポンスの1ページあたりに返される保存済みレコード数を制御します。
  • 保存された結果がタスクの最初のレスポンスページを超える場合は、has_more が false になるまで next_cursor で続きを取得してください。
  • 説明、連絡先フィールド、評価、口コミ数、座標は任意の公開データとして扱い、特定時点の比較のために collected_at を保持してください。

Google Maps Search API 以外に別の種類の公開Google Mapsデータが必要な場合は、これらのAPIをご利用ください。

他のプラットフォームを見る

Google Mapsのデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

Google Maps Search API — よくある質問

Google Maps Search APIは、必須のクエリと地域から公開スポットを検索する非同期インターフェースです。取得可能な識別情報、カテゴリ、住所、連絡先、評価、口コミ数、URL、地理情報のフィールドを含む、プロバイダーに依存しない PlaceItem レコードを返します。

query と location はどちらも必須の空でない文字列です。country、latitude、longitude、zoom_level、results_limit は任意です。

はい。現在のリクエスト仕様では、座標はペアでのみ受け付けます。location を query と組み合わせる場合は両方を省略し、座標を使う場合は-90〜90の latitude と-180〜180の longitude を一緒に指定してください。

results_limit は取得の上限であり、件数を保証するものではありません。ソースが返す公開の一致件数が少ない場合があり、また同じ識別情報を持つレコードはタスクごとに1回だけ保存されます。

公開スポットの結果では、説明、カテゴリ、住所、電話番号、Webサイト、評価、口コミ数、URL、一部の所在地フィールドが含まれない場合があります。クライアント側では、null 値をタスクの失敗とみなさずに処理してください。

保存されたスポットレコード1件につき0.15 SocQクレジットです。事前課金には results_limit(省略時は100)が使われ、成功後は実際に保存された結果の件数に基づいて精算されます。結果が空の場合、結果に対する課金は発生しません。