POST /api/v1/search

API Google Maps Scraper

Trouvez des entreprises par mot-clé et lieu. Recevez jusqu’à 20 enregistrements d’entreprises structurés dans la même réponse JSON, prêts pour votre application ou votre workflow de recherche.

Exemples de requêtes

Pour le contrat complet, consultez la documentation API.

curl https://gmapscrawl.com/api/v1/search \
  -H "Authorization: Bearer $GMSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seattle-coffee-search-001" \
  -d '{"q":"coffee shops in Seattle","page":1,"extra":false}'

Réponse vide illustrative. Une recherche réelle renvoie les entreprises disponibles. Gardez votre clé API côté serveur ; utilisez une nouvelle clé d’idempotence pour un nouveau travail et conservez-la pour une nouvelle tentative inchangée.

Réponse

JSON illustratif
{
  "data": {
    "total": 0,
    "params": {
      "q": "coffee shops in Seattle",
      "page": 1,
      "hl": "en",
      "extra": false
    },
    "businesses": []
  },
  "request_id": "req_example",
  "schema_version": "2026-09-22"
}

L’API renvoie du JSON dans la même réponse. Après un timeout, réessayez avec le corps inchangé et la même Idempotency-Key. Les identifiants de test renvoient des données simulées sans consommer votre quota réel.

Données d’entreprise structurées

D’une recherche Maps à des enregistrements exploitables.

Lisez data.businesses dans la réponse. Chaque entreprise regroupe ses champs de fiche sous place ; la disponibilité des champs dépend de la source.

01

Identité et localisation de l’entreprise

Utilisez le nom de l’entreprise, les catégories, l’adresse formatée, les coordonnées et l’URL Maps pour organiser un jeu de données d’entreprises locales.

02

Contact et réputation

Lisez les numéros de téléphone, sites web, notes et nombres d’avis disponibles. Avec extra activé, demandez l’enrichissement des contacts e-mail et réseaux sociaux.

03

Identifiants et dates d’observation

Conservez place.dataId pour les recherches d’avis et de photos. Inspectez place.observedAt et contactsCheckedAt pour comprendre quand les données ont été observées.

Gardez les données manquantes et anciennes visibles

Les champs indisponibles peuvent être null ou vides, et l’enrichissement peut rapporter not_found ou failed. Un enregistrement ne garantit pas qu’une adresse e-mail ou un site web existe. Les détails Maps peuvent être réutilisés jusqu’à 730 jours avec leurs horodatages d’observation d’origine ; évaluez la fraîcheur avant d’utiliser un enregistrement.

En savoir plus sur la fraîcheur des données →

Une requête ciblée

Choisissez la requête, la page et l’enrichissement.

Envoyez un corps JSON avec votre clé API côté serveur dans l’en-tête authorization. Seul q est requis.

Paramètres de l’API Google Maps Search
ParamètreExigenceObjectif
qRequisUn mot-clé d’entreprise et un lieu, comme coffee shops in Seattle. Utilisez 2 à 200 caractères.
pagePar défaut : 1Une page de recherche numérotée de 1 à 10. Chaque requête renvoie au maximum 20 entreprises.
llOptionnelUn viewport Maps de la forme @47.6062,-122.3321,12z pour guider le lieu de recherche.
hlPar défaut : enLe code de langue utilisé pour la recherche.
glOptionnelUn code pays à deux lettres qui qualifie la requête. Ce n’est pas un filtre géographique strict.
extraPar défaut : falseMettez true pour demander l’enrichissement des contacts e-mail et réseaux sociaux disponibles. Cela peut prendre plus de temps.

La réponse reprend les paramètres normalisés dans data.params. La valeur data.total compte les entreprises dans cette réponse, et non le nombre total d’entreprises sur Google Maps. Choisissez explicitement une autre page quand votre workflow a besoin de plus de résultats.

Construisez votre première intégration

Une requête. Une prochaine étape utile.

L’API Search est synchrone : lisez le résultat directement dans la réponse HTTP.

01

Créez votre clé API

Utilisez votre espace de travail API pour créer une clé avec la permission scrapes:write. Stockez la clé dans l’environnement de votre serveur et envoyez Authorization: Bearer avec la requête.

