> ## 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 엔진마다 매장을 어떤 장소 정보로 보여주는지 확인

> 매장 하나를 ChatGPT, Gemini, Google, Copilot, 네이버에 묻고 엔진마다 그 매장의 장소 정보를 읽습니다. 정보가 어느 지도 DB에서 왔는지, 무엇을 보여주는지, 매장의 공식 정보와 어디가 다른지 알려줍니다.

Place Lookup으로 AI 엔진이 매장, 지점, 병원 하나를 어떻게 보여주는지 확인합니다. 엔진은 각자 지도 DB의 장소 정보를
보여줍니다. Gemini, Copilot, Google 검색 결과 페이지는 Google 지도 정보를, 네이버 AI 탭은 네이버 플레이스 정보를, 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"
  }'
```

조회는 엔진마다 질문 두 개를 보냅니다. 질문 하나가 그 엔진의 일반 태스크이고, 응답이 그 목록을 돌려줍니다.

```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 레퍼런스](/ko/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" }`(십진 도수). 보내면 장소 정보마다 매장까지의 거리가 붙고, 잘못 찍힌 핀을 알려줍니다. |
| `place.phone` | 아니요 | 공식 전화번호, 최대 50자, 형식 자유. 장소 정보의 전화번호를 이 번호와 비교합니다. |
| `place.website` | 아니요 | 공식 웹사이트, `http` 또는 `https` URL. 장소 정보의 웹사이트를 사이트 단위로 비교합니다. |
| `place.googlePlaceId` | 아니요 | 매장의 Google Place ID. 예: `ChIJRXCfNwUVkFQRxraD8U-dANE`. 이 ID의 장소 정보는 그 매장입니다. |
| `place.naverPlaceId` | 아니요 | 매장의 네이버 플레이스 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`이면 다섯 개 모두, 그 밖의 국가는 앞의 네 개입니다. `NAVER_AI_TAB`은 `KR`에만 씁니다. |
| `idempotencyKey` | 아니요 | 조회 id. 앞뒤 공백 없는 1–200자입니다. 없으면 서버가 UUID를 만듭니다. [조회 다시 보내기](#조회-다시-보내기)를 참고하세요. |
| `priority` | 아니요 | 정수 `1`–`10`, 기본 `1`. 모든 태스크에 붙습니다. 실행 순서를 보장하지 않습니다. |

다른 필드는 `webhook`을 포함해 `400 VALIDATION_ERROR`를 반환합니다.

## 조회가 묻는 방식

엔진마다 질문 두 개를 보냅니다. ChatGPT, Gemini, Copilot에는 매장을 지도로 보여달라고 묻고, 두 번째 질문에는 주소를
붙입니다. Google 검색 결과 페이지에서는 매장 위치를 검색하고, 이어서 매장 핀 좌표에서 매장 이름을 검색합니다. 네이버 AI 탭에는
매장 위치를 묻고, 이어서 매장 이름을 묻습니다.

| 엔진 | 첫 질문 | 두 번째 질문 |
| - | - | - |
| `CHATGPT`, `GEMINI`, `BING_COPILOT` | `Show {name} on a map` | `Show {name}, {address} on a map` |
| `GOOGLE` | `{name} location` | `place.location`에서 검색한 `{name}` |

`KR` 매장은 한국어로 묻습니다. ChatGPT의 두 번째 질문만 영어 `Show {name} on a map`입니다. ChatGPT가 영어 질문에 한국
매장의 장소 카드를 더 자주 보여주기 때문입니다. `place.address`가 없으면 두 번째 질문에 주소를 붙이는 엔진은 첫 질문을 한 번
더 묻습니다. `place.location`이 없으면 `KR` 밖에서는 Google의 두 번째 검색에 주소를 붙입니다. 결과의 `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` | 두 질문이 끝나기 전에는 `PROCESSING`, 끝나면 `COMPLETED`입니다. 두 질문이 모두 실패하면 `FAILED`입니다. |
| `found` | 답변이 매장을 보여주면 `true`입니다. 두 질문이 끝났는데 어느 답변에도 매장이 없으면 `false`, 질문이 아직 실행 중이거나 두 질문이 모두 실패하면 `null`입니다. |
| `via[]` | 보낸 질문입니다. `prompt` 또는 `query`, 보낸 경우 `location`, 질문이 시작된 뒤의 `taskId`, `status`, `collectedAt`, `places`(답변이 보여준 장소 수), 실패한 질문의 `error`가 들어 있습니다. 질문이 요금제의 빈자리를 기다리는 동안 `status`는 `PENDING`입니다. |
| `record` | 매장의 장소 정보. 두 답변의 장소 중 매장과 가장 강하게 맞는 것입니다. `found`가 `true`일 때 있습니다. |
| `issues` | `record`에서 틀린 점. 틀린 점이 있을 때만 있습니다. |

### `record`

| 필드 | 설명 |
| - | - |
| `source` | 장소 정보의 지도 DB입니다. `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` 항목은 두 핀이 300 m 넘게 떨어져 있을 때 나오고, 가장 먼 두 핀의 거리 `spreadMeters`를 함께 줍니다. |
| `credits` | 지금까지 이 조회의 질문에 청구된 크레딧. |

`lookup.status`는 모든 엔진이 끝나기 전에는 `PROCESSING`, 끝나면 `COMPLETED`입니다. 결과는 읽을 때마다 저장된 답변으로
다시 판정하고, 조회는 태스크가 끝난 뒤 24시간 동안 읽을 수 있습니다.

## 조회 다시 보내기

질문마다 키가 `{lookup id}:{engine}:{ask}`인 태스크입니다. 예: `canlis-2026-10:GEMINI:2`. 같은 요청을 같은
`idempotencyKey`로 다시 보내면 이미 있는 태스크를 돌려주고, 크레딧이 부족해 거절된 질문처럼 아직 태스크가 없는 질문을 보냅니다. 같은 id로 다른
매장, 국가, 엔진 목록을 보내면 `409 RESOURCE_ALREADY_EXISTS`를 반환하고 아무것도 만들지 않습니다. 나중에 같은 매장을 다시
조회하려면 새 `idempotencyKey`를 쓰세요.

## 요금제 동시 실행 한도

질문 하나가 요금제 동시 실행 한도에서 태스크 하나로 셉니다. 조회는 요금제에 남은 자리만큼 질문을 시작하고, 나머지는
`tasks[]`에서 `status: "PENDING"`으로 기다립니다.

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

기다리는 질문은 실행 중인 태스크가 끝나는 대로 1분 안에, 또는 조회를 다음에 읽을 때 저절로 시작합니다. 요청 한 번으로 조회
전체가 실행됩니다. 동시 실행 태스크가 2개인 Free 요금제에서는 질문을 두 개씩 실행해 몇 분이 걸립니다. 유료 요금제는 동시 실행
태스크 50개부터라 계정에 자리가 있으면 조회 전체가 한 번에 시작합니다. 엔진 대기열이 가득 찼거나 키가 하루 크레딧 한도를 다 쓴
동안에도 질문이 기다립니다. 질문의 가격은 질문이 시작될 때 보류합니다. 그 전에 조회를 보낸 키가 폐기되거나 만료되면 기다리던
질문은 `API_KEY_INACTIVE`로 `FAILED`가 되고 0크레딧입니다.
[크레딧과 한도](/ko/concepts/credits-and-limits.md#요금제-동시-실행-한도)를 참고하세요.

## 오류와 과금

국가 기본 엔진에 모두 묻는 조회는 10크레딧입니다. 질문마다 그 몫을 냅니다. `KR`은 질문 10개에 1크레딧씩, 그 밖의 국가는
질문 8개에 1.25크레딧씩입니다. 엔진을 일부만 고른 조회는 보낸 질문만큼만 냅니다. 질문의 가격은 제출할 때 보류하고 완료되면
청구하며, 실패한 질문은 0입니다. [크레딧과 한도](/ko/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`를 담습니다. [오류](/ko/concepts/errors.md)를 참고하세요.

## 다음 단계

> **[ChatGPT](/ko/engines/chatgpt.md)**
>
> ChatGPT가 보여주는 장소 카드, `map`.

> **[배치와 그리드](/ko/concepts/bulk-submission.md)**
>
> 매장 주변 격자의 모든 지점에서 같은 프롬프트를 묻습니다.


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