Découvrez Google Places

Recevez les lieux que l’onglet Places de Google affiche pour une requête dans la ville de votre choix, jusqu’à 100, avec adresse, coordonnées, téléphone, site web et note, pour 1 crédit par tranche de 20 lieux.

Ce que vous obtenez

• GOOGLE_PLACES : chaque tâche lit la liste que l’onglet Places de Google affiche pour votre requête depuis la ville de votre choix, jusqu’à 100 lieux.
• places : chaque lieu avec name, position et la page d’où il vient, ainsi que location (adresse, latitude et longitude), phoneNumber, url, mapsUrl, placeId, reviews avec note et nombre d’avis, category et l’extrait d’avis affiché par Google.
• pages : le nombre de pages de 20 lieux lues par la tâche, celui qui est facturé.

Fonctionnement

Envoyez query et city, la ville écrite comme Google la nomme, par exemple Reno, Nevada, United States. Si votre outil de suivi de positions conserve déjà la valeur uule de Google pour un lieu, envoyez-la comme uule et Google cherche depuis ce lieu. country fixe le marché, US par défaut.

Google affiche 20 lieux par page. limit fixe le nombre voulu, de 1 à 100 (20 par défaut), et la tâche lit jusqu’à cinq pages dans l’ordre de Google. position continue de compter d’une page à l’autre, et un lieu que Google répète sur une page suivante compte une fois. Quand la liste de Google s’arrête avant votre limite, vous recevez tous les lieux qu’elle contenait.

La tâche vérifie sur chaque page le lieu depuis lequel Google a cherché : tous les lieux d’une liste viennent de la même ville.

Cas d’usage

• Suivez le rang de votre établissement parmi tous les lieux que Google affiche pour votre catégorie dans votre ville, au-delà des trois lieux du local pack.
• Envoyez la même requête dans chaque ville où vous êtes présent et comparez les leaders de chaque marché.
• Placez la liste des lieux à côté des réponses Google AI Overview et AI Mode à la même requête et voyez quels lieux elles recommandent.
• Essayez-le dans le Playground : choisissez Google Places dans l’onglet de recherche, saisissez une ville et choisissez jusqu’à 100 lieux.

Envoyer la requête

Envoyez la requête avec votre clé API dans l’en-tête 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"
    }
  }'

Champs de la requête

taskTypestringObligatoire

Le moteur à interroger, par exemple CHATGPT ou GOOGLE.

payload.querystringObligatoire

La requête, rédigée comme un utilisateur la tape dans le champ de recherche.

payload.citystring

La ville depuis laquelle chercher, écrite comme Google la nomme, par exemple Reno, Nevada, United States. Jusqu’à 100 caractères. Chaque tâche utilise city ou uule.

payload.uulestring

La valeur de localisation de Google sous sa forme w+, celle que les outils de suivi de positions conservent pour chaque lieu. Elle est transmise à Google telle quelle.

payload.limitinteger

Nombre de lieux renvoyés, de 1 à 100. 20 par défaut, soit une page de la liste de Google.

payload.countrystring

Code pays à deux lettres du marché d’où part la question, par exemple US, KR ou JP. Par défaut US.

webhook.urlstring

Une adresse HTTPS de votre serveur. La tâche terminée y est envoyée dès qu’elle se termine.

Réponse

Voici une tâche terminée, raccourcie pour la lecture.

{
  "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, puis COMPLETED avec la réponse ou FAILED avec error.

credits.creditsChargedinteger

Crédits facturés pour la tâche terminée. Une tâche en échec facture 0.

response.placesarray

Les lieux dans l’ordre de Google : name, position comptée d’une page à l’autre, la page d’origine et, quand Google les affiche, placeId, location, phoneNumber, url, mapsUrl, reviews, category et snippet.

response.pagesinteger

Pages de 20 lieux lues, de 1 à 5. La tâche est facturée sur ces pages.

Recevoir le résultat

La requête renvoie aussitôt la tâche avec status QUEUED. Interrogez GET /v1/async/task/{id} jusqu’à ce que status vaille COMPLETED ou FAILED, ou ajoutez webhook.url pour recevoir la tâche terminée sur votre serveur, avec les mêmes task, credits et response. Les résultats restent disponibles 24 heures après la fin de la tâche.

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

Erreurs

VALIDATION_ERRORHTTP 422

limit sort de 1 à 100, city est vide ou dépasse 100 caractères, ou city a été envoyé avec uule ou location. details indique le champ.

MISSING_API_KEYHTTP 401

L’en-tête Authorization manque, ou sa clé est inconnue, expirée ou révoquée.

INSUFFICIENT_CREDITSHTTP 402

Le solde est inférieur au prix de la tâche. Ajoutez des crédits ou changez de plan, puis renvoyez-la.

Tarif

Chaque page de 20 lieux utilise 1 crédit, donc 100 lieux utilisent 5 crédits. L’envoi réserve les crédits nécessaires à votre limit, et la fin de la tâche facture les pages lues : une liste qui s’arrête à la page 2 utilise 2 crédits.