Google Maps API
公開スポットの検索、既知のMaps URLの正規化された詳細の取得、取得元に紐づくスポット情報と投稿者のコンテキストを含む公開クチコミの取得ができます。
利用できるGoogle Maps API
クエリと地域による検索にはSearch、既知のMaps URLにはPlace Details、上限付きの公開クチコミの取得にはReviewsを使用します。
取得できるGoogle Mapsデータ
SocQは正規化された公開 PlaceItem レコードを返し、ロケーション調査、ビジネスの発掘、データの補完、特定時点の市場スナップショットに活用できるようにします。
スポットの基本情報
取得可能なスポットID、名称、カテゴリ、取得元URL、レコードの種類、取得日時を取得します。
住所と地理的コンテキスト
取得可能な整形済み住所、所在地のラベル、市区町村、地域、国、緯度、経度を保持します。
公開されている連絡先
検索結果に含まれている場合、公開されている電話番号とWebサイトを取得します。
評価とクチコミ数
取得元が示す評価とクチコミ数を、欠けている値を推測せずにそのまま保持します。
説明とカテゴリ
取得可能な概要テキストとカテゴリのラベルを使い、スポットの結果を分類・絞り込みできます。
タスクとページネーションのメタデータ
タスクのステータスと result_count を追跡し、next_cursor と has_more を使って保存済みの PlaceItem レコードをページ送りします。
所在地テキストと座標のコンテキスト
Google Maps Searchでは、常に query と location が必要です。現在のランタイム仕様では、座標は任意のコンテキストであり、location の代わりにはなりません。
| 入力の選択肢 | ランタイムでの動作 | 使用する場面 |
|---|---|---|
| location のみ | location のテキストを query と組み合わせて検索 | 市区町村、地区、ランドマーク、住所を起点とした検索 |
| location と両方の座標 | location は必須のまま、座標は lat と long として転送 | 検証済みの地理的な中心点がある場合 |
| location と片方の座標 | 指定した座標が単独で転送される | 部分的な地理コンテキストを意図的に使う場合のみ |
| country と zoom_level | 任意のコンテキストが検索行とともに転送される | 国のヒントや0〜21の明示的なズームが必要な場合 |
Google Maps APIの仕組み
上限付きのスポット検索を送信し、非同期の取得を待ってから、タスクに保存された正規化レコードをページ送りします。
1. スポット検索を定義
具体的なクエリと必須の location を決め、必要な検証済みの地理コンテキストだけを任意で追加します。
2. タスクを送信して追跡
リクエストをPOSTして task_id を保存し、処理が成功または失敗するまで /v1/tasks/{task_id} をポーリングします。
3. 正規化されたスポットを読み取る
data.results.items を処理し、has_more が true の間は next_cursor をたどります。
小さめの取得件数上限とともにクエリと location を送信し、共通のタスクエンドポイントから正規化された PlaceItem の結果を読み取ります。
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 APIの主なユースケース
地域ビジネスの発掘
市区町村、地区、ランドマーク、住所のコンテキストで、カテゴリやサービスに一致する公開ビジネスを見つけます。
スポットデータの補完
既存のスポット候補に、取得可能な連絡先、住所、カテゴリ、評価、クチコミ数、URL、座標のフィールドを追加します。
地域市場のスナップショット
個別に送信したエリアごとに上限付きの結果セットを取得し、特定の取得時点における公開スポットのカバレッジを比較します。
確認キュー
公開されている基本情報、連絡先、評価、地理のフィールドから候補リストを作成し、後のレビューや別の詳細取得処理に回します。
制限事項と公開データポリシー
結果は特定時点の公開レコードです。検索で得られる内容やフィールドの充足度は、送信したリクエストに対して取得元が提供する情報によって異なります。
- query と location はどちらも空でない文字列で必須です。location を座標で代用することはできません。
- country、latitude、longitude、zoom_level は任意です。現在のランタイムでは、latitude と longitude を個別に受け付けます。
- zoom_level は0〜21の整数である必要があります。results_limit のデフォルトは100で、1〜2,000を指定できます。
- results_limit は取得件数の上限で、タスクのGETの limit は保存済み結果の各レスポンスページの件数を制御します。
- 公開結果では、説明、カテゴリ、連絡先、評価、クチコミ数、URL、地理のサブフィールドが欠ける場合があります。
- 重複する識別情報はタスクごとに1回だけ保存されるため、result_count が取得元で確認された行数より少なくなる場合があります。
Google Maps APIに関するよくある質問
Google Maps APIとは何ですか?
Google Maps APIは、公開スポットの検索、既知のスポットURLの解決、公開クチコミの取得を非同期で行い、正規化レコードとして返すAPIです。Searchは query と location を受け付け、取得可能な基本情報、住所、連絡先、評価、クチコミ数、URL、座標のフィールドを含む PlaceItem レコードを返します。
Searchには何が必要ですか?
Searchには、空でない query と location の文字列が必要です。country、latitude、longitude、zoom_level、results_limit は任意です。
取得件数とレスポンスのページネーションはどう違いますか?
results_limit は、送信した検索で取得するレコード数の上限です。成功後、タスクエンドポイントは保存済みのレコードを、別の limit と next_cursor パラメータで制御されるページ単位で返します。
スポットのフィールドが null になるのはなぜですか?
公開検索結果が、すべての連絡先、評価、クチコミ、説明、URL、住所、座標のフィールドを提供しているとは限らないためです。正規化スキーマでは、欠けている値を null として保持します。
Google Maps Searchの結果の料金はどのように計算されますか?
保存されたスポットは1件あたり0.15クレジットです。事前課金の見積もりには results_limit(省略時は100)を使用し、正常に完了した時点で実際に保存された結果の件数に基づいて精算されます。
プラットフォームを横断してデータを組み合わせ、より包括的なビジネスインサイトを
さまざまなプラットフォームの公開プロフィール、コンテンツ、エンゲージメントデータを1つのワークフローに集約し、ブランド、クリエイター、トピックの追跡やクロスプラットフォームのモニタリング・分析をより効率的に行えます。
Google Play API
既知のストアURLから、公開Google Playのアプリ詳細、カテゴリランキング、レビューを、正規化されたアプリとレビューのレコードとして取得できます。
Amazon API
対応するマーケットプレイスで公開Amazon商品を検索し、正規化された商品詳細、売れ筋ランキング、レビュー、セラーのプロフィール、クリエイターのストアフロントのレコードを取得できます。
Apple App Store API
既知のストアURLから、公開Apple App Storeのアプリ詳細、カテゴリランキング、レビューを、正規化されたアプリとレビューのレコードとして取得できます。
SEO API
Googleのオーガニック検索結果をリアルタイムで取得し、キーワードの需要と順位獲得の難易度を比較し、シードキーワードを拡張し、サイトの検索での可視性を支えるキーワードとページを明らかにし、検索意図を分類できるほか、Googleニュース・画像・サジェスト、Bing、YouTubeの結果も集められます。すべてのエンドポイントで、共通のSocQのAPIキー、非同期タスクフロー、正規化された結果形式を使用します。
Telegram API
t.meリンクから公開Telegramチャンネルを読み取ります。登録者数付きのチャンネル情報、閲覧数とリアクション付きの投稿、個別の投稿、ディスカッショングループのコメント、類似チャンネル、全履歴の検索に対応します。
Link in Bio API
クリエイターがInstagram、TikTok、YouTubeのプロフィール欄に置く1本のリンクを、表示名、紹介文、アイコン、掲載されている連絡先メール、連携SNS、各ボタンのタイトルとリンク先という構造化データに変えます。


