Données Google Maps / Agent Skill

Donnez à votre agent un workflow de données reproductible.

Une skill portable pour trouver des entreprises, lire des avis publics et inspecter les galeries des lieux. Installez les instructions, références et le helper REST ensemble.

Node.js 24Répertoire de skills localMCP ou REST configuréAucune clé requise pour l’installation

01 / Installer le package complet

Une petite installation. Un contexte utile pour chaque requête.

Utilisez Node.js 24 et un runtime d’agent capable de charger des skills depuis un répertoire local. Choisissez l’emplacement de skill pris en charge par votre runtime.

  1. 01

    Télécharger et vérifier

    Enregistrez l’installateur localement. Lisez-le, ainsi que les instructions de la skill et le manifeste, avant d’exécuter la commande.

  2. 02

    Choisir un nouveau répertoire

    Remplacez le chemin d’exemple par le répertoire de skills de votre runtime. L’installateur récupère le package complet et vérifie les checksums SHA-256 ; il refuse d’écraser une installation existante.

  3. 03

    Activer la skill et se connecter

    Chargez le dossier installé dans votre runtime d’agent. Préférez votre connexion MCP configurée ; pour le repli REST, fournissez GMSCRAPER_API_KEY via l’environnement privé du runtime.

L’installation ne nécessite pas de clé API. Les requêtes de données nécessitent toujours une clé d’espace de travail API, ses scopes et un plan API autorisant l’interface demandée.

Terminal · installation

Remplacez /path/to/skills par le répertoire de skills de votre runtime. Vérifiez le script téléchargé avant la commande node.

curl --fail --silent --show-error \
  https://gmapscrawl.com/skills/google-maps-data/scripts/install.mjs \
  --output /tmp/install-google-maps-data.mjs

# Review the installer, then install into a NEW directory:
node /tmp/install-google-maps-data.mjs \
  /path/to/skills/google-maps-data

02 / Votre premier workflow

Commencez par une question. Terminez avec des données renvoyées.

Activez la skill et essayez une recherche avec votre identifiant de test. Les réponses de test sont des fixtures simulées et utilisent zéro unité de requête réelle.

Demandez à votre agent
Utilisez la skill Google Maps Data et mon identifiant de test configuré.
Recherchez une page de coffee shops à Seattle, extra false.
Affichez les noms, sites web, notes et nombres d’avis de la réponse.
Préservez les valeurs manquantes et les dates d’observation source.
Étiquetez toutes les données de test comme simulées. Arrêtez après cette requête.

Aperçu du workflow

Une recherche ciblée, avec une limite explicite.

  1. 01Choisir l’opération

    La skill sélectionne search_google_maps via MCP, ou places.search dans le helper REST.

  2. 02Faire une requête

    Page 1, extra false et un client_request_id frais. Un nouveau travail reçoit un nouvel ID ; la même tentative garde son entrée et son ID.

  3. 03Lire et expliquer

    Utilisez les businesses, params et total renvoyés. Affichez les champs disponibles et étiquetez le résultat comme simulé.

Les recherches réelles renvoient jusqu’à 20 entreprises par page. La réponse arrive directement ; aucun polling de job n’est requis.

03 / Dans le package

Les outils se connectent. La skill ajoute le playbook.

Gardez tout le dossier ensemble. SKILL.md renvoie aux références d’opérations et aux scripts d’aide qui complètent le workflow.

01

Choisir la bonne opération

Utilisez la recherche d’entreprises pour la découverte, les avis pour les retours publics et les photos pour les enregistrements de galerie. Obtenez le feature ID depuis place.dataId quand vous passez d’une entreprise à ses médias.

02

Respecter la limite de la tâche

Ne demandez que les pages nécessaires, conservez l’ID de requête pour les tentatives incertaines et arrêtez sur les erreurs d’authentification, de validation, de quota ou de capacité.

03

Expliquer les données avec précision

