> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Place Lookup: AIエンジンごとに店舗がどの掲載情報で表示されるかを確かめる

> 1つの店舗を ChatGPT、Gemini、Google、Copilot、Naver に尋ね、エンジンごとの店舗の掲載情報を読み取ります。情報の出典の地図データベース、表示内容、店舗の公式情報と異なる点がわかります。

Place Lookup は、AIエンジンが1つの店舗、支店、クリニックをどう表示するかを確かめるために使います。各エンジンは地図データベースの掲載情報を表示します。Gemini、Copilot、Google の検索結果ページは Google マップの情報を、Naver AI Tab は Naver Place の情報を、ChatGPT は Yelp、Tripadvisor、Google マップなどのフィードの情報を表示します。照会の結果から、各エンジンがどの掲載情報を使い、何が誤っているかがわかるので、どの掲載情報を直せばよいか判断できます。

## 照会を送信する

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/place-lookup \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "place": {
      "name": "Canlis",
      "address": "2576 Aurora Ave N, Seattle, WA 98109",
      "location": { "latitude": 47.6430534, "longitude": -122.3467361 },
      "phone": "(206) 283-3313",
      "website": "https://canlis.com/"
    },
    "country": "US",
    "idempotencyKey": "canlis-2026-10"
  }'
```

照会はエンジンごとに2つの質問を送ります。各質問はそのエンジンの通常のタスクで、レスポンスがその一覧を返します。

```json theme={"theme":"css-variables"}
{
  "success": true,
  "lookup": { "id": "canlis-2026-10" },
  "tasks": [
    {
      "engine": "CHATGPT",
      "ask": 1,
      "success": true,
      "task": {
        "id": "9d02deef-...",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "2026-10-20T09:00:00.000Z",
        "idempotencyKey": "canlis-2026-10:CHATGPT:1"
      }
    },
    { "engine": "CHATGPT", "ask": 2, "success": true, "task": { "...": "..." } },
    { "engine": "GEMINI", "ask": 1, "success": true, "task": { "...": "..." } }
  ]
}
```

`lookup.status` が `COMPLETED` になるまで `GET /v1/place-lookup/{id}` で照会を読み取ってください。ほとんどの照会は2分以内に終わるので、5〜10秒ごとにポーリングしてください。照会は webhook を送りません。リクエストのスキーマは [API リファレンス](/ja/api-reference/place-lookup.md)にあります。

```bash theme={"theme":"css-variables"}
curl https://api.querying.ai/v1/place-lookup/canlis-2026-10 \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

## リクエストフィールド

