Google Maps Place Details
Google Mapsの公開スポットページでは、名称、カテゴリ、説明、住所、連絡先、評価、口コミ数、Webサイト、地理情報が公開されている場合があります。正規化されたレコードにより、これらの表示中のフィールドを拠点リスト、施設リサーチ、ディレクトリの情報補完、特定時点のモニタリングと簡単に結び付けられます。
Google Maps Place Details API の主な機能
- URLの一括詳細取得1つ以上の既知のGoogle Maps URLを送信すると、空でない入力ごとにプロバイダーの詳細取得行が1行作成されます。取得件数の上限は、送信したURLの数に内部で設定されます。
- 安定したスポットレコード識別情報、元URL、名称、説明、カテゴリ、住所、電話番号、Webサイト、評価、口コミ数を PlaceItem スキーマで返します。
- 構造化された地理情報取得可能な所在地名、市区町村、地域、国、緯度、経度を、表示用テキストから解析することなくまとめて保持します。
- 結果に応じた課金送信したURL1件につき0.15クレジットで見積もり、正常に返された標準スポットレコード1件につき0.15クレジットで精算します。結果が空の場合は課金されません。
Google Maps Place Details API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | 必須。パーサーがホスト名を取得できる参照の空でない配列です。ランタイムはホスト名で google.com、goo.gl、およびそれらのサブドメインを受け付けます。オーソリティ部分を含む任意のスキームとプロトコル相対参照を受け付け、特定のパスパターンは必要ありません。 |
Google Maps Place Details API の使い方
既知のGoogle Maps URLを送信して非同期タスクを追跡し、保存されたすべての PlaceItem を標準のカーソル付き結果エンベロープで読み取ります。
- 解析後のホスト名が google.com、goo.gl、またはそのいずれかのサブドメインになる参照を1つ以上用意します。
- urls を /v1/google-maps/place-details に POST し、返された task_id を保存します。
- タスクが成功または失敗するまで /v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取り、has_more が true の間は next_cursor をたどります。送信リクエスト自体には results_limit フィールドはありません。
curl -X POST "https://api.socq.ai/v1/google-maps/place-details" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.google.com/maps/place/Coffee%20Project%20New%20York%20%7C%20East%20Village/data=!4m7!3m6!1s0x89c2599b5a24d7fd:0x9e354f6cf514b9fc!8m2!3d40.7270884!4d-73.9893820!16s%2Fg%2F11c3svpqld!19sChIJ_dckWptZwokR_LkU9WxPNZ4?authuser=0&hl=en&rclk=1"]}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueGoogle Maps Place Details API の主なユースケース
- 拠点ディレクトリの情報補完: 既知のスポットURLに、正規化されたカテゴリ、住所、電話番号、Webサイト、評価、口コミ数、座標のフィールドを追加します。
- 店舗・支店の監査: 管理しているURLリストを定期的に再取得し、表示中の識別情報、連絡先、評価、地理情報を所定の取得時点で比較します。
- スポットレコードの照合: 返されたID、元URL、名称、住所、座標を使い、公開スポットを社内の拠点レコードと突き合わせます。
Google Maps Place Details API 活用のヒント
- パーサーが受け付け可能なホスト名を解決できるよう、完全な絶対URL形式のマップURLを送信してください。スキームのないホスト名だけでは、ランタイムのパーサーでホスト名を取得できません。
- Place ID、Google APIキー、フィールドマスク、results_limit は、このSocQのリクエスト仕様に含まれないフィールドのため追加しないでください。
- 送信した各URLは結果が保証されたものではなく、詳細取得の候補として扱ってください。ソース側の行が利用できない、または使用できない場合、項目数がURL数より少なくなることがあります。
- null になり得る電話番号、Webサイト、評価、口コミ数、説明、公開日時、所在地の各項目は、代替値を補わずそのまま保持してください。
- プロバイダー側の上限はURLの数で決まりますが、保存されたタスク結果の読み取りにはページネーションが適用されるため、has_more が true の間は next_cursor で続きを取得してください。
関連API
Google Maps Place Details API 以外に別の種類の公開Google Mapsデータが必要な場合は、これらのAPIをご利用ください。
- Google Maps Search API — クエリと場所で公開Google Mapsのスポットを検索し、正規化された名称・ID、住所、連絡先、評価、レビュー数、URL、座標の各フィールドを返します。
- Google Maps Reviews API