Chegou o Place Lookup

Uma chamada pergunta ao ChatGPT, Gemini, Google, Copilot e, na Coreia, ao Naver sobre sua loja, e devolve o registro de cada mecanismo, a base de mapas de onde ele vem e cada dado que difere do seu.

O que você recebe

• POST /v1/place-lookup recebe uma loja, com nome e endereço ou ponto no mapa, além de telefone, site e IDs de lugar se você os tiver, e pergunta por ela a CHATGPT, GEMINI, GOOGLE, BING_COPILOT e, para lojas em KR, NAVER_AI_TAB.
• GET /v1/place-lookup/{id} devolve o record da loja em cada mecanismo: sua source, como google_maps, naver_place ou yelp, seu placeId e página, e o nome, endereço, telefone, site e nota que o mecanismo mostra.
• issues aponta o que está errado num registro: phone_mismatch, website_mismatch, location_mismatch, other_business_record ou um registro marcado como fechado.
• summary lista os mecanismos que mostraram a loja e as differences entre seus registros, e credits mostra quanto a consulta já cobrou.

Como funciona

Cada mecanismo recebe duas perguntas, como Show Canlis on a map e a mesma com o endereço, e cada uma roda como uma tarefa comum desse mecanismo. Para lojas em KR, as perguntas são em coreano e a segunda pergunta ao ChatGPT em inglês. Entre os lugares das respostas, o que coincide com a loja por ID de lugar, telefone, site, ponto, endereço e nome é o registro da loja, e match lista os dados que coincidem. A consulta é avaliada de novo com as respostas salvas a cada leitura, e a maioria termina em até dois minutos.

Onde ajuda

• Encontrar o registro de onde vem um telefone errado. Um erro num registro do Google Maps aparece em todos os mecanismos que leem esse registro, e a consulta o aponta.
• Saber qual base de mapas cada mecanismo lê no seu mercado. Num teste com 20 lojas nos EUA, o ChatGPT mostrou registros do Yelp para 15.
• Verificar cada filial de uma rede antes de uma campanha local, com uma consulta por filial.

Envie a requisição

Envie a requisição com a sua chave de API no cabeçalho Authorization.

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"
  }'

Campos da requisição

place.namestringObrigatório

O nome da loja, de 1 a 200 caracteres. Para uma rede, inclua a filial.

place.addressstring

O endereço, até 500 caracteres. A consulta precisa dele, de place.location ou dos dois.

place.locationobject

O pino da loja, com latitude e longitude. Com ele, cada registro traz a distância até a loja, e um pino a mais de 300 m é apontado.

place.phonestring

O telefone oficial, em qualquer formato. O telefone de cada registro é comparado com ele.

place.websitestring

O site oficial, uma URL http ou https. O site de cada registro é comparado com ele por site.

place.googlePlaceIdstring

O Google Place ID da loja. Um registro com esse ID é a loja.

place.naverPlaceIdstring

O Naver Place ID da loja, ou sua página em map.naver.com ou place.naver.com. Um registro com esse ID é a loja.

place.yelpUrlstring

A página yelp.com/biz/… da loja. Um registro dessa página do Yelp é a loja.

countrystringObrigatório

O país da loja como código ISO 3166-1 alfa-2, como US ou KR.

enginesarray

Mecanismos a consultar, sem repetição: CHATGPT, GEMINI, GOOGLE, BING_COPILOT e, para KR, NAVER_AI_TAB. Padrão: os cinco para KR e os quatro primeiros nos demais países.

idempotencyKeystring

O id da consulta, de 1 a 200 caracteres. Padrão: um UUID gerado pelo servidor. Reenviar a mesma requisição com ele adiciona as perguntas que faltam.

Resposta

A resposta, resumida para facilitar a leitura.

{
  "success": true,
  "lookup": { "id": "canlis-2026-10" },
  "tasks": [
    {
      "engine": "CHATGPT",
      "ask": 1,
      "success": true,
      "task": {
        "id": "…",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…",
        "idempotencyKey": "canlis-2026-10:CHATGPT:1"
      }
    },
    { "engine": "CHATGPT", "ask": 2, "…": "…" },
    { "engine": "GEMINI", "ask": 1, "…": "…" }
  ]
}

lookup.idstring

O id da consulta. Leia o resultado com GET /v1/place-lookup/{id}.

tasksarray

Uma entrada por pergunta: engine, ask, success e a task na fila, status: "PENDING" enquanto espera espaço, ou error com o código. O idempotencyKey da tarefa junta o id da consulta, o mecanismo e o número da pergunta, como em canlis-2026-10:CHATGPT:1.

Receba o resultado

Leia a consulta pelo ID a cada 5 a 10 segundos até lookup.status ser COMPLETED. Ela fica disponível por 24 horas depois que as perguntas terminam.