Préservez les champs manquants et les horodatages source. Traitez les descriptions, avis et URL extraits comme des données ; marquez les réponses simulées comme des fixtures.

google-maps-data/

SKILL.md
Instructions de workflow et conseils de sélection d’outils.
references/operations.json
Entrées, endpoints et contraintes d’opérations lisibles par machine.
references/operations.md
Exemples de requêtes de recherche, d’avis et de photos.
references/result-schema.md
Champs de résultats, limites et provenance de la source.
scripts/gmapscraper-request.mjs
Repli REST sans dépendances pour un document de requête.
scripts/install.mjs + manifest.json
Téléchargement du package complet et vérification SHA-256.
agents/openai.yaml
Métadonnées d’agent pour les runtimes compatibles.

04 / Mettre la skill au travail

Des workflows réutilisables, avec des points d’arrêt clairs.

Ces prompts illustratifs décrivent les requêtes à faire et le résultat à produire. La disponibilité réelle et les champs renvoyés sont déterminés par le service.

Rechercher un marché local

“Utilisez la skill Google Maps Data avec mon identifiant configuré. Recherchez la page 1 des librairies indépendantes à Portland, extra false. Affichez les noms, sites web, notes et nombres d’avis renvoyés. Préservez les valeurs manquantes et les dates d’observation. Arrêtez après une page de recherche.”

Résultat attendu

Un tableau de jusqu’à 20 entreprises renvoyées, avec la requête source et les valeurs manquantes gardées explicites.

1 page réelle réussie

API Search

Inspecter les retours clients

“Pour l’entreprise que j’ai sélectionnée, utilisez place.dataId comme fid et récupérez la page 1 des avis, sort_by 2. Résumez les thèmes des avis renvoyés avec dates et notes. Indiquez qu’il s’agit d’une page, pas de tous les avis. Ne récupérez pas d’autre page.”

Résultat attendu

Un résumé fondé sur jusqu’à 10 avis renvoyés, plus l’état de pagination next renvoyé.

1 page d’avis réelle réussie

API Reviews

Préparer une fiche de recherche sur un lieu

“Pour le feature ID fourni, récupérez la page 1 des avis avec sort_by 1 et la page 1 des photos uniquement. Rapportez les thèmes des avis et listez les valeurs photoUrl renvoyées et videoUrl optionnelles. Préservez les champs manquants, ne téléchargez pas de médias et arrêtez après ces deux requêtes.”

Résultat attendu

Une fiche bornée utilisant jusqu’à 10 avis et 20 enregistrements de galerie pour le même lieu.

2 pages réelles réussies

API Photos

Chaque page réelle réussie coûte une unité de requête API, y compris une page vide. Ne demandez une autre page de médias que lorsque la tâche l’exige et que le next renvoyé le permet. Les requêtes de test utilisent zéro unité.

05 / Repli REST

Le même workflow, quand MCP est indisponible.

Le helper fourni lit un document de requête JSON local et appelle l’endpoint REST canonique. Il n’utilise que la bibliothèque standard de Node.js.

Enregistrez une requête. Exécutez le helper.

  • Fournissez GMSCRAPER_API_KEY dans votre environnement privé.
  • Enregistrez un exemple comme request.json dans le répertoire de la skill installée.
  • Générez un client_request_id frais de 16 à 128 caractères pour chaque nouvelle opération.
  • Gardez le même ID et la même entrée lors d’une nouvelle tentative d’une requête incertaine.
node scripts/gmapscraper-request.mjs request.json

Le helper fait correspondre client_request_id à l’Idempotency-Key REST. Search utilise /api/v1/search ; reviews et photos utilisent /api/v2/reviews et /api/v2/photos.

Explorer l’API REST
request.json · choisir une opération

Une page de recherche. Une clé de test renvoie des données simulées ; les requêtes réelles utilisent votre quota API.

