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 の使い方
クエリと地域を送信して非同期タスクを追跡し、正規化されたスポットレコードをカーソルページネーションで読み取ります。
- 空でない query と location を用意します。必要に応じて country、座標、zoom_level、1〜2,000の results_limit を追加します。
- リクエストを /v1/google-maps/search に POST し、返された task_id を保存します。
- タスクが成功するか失敗が報告されるまで /v1/tasks/{task_id} をポーリングします。
- 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 trueGoogle 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 を保持してください。
関連API
Google Maps Search API 以外に別の種類の公開Google Mapsデータが必要な場合は、これらのAPIをご利用ください。