Ouvrir les clés API
02

Recherchez une zone délimitée

Choisissez une catégorie et un lieu, demandez la page 1 et inspectez les champs de fiche renvoyés. Pour une comparaison de marché, lancez des recherches séparées pour les zones à comparer.

03

Suivez un identifiant de lieu

Utilisez place.dataId d’une entreprise correspondante comme fid pour récupérer une page d’avis ou de galerie. Ce sont des requêtes séparées avec leurs propres enregistrements renvoyés.

Explorer l’API Reviews

Prévoyez des requêtes réelles

Pages prévisibles, limites explicites.

Utilisation et disponibilité

Chaque page de recherche réelle réussie utilise une unité de requête API, y compris un résultat vide. REST et MCP partagent le quota API. Les abonnements Online scraper et Extension ont des quotas séparés. Les limites de débit, identifiants, capacité de service et disponibilité de la source s’appliquent toujours.

Comparer les plans API →

Timeouts et nouvelles tentatives

Prévoyez jusqu’à 180 secondes dans votre client HTTP. Un timeout peut laisser un travail en cours avec une unité de requête réservée. Réutilisez le corps identique et l’Idempotency-Key pour réessayer cette requête. Vérifiez les détails de l’erreur et la possibilité de réessayer avant de lancer une nouvelle tentative.

Comprendre les nouvelles tentatives →

Poursuivez votre workflow

D’autres façons d’utiliser les mêmes données d’entreprise.

01

Données d’avis et de galerie

Récupérez les avis publics ou les métadonnées photo et vidéo d’un lieu avec son feature ID.

Explorer les données de galerie
02

Connectez un client MCP

Laissez un client IA compatible découvrir les outils de recherche, d’avis et de photos avec vos identifiants API.

Configurer MCP
03

Installez l’Agent Skill

Donnez à votre agent des instructions de workflow, des références d’opérations et une solution REST de repli pour la recherche Google Maps.

Explorer la skill

Questions fréquentes

Que renvoie l’API Google Maps Scraper ?

Elle renvoie une enveloppe JSON avec data.businesses, data.total, les data.params normalisés, request_id et schema_version. Les entreprises incluent les champs de fiche disponibles tels que noms, adresses, catégories, informations de contact, notes et identifiants Maps.

Puis-je utiliser l’API depuis Python ou JavaScript ?

Oui. L’endpoint accepte des requêtes HTTP POST standard avec JSON et une authentification Bearer. Les exemples ci-dessus utilisent la bibliothèque standard de Python et fetch côté serveur en JavaScript. Tout client HTTP capable d’envoyer ces en-têtes et ce corps peut s’intégrer.

Combien d’entreprises une requête peut-elle renvoyer ?

Une page de recherche renvoie entre zéro et 20 entreprises. Le paramètre page accepte de 1 à 10. Chaque page réelle réussie, y compris une page vide, utilise une unité de requête API ; une recherche ne garantit pas que chaque page contient 20 entreprises.

Puis-je récupérer des avis et photos individuels ?

Oui. Copiez place.dataId d’une entreprise et transmettez-le comme fid à l’API Reviews ou Photos séparée. Ces endpoints renvoient une page bornée par requête. La vue d’ensemble de l’API renvoie vers les champs, exemples et règles de pagination de chaque endpoint.

Les adresses e-mail sont-elles incluses pour chaque entreprise ?

Non. Mettez extra à true pour demander l’enrichissement de contact disponible. Les sites web, e-mails et profils sociaux peuvent être manquants. Inspectez enrichmentState et fieldStates et gardez les données indisponibles explicites dans votre application.

Comment tester une intégration ?

Si vous avez un identifiant de test, ses réponses sont simulées et ne consomment pas de quota API réel. Étiquetez ces résultats comme simulés. Les clés réelles nécessitent un droit API actif et une capacité de service disponible, et les appels réels réussis utilisent des unités de requête.

Passez à l’étape suivante

Construisez votre première recherche Google Maps.

Créez une clé API, choisissez une requête et un lieu, et lisez des données d’entreprise structurées dans la même réponse.