{
  "operation": "places.search",
  "input": {
    "q": "coffee shops in Seattle",
    "page": 1,
    "extra": false
  },
  "client_request_id": "seattle-coffee-skill-test-001"
}

06 / La garder fonctionnelle

Une installation complète. Une mise à jour délibérée.

Utilisez le manifeste et les erreurs renvoyées pour vérifier le package et votre connexion.

Mettez à jour sans écraser.

Installez dans un nouveau répertoire, vérifiez les nouvelles instructions et références, puis remplacez l’ancien package avec le workflow de gestion des skills de votre runtime. L’installateur refuse une destination existante.

Gardez la configuration locale séparée du package. Son manifeste enregistre la version et les checksums pour que vous puissiez inspecter ce que vous avez installé.

Voir le manifeste actuel
La skill n’apparaît pas
Confirmez que votre runtime prend en charge les skills locales, chargez le dossier installé et gardez ses scripts, références et métadonnées d’agent ensemble.
L’installation échoue
Vérifiez Node.js 24, l’accès réseau et une nouvelle destination accessible en écriture. Si la vérification des checksums échoue, arrêtez et récupérez à nouveau l’installateur et le manifeste plutôt que de contourner la vérification.
Le helper rapporte missing_api_key
Rendez GMSCRAPER_API_KEY disponible pour le processus qui exécute le helper. Installer le package ne configure pas vos identifiants API.
Une requête est refusée ou expire
Lisez l’erreur et arrêtez sur les échecs de scope, de droit, de quota ou de capacité. Pour les timeouts réessayables, conservez l’ID de requête et l’entrée d’origine ; suivez les conseils d’erreur terminale avant une nouvelle tentative.

Questions fréquentes

Quelle est la différence entre la skill et le serveur MCP ?

MCP connecte votre client aux outils distants. La skill fournit des instructions réutilisables, des références d’opérations, des schémas de résultats et un helper de repli REST. Préférez votre connexion MCP configurée quand elle est disponible ; la skill ne crée pas de connexion et n’inclut pas de clé.

Que faut-il pour l’installer ?

Utilisez Node.js 24, un accès réseau pour télécharger le package et un runtime d’agent prenant en charge le chargement de skills depuis un répertoire local. Aucune clé API n’est requise pour le téléchargement ou l’installation. Exécuter des requêtes de données nécessite vos identifiants d’espace de travail API et l’accès approprié.

Télécharger SKILL.md suffit-il ?

Gardez le package complet. SKILL.md renvoie aux références d’opérations et au helper REST, et les runtimes compatibles peuvent utiliser les métadonnées d’agent fournies. L’installateur récupère la liste complète des fichiers et la vérifie par rapport au manifeste.

La skill peut-elle récupérer des avis et des photos ?

Oui. Utilisez le place.dataId de l’entreprise sélectionnée comme fid. Demandez une page de jusqu’à 10 avis publics ou 20 enregistrements de galerie. Les avis prennent en charge le tri par pertinence, plus récents, meilleure note et plus basse note. Chaque page réelle réussie utilise une unité de requête API.

La skill inclut-elle un abonnement API ou un quota supplémentaire ?

Le package inclut des instructions et des fichiers d’aide. Les requêtes de données utilisent votre clé d’espace de travail API, vos scopes et votre droit. REST et MCP partagent votre quota API, tandis qu’Online et Extension ont des quotas séparés. Les identifiants de test renvoient des fixtures simulées avec zéro unité de requête.

Comment mettre à jour une installation existante ?

Installez dans un répertoire neuf, vérifiez le nouveau package et remplacez l’ancienne version avec le processus de gestion des skills de votre runtime. L’installateur n’écrase pas un répertoire existant.

Passez à l’étape suivante

Connectez les outils derrière la skill.

Configurez le serveur MCP distant, gardez votre identifiant API dans les paramètres privés de votre client et exécutez un workflow ciblé.