| フィールド | 必須 | 説明 |
| - | - | - |
| `place.name` | はい | 店舗名、1〜200文字。チェーン店は支店名まで含めます。例: `Anchorhead Coffee Downtown Seattle`。 |
| `place.address` | `address` または `location` | 住所、最大500文字。 |
| `place.location` | `address` または `location` | 店舗のピンの位置 `{ "latitude", "longitude" }`（10進数の度）。指定すると、各掲載情報に店舗からの距離が付き、ずれたピンが報告されます。 |
| `place.phone` | いいえ | 公式の電話番号、最大50文字、形式は自由。各掲載情報の電話番号をこれと比べます。 |
| `place.website` | いいえ | 公式ウェブサイト、`http` または `https` の URL。各掲載情報のウェブサイトをサイト単位で比べます。 |
| `place.googlePlaceId` | いいえ | 店舗の Google Place ID。例: `ChIJRXCfNwUVkFQRxraD8U-dANE`。この ID の掲載情報はその店舗です。 |
| `place.naverPlaceId` | いいえ | 店舗の Naver Place ID、またはその場所の `map.naver.com` か `place.naver.com` のページ。この ID の掲載情報はその店舗です。 |
| `place.yelpUrl` | いいえ | 店舗の `yelp.com/biz/...` ページ。この事業者の掲載情報はその店舗です。 |
| `country` | はい | 店舗がある国の ISO 3166-1 alpha-2 コード。例: `US`、`KR`。 |
| `engines` | いいえ | 尋ねるエンジン。`CHATGPT`、`GEMINI`、`GOOGLE`、`BING_COPILOT`、`NAVER_AI_TAB` から重複なく選びます。既定は `KR` なら5つすべて、それ以外の国は最初の4つです。`NAVER_AI_TAB` は `KR` 専用です。 |
| `idempotencyKey` | いいえ | 照会の id。前後に空白のない1〜200文字です。指定しないとサーバーが UUID を作ります。[照会を再送信する](#照会を再送信する)を参照してください。 |
| `priority` | いいえ | 整数 `1`〜`10`、既定 `1`。すべてのタスクに付きます。実行順序は保証しません。 |

ほかのフィールドは、`webhook` も含めて `400 VALIDATION_ERROR` を返します。

## 照会の質問のしかた

各エンジンに2つの質問を送ります。ChatGPT、Gemini、Copilot には店舗を地図で表示するよう尋ね、2つ目の質問では住所を加えます。Google の検索結果ページでは店舗の場所を検索し、続いて店舗のピンの位置から店舗名を検索します。Naver AI Tab には店舗の場所を尋ね、続いて店舗名を尋ねます。

| エンジン | 1つ目の質問 | 2つ目の質問 |
| - | - | - |
| `CHATGPT`、`GEMINI`、`BING_COPILOT` | `Show {name} on a map` | `Show {name}, {address} on a map` |
| `GOOGLE` | `{name} location` | `place.location` から検索した `{name}` |

`KR` の店舗には韓国語で質問します。ただし ChatGPT の2つ目の質問は英語の `Show {name} on a map` です。ChatGPT は英語で尋ねたほうが韓国の店舗のプレイスカードを多く表示するためです。`place.address` がない場合、2つ目の質問に住所を加えるエンジンは1つ目の質問を2回尋ねます。`place.location` がない場合、`KR` 以外では Google の2回目の検索に住所を加えます。結果の `via[]` に、実際に送った質問がそのまま入ります。

## 結果を読む

Canlis の照会を主なフィールドだけに絞ると、次のようになります。

```json theme={"theme":"css-variables"}
{
  "success": true,
  "lookup": {
    "id": "canlis-2026-10",
    "status": "COMPLETED",
    "place": {
      "name": "Canlis",
      "address": "2576 Aurora Ave N, Seattle, WA 98109",
      "location": { "latitude": 47.6430534, "longitude": -122.3467361 },
      "phone": "(206) 283-3313",
      "website": "https://canlis.com/"
    },
    "country": "US",
    "engines": [
      {
        "engine": "CHATGPT",
        "status": "COMPLETED",
        "found": true,
        "via": [
          {
            "taskType": "CHATGPT",
            "prompt": "Show Canlis on a map",
            "taskId": "9d02deef-...",
            "status": "COMPLETED",
            "collectedAt": "2026-10-19T16:38:48.957Z",
            "places": 1
          },
          {
            "taskType": "CHATGPT",
            "prompt": "Show Canlis, 2576 Aurora Ave N, Seattle, WA 98109 on a map",
            "taskId": "91505c8f-...",
            "status": "COMPLETED",
            "collectedAt": "2026-10-19T16:39:04.194Z",
            "places": 1
          }
        ],
        "record": {
          "position": 1,
          "name": "Canlis",
          "source": "yelp",
          "provider": "yelp-feed",
          "url": "https://www.yelp.com/biz/canlis-seattle?adjust_creative=openai",
          "address": "2576 Aurora Ave N, Seattle, WA 98109, United States",
          "latitude": 47.6430933,
          "longitude": -122.3467535,
          "phone": "+1 206-283-3313",
          "rating": 4,
          "reviewCount": 1935,
          "website": "https://canlis.com/",
          "match": {
            "same": true,
            "by": ["phone", "website", "location", "address", "name"],
            "nameScore": 1,
            "distanceMeters": 5
          }
        }
      },
      {
        "engine": "GEMINI",
        "status": "COMPLETED",
        "found": true,
        "via": [{ "...": "..." }],
        "record": {
          "position": 1,
          "name": "Canlis",
          "source": "google_maps",
          "placeId": "ChIJRXCfNwUVkFQRxraD8U-dANE",
          "url": "https://maps.google.com/?cid=15060210120606856902",
          "phone": "+1 206-283-3313",
          "rating": 4.6,
          "reviewCount": 2892,
          "website": "https://canlis.com/",
          "match": {
            "same": true,
            "by": ["phone", "website", "location", "address", "name"],
            "nameScore": 1,
            "distanceMeters": 5
          }
        }
      },
      {
        "engine": "GOOGLE",
        "status": "COMPLETED",
        "found": false,
        "via": [
          {
            "taskType": "GOOGLE",
            "query": "Canlis location",
            "taskId": "6d3c3a73-...",
            "status": "COMPLETED",
            "collectedAt": "2026-10-19T16:38:43.932Z",
            "places": 0
          },
          {
            "taskType": "GOOGLE",
            "query": "Canlis",
            "location": { "latitude": 47.6430534, "longitude": -122.3467361 },
            "taskId": "980a858a-...",
            "status": "COMPLETED",
            "collectedAt": "2026-10-19T16:38:48.902Z",
            "places": 0
          }
        ]
      },
      {
        "engine": "BING_COPILOT",
        "status": "COMPLETED",
        "found": true,
        "via": [{ "...": "..." }],
        "record": {
          "name": "Canlis",
          "source": "google_maps",
          "placeId": "ChIJRXCfNwUVkFQRxraD8U-dANE",
          "openState": "Closed · Opens 5 PM Tue",
          "...": "..."
        }
      }
    ],
    "summary": {
      "foundIn": ["CHATGPT", "GEMINI", "BING_COPILOT"],
      "notFoundIn": ["GOOGLE"],
      "failed": [],
      "pending": [],
      "differences": []
    },
    "credits": 10
  }
}
```

ChatGPT はこのレストランの Yelp の掲載情報を表示しました。Gemini と Copilot は、同じ Place ID を持つ同じ Google マップの掲載情報を表示しました。Google の検索結果ページはどちらの質問でも場所を表示しなかったので、`found` は `false` です。

### `engines[]`

| フィールド | 説明 |
| - | - |
| `engine` | 尋ねたエンジン。 |
| `status` | 2つの質問が終わるまでは `PROCESSING`、終わると `COMPLETED`。両方の質問が失敗すると `FAILED`。 |
| `found` | 回答が店舗を表示すると `true`。両方の質問が終わり、どの回答にも店舗がなければ `false`。質問がまだ実行中のときと、両方が失敗したときは `null`。 |
| `via[]` | 送った質問。`prompt` または `query`、送った場合は `location`、質問が始まった後の `taskId`、`status`、`collectedAt`、`places`（回答が表示した場所の数）、失敗した質問の `error` が入ります。質問がプランの空きを待つ間、`status` は `PENDING` です。 |
| `record` | 店舗の掲載情報。2つの回答の場所のうち、店舗と最も強く一致するものです。`found` が `true` のときにあります。 |
| `issues` | `record` の誤り。誤りがあるときだけあります。 |

### `record`

| フィールド | 説明 |
| - | - |
| `source` | 掲載情報の地図データベース。`google_maps`、`naver_place`、`yelp`、`tripadvisor` のいずれかで、回答からわからなければ `unknown`。 |
| `placeId`、`url` | 出典での ID とページ。例: Google Place ID と Google マップのリンク。 |
| `name`、`address`、`latitude`、`longitude`、`phone`、`website` | エンジンが表示した情報。回答にあるフィールドだけが入ります。 |
| `category`、`rating`、`reviewCount`、`openState`、`image`、`description` | エンジンが表示したその他の情報。あるときだけ入ります。 |
| `position` | 回答の場所の中での順番。1から数えます。 |
| `provider` | ChatGPT のみ: ChatGPT が示したフィード。例: `yelp-feed`、`bright-feed`。 |
| `localName` | ChatGPT のみ: 場所の別の名前。例: 韓国の店舗の韓国語名。 |
| `resolvedBy` | ChatGPT のみ: モデルが書いた住所から ChatGPT が場所を見つけた場合は `address`。このような掲載情報は、その住所にある別の事業者のものであることがあります。 |
| `closed` | ChatGPT のみ: 閉業の表示があれば `permanently` または `temporarily`。 |
| `match` | この掲載情報を店舗と判断した根拠。`by` は一致した情報（`place_id`、`phone`、`website`、`location`、`address`、`name`）、`nameScore` は 0〜1 の名前の類似度、`distanceMeters` は `place.location` から掲載情報のピンまでの距離です。 |

### `issues`

| 問題 | 意味 |
| - | - |
| `phone_mismatch` | 電話番号が `place.phone` と異なります。`place.phone` がなければ、ほかのエンジンの多くが表示した番号と異なります。 |
| `website_mismatch` | ウェブサイトが `place.website` と別のサイトです。`place.website` がなければ、ほかのエンジンの多くが表示したサイトと異なります。 |
| `location_mismatch` | ピンが `place.location` から 300 m を超えて離れています。 |
| `other_business_record` | 店舗の位置にある別の事業者の掲載情報である可能性が高いです。電話番号とウェブサイトがどちらも異なるか、ChatGPT が住所から見つけ、どちらか一方が異なります。 |
| `closed_permanently`、`closed_temporarily` | ChatGPT がその場所を閉業と表示しています。 |

フリーダイヤルのように、チェーンのすべての支店が載せる番号は比べません。

### `summary` と `credits`

| フィールド | 説明 |
| - | - |
| `summary.foundIn` | 店舗を表示したエンジン。 |
| `summary.notFoundIn` | 回答が終わり、店舗がなかったエンジン。 |
| `summary.failed` | 両方の質問が失敗したエンジン。 |
| `summary.pending` | まだ回答中で、店舗をまだ表示していないエンジン。 |
| `summary.differences[]` | エンジンの掲載情報どうしが異なる箇所。`field` は `name`、`phone`、`website`、`location` のいずれかで、`values[]` は値（`value`）ごとにその値を表示した `engines` を持ちます。`location` の項目は2つのピンが 300 m を超えて離れているときに現れ、最も離れた2つのピンの距離 `spreadMeters` が付きます。 |
| `credits` | これまでにこの照会の質問に請求されたクレジット。 |

`lookup.status` はすべてのエンジンが終わるまでは `PROCESSING`、終わると `COMPLETED` です。結果は読み取るたびに保存された回答から判定し直され、照会はタスクの完了後24時間読み取れます。

## 照会を再送信する

各質問は、キーが `{lookup id}:{engine}:{ask}` のタスクです。例: `canlis-2026-10:GEMINI:2`。同じリクエストを同じ `idempotencyKey` で再送信すると、既存のタスクを返し、クレジット不足で拒否された質問など、まだタスクのない質問を送ります。同じ id で別の店舗、国、エンジンの組み合わせを送ると `409 RESOURCE_ALREADY_EXISTS` を返し、何も作りません。後で同じ店舗をもう一度照会するときは、新しい `idempotencyKey` を使ってください。

## プランの同時実行数

各質問はプランの同時実行数のタスク1つとして数えます。照会はプランに空きがある分だけ質問を始め、残りは `tasks[]` で `status: "PENDING"` として待ちます。

```json theme={"theme":"css-variables"}
{ "engine": "GEMINI", "ask": 1, "success": true, "status": "PENDING" }
```

待っている質問は、実行中のタスクが終わりしだい1分以内に、または次に照会を読んだときに自動で始まります。1回のリクエストで照会全体が実行されます。同時実行タスクが2つの Free プランでは質問を2つずつ実行し、数分かかります。有料プランは同時実行タスク50から始まるので、アカウントに空きがあれば照会全体が一度に始まります。エンジンのキューが満杯のときや、キーが1日のクレジット上限に達したときも質問は待ちます。質問の価格は質問が始まるときに保留します。その前に照会を送ったキーが失効または期限切れになると、待っていた質問は `API_KEY_INACTIVE` で `FAILED` になり、0クレジットです。[クレジットと上限](/ja/concepts/credits-and-limits.md#プランの同時実行数)を参照してください。

## エラーと課金

国の既定のエンジンすべてに尋ねる照会は10クレジットです。各質問がその分担分を払います。`KR` では10の質問それぞれに1クレジット、その他の国では8の質問それぞれに1.25クレジットです。エンジンを絞った照会は、送った質問の分だけ払います。各質問の価格は送信時に確保され、完了時に請求されます。失敗した質問は0です。[クレジットと上限](/ja/concepts/credits-and-limits.md)を参照してください。

### 送信時の拒否

| ステータス | コード | 原因 |
| - | - | - |
| `400` | `VALIDATION_ERROR` | 本文が有効な JSON でない、フィールドがないか不正、不明なフィールドや `webhook` を送った、または `KR` 以外で `NAVER_AI_TAB` を尋ねました。`details` がフィールドを示します。 |
| `409` | `RESOURCE_ALREADY_EXISTS` | `idempotencyKey` が別の店舗、国、エンジンの組み合わせの照会を指しています。 |

すべての質問が拒否されると、最初の拒否がそのステータスのままレスポンスになり、何も作られません。例: `402 INSUFFICIENT_CREDITS`、`403 KEY_SCOPE_DENIED`。一部の質問が受け付けられた場合、レスポンスは `200` で、拒否された質問は `tasks[]` に `error` を持ちます。

```json theme={"theme":"css-variables"}
{
  "engine": "GOOGLE",
  "ask": 2,
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "insufficient credits (need 1.25)",
    "timestamp": "2026-10-20T09:00:00.000Z"
  }
}
```

### 照会の読み取り

アカウントで使っていない id と、タスクが24時間を過ぎた照会には、`GET /v1/place-lookup/{id}` が `404 RESOURCE_NOT_FOUND` を返します。失敗した質問は `via[]` に `status: "FAILED"` と、コードで始まる `error` を示します。例: `ENGINE_NO_RESULT`。コードはそのエンジンのタスクと同じで、始まる前に終わった待機中の質問は `API_KEY_INACTIVE` か `INSUFFICIENT_CREDITS` を持ちます。[エラー](/ja/concepts/errors.md)を参照してください。

## 次のステップ

> **[ChatGPT](/ja/engines/chatgpt.md)**
>
> ChatGPT が表示するプレイスカード、`map`。

> **[バッチとグリッド](/ja/concepts/bulk-submission.md)**
>
> 店舗の周りのグリッドの各地点から同じプロンプトを尋ねます。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.