A localização exata chega ao Google AI Mode, aos AI Overviews e à busca

Use payload.location em tarefas GOOGLE, AIMODE e GOOGLE_SERP para receber a AI Overview, a resposta do AI Mode e os resultados que um usuário vê naquele local.

O que muda

• Tarefas GOOGLE, AIMODE e GOOGLE_SERP aceitam payload.location e devolvem a AI Overview, a resposta do AI Mode e os resultados que o Google mostra a um usuário no lugar indicado: uma estação, um distrito ou um endereço.
• location em cada resultado com local, o mesmo objeto do ChatGPT e do Gemini: o lugar aplicado, as coordenadas e o tipo de lugar reconhecido.
• Tarefas GEMINI aceitam um local em todos os países atendidos pelo Gemini, agora também na Alemanha, no Reino Unido e no Irã.
• O campo de localização do Playground para Google AI Overviews e Google AI Mode em Mecanismos de resposta, e para Google Search em Mecanismos de busca. Ele sugere um lugar do país escolhido, como 강남역 para KR ou 旺角 para HK.

Como funciona

O Google responde conforme a localização precisa que um celular ou navegador compartilha, então “vacina da gripe perto de mim” mostra clínicas ao redor desse ponto. Numa tarefa com local, o querying.ai compartilha as coordenadas do seu lugar da mesma forma antes da busca, e o Google responde como a um usuário que está ali. O country da tarefa define o mercado e o idioma dos resultados, e payload.location define o ponto dentro dele.

Nos testes, o AI Mode citou o lugar pedido nas 50 respostas com local, em oito cidades da Coreia e dez lugares nos Estados Unidos, no Japão, na Alemanha e no Reino Unido. As AI Overviews refletiram o lugar nas 18 respostas com local, e o Gemini respondeu para a cidade pedida em cada resposta concluída da Alemanha e do Reino Unido.

Escreva o lugar como as pessoas de lá escrevem, com até 200 caracteres, dentro do country da tarefa. O AI Mode, as AI Overviews e os resultados de busca registram o lugar em location, com query, name, latitude, longitude e precision.

Onde ajuda

• Confira se sua clínica, restaurante ou loja aparece na AI Overview e na resposta do AI Mode para buscas feitas ao redor dela.
• Faça a mesma pergunta a partir de um endereço ao Google AI Mode, às AI Overviews, ao ChatGPT e ao Gemini, e compare o que cada um recomenda.
• Acompanhe os resultados de busca ao redor de cada unidade de uma rede, com um conjunto de buscas por endereço.

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/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "AIMODE",
    "payload": {
      "query": "where can I get a flu shot near me",
      "country": "HK",
      "location": "旺角"
    }
  }'

Campos da requisição

taskTypestringObrigatório

O motor que executa a tarefa, como CHATGPT ou GOOGLE.

payload.querystringObrigatório

A busca, escrita como o usuário digita na caixa de pesquisa.

payload.countrystring

Código de país de duas letras do mercado de onde a pergunta parte, como US, KR ou JP. Padrão US.

payload.locationstring

Um lugar dentro de country, como uma estação, um bairro ou um endereço, com até 200 caracteres. O motor responde como a um usuário que está ali. Para CHATGPT, GEMINI, GOOGLE, AIMODE e GOOGLE_SERP.

webhook.urlstring

Um endereço HTTPS do seu servidor. A tarefa concluída é enviada para lá assim que termina.

idempotencyKeystring

Seu próprio ID para a requisição. Cada chave cria uma única tarefa por conta, então um reenvio continua sendo uma tarefa.

Resposta

Uma tarefa concluída chega assim, resumida para facilitar a leitura.

{
  "success": true,
  "task": {
    "id": "22ae7f29-df83-425a-b614-606c50c81502",
    "taskType": "AIMODE",
    "status": "COMPLETED",
    "createdAt": "2026-10-03T17:54:37.189Z"
  },
  "credits": { "creditsToCharge": 2, "creditsCharged": 2 },
  "response": {
    "markdown": "In the **Yau Tsim Mong District** and across Hong Kong, you can get your seasonal influenza vaccination (flu shot) through private medical clinics, private group medical practices, or subsidized public channels…\n\nHere are a few options located right in your area:\n\n- **Private Medical Groups & Clinics:**\n  - **Local Private General Practice Clinics:** Many neighborhood private clinics across Yau Ma Tei, Tsim Sha Tsui, and Mong Kok offer walk-in or appointment-based flu jabs.\n…",
    "sources": [
      {
        "position": 1,
        "url": "https://www.chp.gov.hk/en/features/18630.html",
        "label": "CHP Government Vaccination Programme"
      }
    ],
    "location": {
      "name": "旺角, 亞皆老街, 旺角, 油尖旺區, 九龍, 香港, 中国",
      "query": "旺角",
      "latitude": 22.31931,
      "longitude": 114.16981,
      "precision": "railway"
    }
  }
}

task.statusstring

QUEUED, PROCESSING e, no fim, COMPLETED com a resposta ou FAILED com error.

credits.creditsChargedinteger

Créditos cobrados pela tarefa concluída. Uma tarefa que falhou cobra 0.

response.textstring

A resposta em texto puro.

response.markdownstring

A resposta com títulos, listas e tabelas, em todo resultado.

response.sourcesarray

As páginas que a resposta cita, na ordem do motor, com position, url e label.

response.locationobject

O lugar usado na resposta: query, name, latitude, longitude e precision.

Receba o resultado

A requisição devolve a tarefa na hora, com status QUEUED. Consulte GET /v1/async/task/{id} até status virar COMPLETED ou FAILED, ou adicione webhook.url e a tarefa concluída chega ao seu servidor com os mesmos task, credits e response. Os resultados ficam disponíveis por 24 horas após o fim da tarefa.

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

Erros

LOCATION_UNSUPPORTEDHTTP 422

payload.location funciona em CHATGPT, GEMINI, GOOGLE, AIMODE e GOOGLE_SERP. Os outros mecanismos devolvem este código no envio.

LOCATION_NOT_FOUNDHTTP 422

O lugar de payload.location é desconhecido dentro de country. Acrescente o bairro ou a cidade e envie de novo.

LOCATION_LOOKUP_UNAVAILABLEHTTP 503

A busca de lugares está parada por um instante. Reenvie a mesma requisição e os lugares já encontrados são resolvidos na hora.

Preço

Uma tarefa com local custa o mesmo que qualquer outra do mecanismo, por tarefa concluída: 2 créditos no AI Mode e nas AI Overviews, 1 crédito nos resultados de busca e 1 crédito no Gemini.