Conheça o Google Places

Receba os lugares que a aba Places do Google mostra para uma busca na cidade que você escolher, até 100, com endereço, coordenadas, telefone, site e avaliação, por 1 crédito a cada 20 lugares.

O que você recebe

• GOOGLE_PLACES: cada tarefa lê a lista que a aba Places do Google mostra para a sua busca a partir da cidade que você escolher, até 100 lugares.
• places: cada lugar com name, position e a page de onde veio, além de location (endereço, latitude e longitude), phoneNumber, url, mapsUrl, placeId, reviews com nota e número de resenhas, category e o trecho de resenha que o Google mostra.
• pages: quantas páginas de 20 lugares a tarefa leu, o número cobrado.

Como funciona

Envie query e city, a cidade escrita como o Google a nomeia, por exemplo Reno, Nevada, United States. Se a sua ferramenta de rastreamento de posições já guarda o valor uule do Google para um lugar, envie-o como uule e o Google busca a partir desse lugar. country define o mercado, US por padrão.

O Google mostra 20 lugares por página. limit define quantos você quer, de 1 a 100 (20 por padrão), e a tarefa lê até cinco páginas na ordem do Google. position continua contando entre as páginas, e um lugar que o Google repete numa página seguinte conta uma vez. Quando a lista do Google termina antes do seu limite, você recebe todos os lugares que ela tinha.

A tarefa confere em cada página o lugar de onde o Google buscou, então todos os lugares de uma lista vêm da mesma cidade.

Onde ajuda

• Acompanhe a posição do seu negócio entre todos os lugares que o Google mostra para a sua categoria na sua cidade, além dos três lugares do local pack.
• Envie a mesma busca em cada cidade onde você atua e compare quem lidera cada mercado.
• Coloque a lista de lugares ao lado das respostas do Google AI Overview e do AI Mode para a mesma busca e veja quais lugares elas recomendam.
• Experimente no Playground: escolha Google Places na aba de busca, digite uma cidade e escolha até 100 lugares.

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": "GOOGLE_PLACES",
    "payload": {
      "query": "Reno attorney",
      "city": "Reno, Nevada, United States",
      "limit": 100,
      "country": "US"
    }
  }'

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.citystring

A cidade de onde a busca parte, escrita como o Google a nomeia, por exemplo Reno, Nevada, United States. Até 100 caracteres. Cada tarefa usa city ou uule.

payload.uulestring

O valor de localização do Google no formato w+, o que as ferramentas de rastreamento de posições guardam para cada lugar. Vai para o Google como foi enviado.

payload.limitinteger

Lugares retornados, de 1 a 100. Padrão 20, uma página da lista do Google.

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.

webhook.urlstring

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

Resposta

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

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "GOOGLE_PLACES",
    "status": "COMPLETED",
    "createdAt": "…"
  },
  "credits": { "creditsToCharge": 5, "creditsCharged": 5 },
  "response": {
    "places": [
      {
        "name": "Joey Gilbert Law",
        "position": 1,
        "placeId": "ChIJcW7HSupAmYARRnrM6Ap0UtU",
        "location": {
          "address": "405 Marsh Ave, Reno, NV 89509",
          "latitude": 39.519216,
          "longitude": -119.815709
        },
        "phoneNumber": "(775) 210-1501",
        "url": "https://joeygilbertlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=15371476068373133894",
        "reviews": [
          { "rating": 4.4, "count": 381, "providerName": "Google" }
        ],
        "category": "Criminal justice attorney",
        "snippet": "Joey is knowledgeable, straightforward, and fights hard for his clients.",
        "page": 1
      },
      {
        "name": "Viloria, Oliphant, Oster & Aman L.L.P.",
        "position": 2,
        "placeId": "ChIJv8KkdMlAmYARmINKFMPLxbs",
        "location": {
          "address": "327 California Ave, Reno, NV 89509",
          "latitude": 39.520335,
          "longitude": -119.81519
        },
        "phoneNumber": "(775) 515-8480",
        "url": "https://www.renonvlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=13530444694224012184",
        "reviews": [
          { "rating": 4.6, "count": 117, "providerName": "Google" }
        ],
        "category": "Personal injury attorney",
        "snippet": "Tom’s work ethic and knowledge of the legal system is beyond reproach.",
        "page": 1
      },
      "…"
    ],
    "pages": 5,
    "city": "Reno, Nevada, United States"
  }
}

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.placesarray

Os lugares na ordem do Google: name, position contada entre as páginas, a page de onde veio e, quando o Google os mostra, placeId, location, phoneNumber, url, mapsUrl, reviews, category e snippet.

response.pagesinteger

Páginas de 20 lugares lidas, de 1 a 5. A tarefa é cobrada por essas páginas.

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

VALIDATION_ERRORHTTP 422

limit está fora de 1 a 100, city está vazio ou passa de 100 caracteres, ou city foi enviado junto com uule ou location. details indica o campo.

MISSING_API_KEYHTTP 401

Falta o cabeçalho Authorization, ou a chave é desconhecida, expirou ou foi revogada.

INSUFFICIENT_CREDITSHTTP 402

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

Preço

Cada página de 20 lugares usa 1 crédito, então 100 lugares usam 5 créditos. O envio reserva os créditos que o seu limit precisa, e a conclusão cobra as páginas lidas: uma lista que termina na página 2 usa 2 créditos.