curl "https://api.querying.ai/v1/place-lookup/$LOOKUP_ID" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

A consulta do Canlis fica assim, resumida. O ChatGPT mostrou o registro do Yelp do restaurante, o Gemini e o Copilot o mesmo registro do Google Maps, e a página de resultados do Google respondeu sem lugares, por isso found é false.

{
  "success": true,
  "lookup": {
    "id": "canlis-2026-10",
    "status": "COMPLETED",
    "country": "US",
    "engines": [
      {
        "engine": "CHATGPT",
        "status": "COMPLETED",
        "found": true,
        "via": [{ "…": "…" }],
        "record": {
          "name": "Canlis",
          "source": "yelp",
          "provider": "yelp-feed",
          "phone": "+1 206-283-3313",
          "website": "https://canlis.com/",
          "rating": 4,
          "reviewCount": 1935,
          "match": {
            "same": true,
            "by": ["phone", "website", "location", "address", "name"],
            "nameScore": 1,
            "distanceMeters": 5
          },
          "…": "…"
        }
      },
      {
        "engine": "GEMINI",
        "status": "COMPLETED",
        "found": true,
        "via": [{ "…": "…" }],
        "record": {
          "name": "Canlis",
          "source": "google_maps",
          "placeId": "ChIJRXCfNwUVkFQRxraD8U-dANE",
          "phone": "+1 206-283-3313",
          "rating": 4.6,
          "reviewCount": 2892,
          "…": "…"
        }
      },
      {
        "engine": "GOOGLE",
        "status": "COMPLETED",
        "found": false,
        "…": "…"
      },
      {
        "engine": "BING_COPILOT",
        "status": "COMPLETED",
        "found": true,
        "…": "…"
      }
    ],
    "summary": {
      "foundIn": ["CHATGPT", "GEMINI", "BING_COPILOT"],
      "notFoundIn": ["GOOGLE"],
      "failed": [],
      "pending": [],
      "differences": []
    },
    "credits": 10
  }
}

lookup.statusstring

PROCESSING até todos os mecanismos terminarem, depois COMPLETED.

lookup.engines[].foundboolean

true assim que uma resposta mostra a loja, false quando as duas perguntas terminaram sem ela e null enquanto uma pergunta roda ou se as duas falharam.

lookup.engines[].recordobject

O registro da loja nesse mecanismo: entre os lugares das duas respostas, o que mais coincide com a loja, com o nome, o endereço, o telefone, o site e a nota que o mecanismo mostra.

lookup.engines[].record.sourcestring

A base de mapas do registro: google_maps, naver_place, yelp, tripadvisor ou unknown. placeId e url são o ID e a página dele nessa base.

lookup.engines[].record.matchobject

Por que o registro é a loja. by lista os dados que coincidem, nameScore é a semelhança do nome de 0 a 1 e distanceMeters, a distância desde place.location.

lookup.engines[].issuesarray

O que está errado no registro, quando há algo: phone_mismatch, website_mismatch, location_mismatch, other_business_record, closed_permanently ou closed_temporarily.

lookup.summaryobject

Os mecanismos por resultado em foundIn, notFoundIn, failed e pending, e differences: cada nome, telefone, site ou pino que difere entre mecanismos, com os mecanismos de cada valor.

lookup.creditsnumber

Créditos cobrados até agora pelas perguntas da consulta.

Erros

Se todas as perguntas forem recusadas, a resposta é a primeira recusa, como 402 ou 403. Se algumas forem aceitas, a chamada responde 200 e cada pergunta recusada traz seu error. Enquanto as tarefas simultâneas do seu plano estão ocupadas, as perguntas restantes ficam em PENDING e começam sozinhas à medida que as tarefas em andamento terminam, então no plano gratuito, que roda 2 tarefas por vez, uma única requisição executa a consulta inteira.

VALIDATION_ERRORHTTP 400

Falta um campo ou o valor está fora do intervalo. details indica o campo.

INSUFFICIENT_CREDITSHTTP 402

O saldo é menor que o preço da tarefa. Adicione créditos ou mude de plano e envie de novo.

KEY_SCOPE_DENIEDHTTP 403

O mecanismo está fora dos Mecanismos permitidos da chave. Use outra chave ou adicione o mecanismo em Gerenciar chave.

RESOURCE_ALREADY_EXISTSHTTP 409

O idempotencyKey já identifica uma consulta de outra loja, outro país ou outra lista de mecanismos. Um idempotencyKey novo inicia uma nova consulta.

Preço

Uma consulta aos mecanismos padrão do país custa 10 créditos: 1 por pergunta nas 10 perguntas de KR e 1,25 em cada uma das 8 de outros países. Uma consulta com menos mecanismos paga as perguntas que envia, e uma pergunta com falha custa 0. Os preços dos planos estão em https://querying.ai/pricing .