Google Placesが登場しました

Google の Places タブが検索語に対して表示する場所を、選んだ都市で最大100件、住所、座標、電話番号、ウェブサイト、評価とともに受け取れます。20件ごとに1クレジットです。

得られる結果

• GOOGLE_PLACES: 1つのタスクで、選んだ都市から検索したときに Google の Places タブが表示する一覧を最大100件読みます。
• places: 場所ごとに name、position、載っていた page に加え、location（住所、緯度、経度）、phoneNumber、url、mapsUrl、placeId、評価とレビュー数の reviews、category、Google が表示するレビューの一文が入ります。
• pages: タスクが読んだ20件単位のページ数で、このページ数分が課金されます。

仕組み

query と city を送ります。city は Reno, Nevada, United States のように Google の表記で書きます。順位追跡ツールが場所ごとに Google の uule 値を保存していれば、uule として送ると Google はその場所から検索します。country は市場を決め、既定値は US です。

Google は1ページに20件の場所を表示します。limit で受け取る件数を1〜100（既定は20）で指定すると、タスクは Google の順に最大5ページを読みます。position はページをまたいで続けて数え、後のページに再び出た場所は1回だけ数えます。Google の一覧が limit より先に終わった場合は、Google が表示した場所をすべて受け取ります。

タスクはページごとに Google が検索した地点を確かめるため、1つの一覧の場所はすべて同じ都市から届きます。

活用例

• 自社の業種で検索したとき、Google が地元の都市で表示する場所の中で自店舗が何位かを、ローカルパックの3件より先まで追跡します。
• 同じ検索語を営業している都市ごとに送り、市場ごとの上位の事業者を比べます。
• 同じ検索語の Google AI Overview や AI Mode の回答と場所の一覧を並べ、回答がどの場所を勧めるかを確かめます。
• Playground ですぐに試せます。検索タブで Google Places を選び、都市を入力して、件数を最大100件まで指定します。

リクエストを送る

API キーを Authorization ヘッダーに入れてリクエストを送ります。

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "GOOGLE_PLACES",
    "payload": {
      "query": "Reno attorney",
      "city": "Reno, Nevada, United States",
      "limit": 100,
      "country": "US"
    }
  }'

リクエストのフィールド

taskTypestring必須

実行するエンジン。CHATGPT や GOOGLE などを指定します。

payload.querystring必須

ユーザーが検索ボックスに入力するとおりに書いた検索クエリ。

payload.citystring

検索する都市。Google の表記で書きます。例: Reno, Nevada, United States。最大100文字。1つのタスクで city と uule のどちらか一方を使います。

payload.uulestring

Google の位置の値を w+ 形式のまま指定します。順位追跡ツールが場所ごとに保存している値で、そのまま Google に送ります。

payload.limitinteger

返す場所の数、1〜100。既定値は20（Google の一覧1ページ分）。

payload.countrystring

質問する市場の2文字の国コード。US、KR、JP など。既定値は US。

webhook.urlstring

サーバーの HTTPS アドレス。タスクが完了した瞬間に結果をここへ送ります。

レスポンス

完了したタスクはこの形で届きます。長さを抑えて抜粋しています。

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "GOOGLE_PLACES",
    "status": "COMPLETED",
    "createdAt": "…"
  },
  "credits": { "creditsToCharge": 5, "creditsCharged": 5 },
  "response": {
    "places": [
      {
        "name": "Joey Gilbert Law",
        "position": 1,
        "placeId": "ChIJcW7HSupAmYARRnrM6Ap0UtU",
        "location": {
          "address": "405 Marsh Ave, Reno, NV 89509",
          "latitude": 39.519216,
          "longitude": -119.815709
        },
        "phoneNumber": "(775) 210-1501",
        "url": "https://joeygilbertlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=15371476068373133894",
        "reviews": [
          { "rating": 4.4, "count": 381, "providerName": "Google" }
        ],
        "category": "Criminal justice attorney",
        "snippet": "Joey is knowledgeable, straightforward, and fights hard for his clients.",
        "page": 1
      },
      {
        "name": "Viloria, Oliphant, Oster & Aman L.L.P.",
        "position": 2,
        "placeId": "ChIJv8KkdMlAmYARmINKFMPLxbs",
        "location": {
          "address": "327 California Ave, Reno, NV 89509",
          "latitude": 39.520335,
          "longitude": -119.81519
        },
        "phoneNumber": "(775) 515-8480",
        "url": "https://www.renonvlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=13530444694224012184",
        "reviews": [
          { "rating": 4.6, "count": 117, "providerName": "Google" }
        ],
        "category": "Personal injury attorney",
        "snippet": "Tom’s work ethic and knowledge of the legal system is beyond reproach.",
        "page": 1
      },
      "…"
    ],
    "pages": 5,
    "city": "Reno, Nevada, United States"
  }
}

task.statusstring

QUEUED、PROCESSING を経て、回答付きの COMPLETED か error 付きの FAILED で終わります。

credits.creditsChargedinteger

完了したタスクに請求されたクレジット。失敗したタスクは0です。

response.placesarray

Google の順に並んだ場所。name、ページをまたいで数える position、載っていた page に加え、Google が表示していれば placeId、location、phoneNumber、url、mapsUrl、reviews、category、snippet が入ります。

response.pagesinteger

読んだページ数（1ページ20件）、1〜5。このページ数分が課金されます。

結果を受け取る

リクエストすると status が QUEUED のタスクがすぐに返ります。status が COMPLETED か FAILED になるまで GET /v1/async/task/{id} で取得するか、webhook.url を指定して同じ task、credits、response をサーバーで受け取ります。結果はタスクの完了から24時間取得できます。

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

エラー

VALIDATION_ERRORHTTP 422

limit が1〜100の外にあるか、city が空か100文字を超えるか、city を uule または location と一緒に送りました。details に該当するフィールドが入ります。

MISSING_API_KEYHTTP 401

Authorization ヘッダーが欠けているか、キーが誤っている、期限切れ、または無効化済みです。

INSUFFICIENT_CREDITSHTTP 402

残高がタスクの料金を下回っています。クレジットを追加するかプランを上げてから、もう一度送ってください。

料金

20件の場所の1ページごとに1クレジットを使うため、100件では5クレジットです。送信時に limit に必要なクレジットを確保し、完了時に読んだページ分だけ差し引きます。2ページ目で終わった一覧は2クレジットです。