> ## 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: veja qual registro cada mecanismo de IA mostra para um estabelecimento > Pergunte ao ChatGPT, Gemini, Google, Copilot e Naver sobre um estabelecimento e leia o registro que cada mecanismo mostra: a base de mapas de onde ele vem, o que ele diz e onde difere dos dados do próprio estabelecimento. Use o Place Lookup para verificar como os mecanismos de IA mostram um estabelecimento, uma filial ou uma clínica. Cada mecanismo mostra lugares de uma base de mapas. Gemini, Copilot e a página de resultados do Google mostram registros do Google Maps, o Naver AI Tab mostra registros do Naver Place e o ChatGPT mostra registros de fontes como Yelp, Tripadvisor e Google Maps. Uma consulta mostra qual registro cada mecanismo usou e o que há de errado nele, para você saber qual cadastro corrigir. ## Envie uma consulta ```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" }' ``` A consulta faz duas perguntas a cada mecanismo. Cada pergunta é uma tarefa comum desse mecanismo, e a resposta as lista: ```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": { "...": "..." } } ] } ``` Leia a consulta com `GET /v1/place-lookup/{id}` até que `lookup.status` seja `COMPLETED`. A maioria das consultas termina em menos de dois minutos, então consulte a cada 5 a 10 segundos. Uma consulta não envia webhook. O schema da requisição está na [referência da API](/pt/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" ``` ## Campos da requisição | Campo | Obrigatório | Descrição | | - | - | - | | `place.name` | Sim | O nome do estabelecimento, de 1 a 200 caracteres. Para uma rede, inclua a filial, como `Anchorhead Coffee Downtown Seattle`. | | `place.address` | `address` ou `location` | O endereço, até 500 caracteres. | | `place.location` | `address` ou `location` | O pino do estabelecimento como `{ "latitude", "longitude" }` em graus decimais. Com ele, cada registro traz sua distância até o estabelecimento, e um pino fora do lugar é apontado. | | `place.phone` | Não | O telefone oficial em qualquer formato, até 50 caracteres. O telefone de cada registro é comparado com ele. | | `place.website` | Não | O site oficial, uma URL `http` ou `https`. O site de cada registro é comparado com ele por site. | | `place.googlePlaceId` | Não | O Google Place ID do estabelecimento, como `ChIJRXCfNwUVkFQRxraD8U-dANE`. Um registro com esse ID é o estabelecimento. | | `place.naverPlaceId` | Não | O Naver Place ID do estabelecimento, ou sua página em `map.naver.com` ou `place.naver.com`. Um registro com esse ID é o estabelecimento. | | `place.yelpUrl` | Não | A página `yelp.com/biz/...` do estabelecimento. Um registro com essa página do Yelp é o estabelecimento. | | `country` | Sim | O país do estabelecimento como código ISO 3166-1 alfa-2, como `US` ou `KR`. | | `engines` | Não | Mecanismos a consultar, sem repetição: `CHATGPT`, `GEMINI`, `GOOGLE`, `BING_COPILOT` e `NAVER_AI_TAB`. Padrão: os cinco para `KR` e os quatro primeiros nos demais países. `NAVER_AI_TAB` é só para `KR`. | | `idempotencyKey` | Não | O id da consulta, de 1 a 200 caracteres sem espaços no início ou no fim. Sem ele, o servidor gera um UUID. Veja [Reenvie uma consulta](#reenvie-uma-consulta). | | `priority` | Não | Inteiro de `1` a `10`, padrão `1`, aplicado a cada tarefa. Não garante a ordem de execução. | Outros campos, inclusive `webhook`, retornam `400 VALIDATION_ERROR`. ## Como uma consulta pergunta Cada mecanismo recebe duas perguntas. ChatGPT, Gemini e Copilot recebem o pedido de mostrar o estabelecimento em um mapa, na segunda vez com o endereço. Na página de resultados do Google, a busca é pela localização do estabelecimento e depois pelo nome, a partir do pino do próprio estabelecimento. O Naver AI Tab recebe a pergunta sobre a localização do estabelecimento e depois sobre o nome. | Mecanismo | Primeira pergunta | Segunda pergunta | | - | - | - | | `CHATGPT`, `GEMINI`, `BING_COPILOT` | `Show {name} on a map` | `Show {name}, {address} on a map` | | `GOOGLE` | `{name} location` | `{name}`, buscado a partir de `place.location` | Em `KR` as perguntas são em coreano, e a segunda pergunta ao ChatGPT é `Show {name} on a map` em inglês, porque o ChatGPT mostra o cartão de um estabelecimento coreano com mais frequência quando a pergunta é em inglês. Sem `place.address`, um mecanismo cuja segunda pergunta acrescenta o endereço repete a primeira. Sem `place.location`, a segunda busca do Google acrescenta o endereço fora de `KR`. `via[]` no resultado mostra cada pergunta como foi enviada. ## Leia o resultado A consulta do Canlis fica assim, reduzida aos campos principais: ```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 } } ``` O ChatGPT mostrou o registro do Yelp do restaurante. Gemini e Copilot mostraram o mesmo registro do Google Maps, com o mesmo Place ID. A página de resultados do Google não mostrou nenhum lugar nas duas perguntas, então seu `found` é `false`. ### `engines[]` | Campo | Descrição | | - | - | | `engine` | O mecanismo consultado. | | `status` | `PROCESSING` até as duas perguntas terminarem, depois `COMPLETED`. `FAILED` quando as duas falharam. | | `found` | `true` assim que uma resposta mostra o estabelecimento. `false` quando as duas perguntas terminaram e nenhuma resposta o mostrou. `null` enquanto uma pergunta ainda está em andamento e quando as duas falharam. | | `via[]` | Cada pergunta como foi enviada: `prompt` ou `query`, `location` quando enviado, `taskId` quando a pergunta começa, `status`, `collectedAt`, `places` (quantos lugares a resposta mostrou) e `error` em uma pergunta que falhou. `status` é `PENDING` enquanto a pergunta espera espaço no seu plano. | | `record` | O registro do estabelecimento: entre os lugares das duas respostas, o que melhor corresponde ao estabelecimento. Presente quando `found` é `true`. | | `issues` | O que está errado em `record`. Presente só quando há algo. | ### `record` | Campo | Descrição | | - | - | | `source` | A base de mapas do registro: `google_maps`, `naver_place`, `yelp`, `tripadvisor`, ou `unknown` quando a resposta não mostra. | | `placeId`, `url` | O ID e a página do registro na fonte, como um Google Place ID e seu link do Google Maps. | | `name`, `address`, `latitude`, `longitude`, `phone`, `website` | Os dados que o mecanismo mostra. Só aparecem os campos que a resposta traz. | | `category`, `rating`, `reviewCount`, `openState`, `image`, `description` | Outros dados como o mecanismo os mostra, quando existem. | | `position` | A ordem do registro entre os lugares da resposta, a partir de 1. | | `provider` | Só ChatGPT: a fonte que o ChatGPT indica para o registro, como `yelp-feed` ou `bright-feed`. | | `localName` | Só ChatGPT: o outro nome do registro, como o nome coreano de um estabelecimento coreano. | | `resolvedBy` | Só ChatGPT: `address` quando o ChatGPT encontrou o registro por um endereço que o modelo escreveu. Esse registro pode ser de outro estabelecimento nesse endereço. | | `closed` | Só ChatGPT: `permanently` ou `temporarily` quando o registro está marcado como fechado. | | `match` | Por que o registro é o estabelecimento. `by` lista os dados que coincidem: `place_id`, `phone`, `website`, `location`, `address` e `name`. `nameScore` é a semelhança do nome, de 0 a 1, e `distanceMeters`, a distância de `place.location` até o pino do registro. | ### `issues` | Problema | Significado | | - | - | | `phone_mismatch` | O telefone do registro difere de `place.phone` ou, sem ele, do número que a maioria dos outros mecanismos mostra. | | `website_mismatch` | O site do registro é outro site que não `place.website` ou, sem ele, que não o site que a maioria dos outros mecanismos mostra. | | `location_mismatch` | O pino do registro está a mais de 300 m de `place.location`. | | `other_business_record` | O registro provavelmente é de outro estabelecimento no local do seu: telefone e site diferem, ou o ChatGPT o encontrou pelo endereço e um dos dois difere. | | `closed_permanently`, `closed_temporarily` | O ChatGPT mostra o lugar como fechado. | Um número que todas as filiais de uma rede divulgam, como um número gratuito, não é comparado. ### `summary` e `credits` | Campo | Descrição | | - | - | | `summary.foundIn` | Mecanismos que mostraram o estabelecimento. | | `summary.notFoundIn` | Mecanismos cujas respostas terminaram sem ele. | | `summary.failed` | Mecanismos em que as duas perguntas falharam. | | `summary.pending` | Mecanismos que ainda estão respondendo e não mostraram o estabelecimento. | | `summary.differences[]` | Onde os registros dos mecanismos divergem. `field` é `name`, `phone`, `website` ou `location`, e `values[]` lista cada `value` com os `engines` que o mostram. Uma entrada `location` aparece quando dois pinos estão a mais de 300 m um do outro e traz `spreadMeters`, a maior distância entre eles. | | `credits` | Créditos cobrados até agora pelas perguntas da consulta. | `lookup.status` é `PROCESSING` até todos os mecanismos terminarem, depois `COMPLETED`. O resultado é avaliado a partir das respostas salvas a cada leitura, e uma consulta pode ser lida por 24 horas depois que suas tarefas terminam. ## Reenvie uma consulta Cada pergunta é uma tarefa cuja chave é `{lookup id}:{engine}:{ask}`, como `canlis-2026-10:GEMINI:2`. Envie a mesma requisição com o mesmo `idempotencyKey`, e a consulta retorna as tarefas que já tem e envia as perguntas que ainda não têm tarefa, como as recusadas por falta de créditos. O mesmo id com outro estabelecimento, país ou lista de mecanismos retorna `409 RESOURCE_ALREADY_EXISTS` e não cria nada. Para consultar o estabelecimento de novo mais tarde, use um novo `idempotencyKey`. ## Concorrência do plano Cada pergunta conta como uma tarefa no limite de concorrência do seu plano. Uma consulta começa as perguntas para as quais seu plano tem espaço, e as demais esperam em `tasks[]` com `status: "PENDING"`: ```json theme={"theme":"css-variables"} { "engine": "GEMINI", "ask": 1, "success": true, "status": "PENDING" } ``` Uma pergunta em espera começa sozinha à medida que suas tarefas em andamento terminam, em até um minuto ou na próxima vez que você ler a consulta, então uma única requisição executa a consulta inteira. No plano Free, que permite 2 tarefas simultâneas, uma consulta roda duas perguntas por vez e leva alguns minutos. Os planos pagos começam em 50 tarefas simultâneas, então uma consulta inteira começa de uma vez enquanto sua conta tiver espaço. As perguntas também esperam enquanto a fila de um mecanismo está cheia ou a chave atingiu seu limite diário de créditos. O preço de uma pergunta é reservado quando ela começa. Se a chave que enviou a consulta for revogada ou expirar antes, as perguntas em espera terminam como `FAILED` com `API_KEY_INACTIVE` e custam 0. Veja [Créditos e limites](/pt/concepts/credits-and-limits.md#concorrência-do-plano). ## Erros e cobrança Uma consulta aos mecanismos padrão do país custa 10 créditos. Cada pergunta paga sua parte: 1 crédito para cada uma das 10 perguntas em `KR` e 1,25 para cada uma das 8 nos demais países. Uma consulta a menos mecanismos paga as perguntas que envia. O preço de cada pergunta é reservado no envio e cobrado quando ela termina, e uma pergunta que falhou custa 0. Veja [Créditos e limites](/pt/concepts/credits-and-limits.md). ### Recusas no envio | Status | Código | Causa | | - | - | - | | `400` | `VALIDATION_ERROR` | O corpo não é JSON válido, um campo está ausente ou inválido, um campo desconhecido ou `webhook` foi enviado, ou `NAVER_AI_TAB` foi consultado fora de `KR`. `details` indica o campo. | | `409` | `RESOURCE_ALREADY_EXISTS` | O `idempotencyKey` corresponde a uma consulta de outro estabelecimento, país ou lista de mecanismos. | Quando todas as perguntas são recusadas, a primeira recusa é a resposta, com seu próprio status, como `402 INSUFFICIENT_CREDITS` ou `403 KEY_SCOPE_DENIED`, e nada é criado. Quando algumas são admitidas, a resposta é `200` e cada pergunta recusada traz seu `error` em `tasks[]`: ```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" } } ``` ### Leia uma consulta `GET /v1/place-lookup/{id}` retorna `404 RESOURCE_NOT_FOUND` para um id que sua conta não usou e para uma consulta cujas tarefas passaram da janela de 24 horas. Uma pergunta que falhou mostra `status: "FAILED"` em `via[]` e um `error` que começa com seu código, como `ENGINE_NO_RESULT`. Os códigos são os das tarefas do mecanismo, e uma pergunta em espera que termina antes de começar traz `API_KEY_INACTIVE` ou `INSUFFICIENT_CREDITS`. Veja [Erros](/pt/concepts/errors.md). ## Próximos passos > **[ChatGPT](/pt/engines/chatgpt.md)** > > Os cartões de lugares que o ChatGPT mostra, em `map`. > **[Lotes e grades](/pt/concepts/bulk-submission.md)** > > Faça a mesma pergunta a partir de cada ponto de uma grade em torno de um estabelecimento. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.