Presentamos Google Places

Recibe los lugares que la pestaña Places de Google muestra para una búsqueda en la ciudad que elijas, hasta 100, con dirección, coordenadas, teléfono, sitio web y valoración, por 1 crédito cada 20 lugares.

Qué obtienes

• GOOGLE_PLACES: cada tarea lee la lista que la pestaña Places de Google muestra para tu búsqueda desde la ciudad que elijas, hasta 100 lugares.
• places: cada lugar con name, position y la page de la que sale, además de location (dirección, latitud y longitud), phoneNumber, url, mapsUrl, placeId, reviews con valoración y número de reseñas, category y la cita de reseña que muestra Google.
• pages: cuántas páginas de 20 lugares leyó la tarea, el número por el que se cobra.

Cómo funciona

Envía query y city, la ciudad escrita como la nombra Google, por ejemplo Reno, Nevada, United States. Si tu herramienta de seguimiento de posiciones ya guarda el valor uule de Google para un lugar, envíalo como uule y Google busca desde ese lugar. country fija el mercado, US por defecto.

Google muestra 20 lugares por página. limit fija cuántos quieres, de 1 a 100 (20 por defecto), y la tarea lee hasta cinco páginas en el orden de Google. position sigue contando entre páginas, y un lugar que Google repite en una página posterior cuenta una vez. Cuando la lista de Google termina antes de tu límite, recibes todos los lugares que tenía.

La tarea comprueba en cada página el lugar desde el que buscó Google, así todos los lugares de una lista salen de la misma ciudad.

Para qué sirve

• Sigue la posición de tu negocio entre todos los lugares que Google muestra para tu categoría en tu ciudad, más allá de los tres del local pack.
• Envía la misma búsqueda en cada ciudad donde operas y compara quién lidera cada mercado.
• Pon la lista de lugares junto a las respuestas de Google AI Overview y AI Mode para la misma búsqueda y mira qué lugares recomiendan.
• Pruébalo en el Playground: elige Google Places en la pestaña de búsqueda, escribe una ciudad y elige hasta 100 lugares.

Envía la solicitud

Envía la solicitud con tu clave de API en la cabecera 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 de la solicitud

taskTypestringObligatorio

El motor que se ejecuta, como CHATGPT o GOOGLE.

payload.querystringObligatorio

La búsqueda, escrita como la teclea un usuario en el buscador.

payload.citystring

La ciudad desde la que se busca, escrita como la nombra Google, por ejemplo Reno, Nevada, United States. Hasta 100 caracteres. Cada tarea usa city o uule.

payload.uulestring

El valor de ubicación de Google en su forma w+, el que las herramientas de seguimiento de posiciones guardan para cada lugar. Llega a Google tal como se envía.

payload.limitinteger

Lugares que se devuelven, de 1 a 100. Por defecto, 20, una página de la lista de Google.

payload.countrystring

Código de país de dos letras del mercado desde el que se pregunta, como US, KR o JP. Por defecto US.

webhook.urlstring

Una dirección HTTPS de tu servidor. La tarea terminada se envía allí en cuanto se completa.

Respuesta

Así llega una tarea terminada, recortada para que se lea mejor.

{
  "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 y al final COMPLETED con la respuesta o FAILED con error.

credits.creditsChargedinteger

Créditos cobrados por la tarea terminada. Una tarea fallida cobra 0.

response.placesarray

Los lugares en el orden de Google: name, position contada entre páginas, la page de la que sale y, cuando Google los muestra, placeId, location, phoneNumber, url, mapsUrl, reviews, category y snippet.

response.pagesinteger

Páginas de 20 lugares leídas, de 1 a 5. La tarea se cobra por esas páginas.

Recibe el resultado

La solicitud devuelve la tarea al instante con status QUEUED. Consulta GET /v1/async/task/{id} hasta que status sea COMPLETED o FAILED, o añade webhook.url y la tarea terminada llega a tu servidor con los mismos task, credits y response. Los resultados siguen disponibles 24 horas después de terminar la tarea.

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

Errores

VALIDATION_ERRORHTTP 422

limit queda fuera de 1 a 100, city está vacío o supera los 100 caracteres, o city se envió junto con uule o location. details indica el campo.

MISSING_API_KEYHTTP 401

Falta la cabecera Authorization, o su clave es desconocida, caducó o fue revocada.

INSUFFICIENT_CREDITSHTTP 402

El saldo es menor que el precio de la tarea. Añade créditos o mejora el plan y vuelve a enviarla.

Precio

Cada página de 20 lugares usa 1 crédito, así que 100 lugares usan 5 créditos. Al enviar se reservan los créditos que necesita tu limit, y al completarse se cobran las páginas leídas: una lista que termina en la página 2 usa 2 créditos.