Datos de Google Maps / Agent Skill

Dé a su agente un flujo de trabajo de datos repetible.

Una skill portátil para encontrar negocios, leer reseñas públicas e inspeccionar galerías de lugares. Instale las instrucciones, las referencias y el auxiliar REST juntos.

Node.js 24Directorio local de skillsMCP o REST configuradoNo se necesita clave para instalar

01 / Instale el paquete completo

Una instalación pequeña. Contexto útil para cada solicitud.

Use Node.js 24 y un entorno de ejecución de agente que pueda cargar skills desde un directorio local. Elija la ubicación de skills que admita su entorno de ejecución.

  1. 01

    Descargue y revise

    Guarde el instalador localmente. Léalo, así como las instrucciones de la skill y el manifiesto, antes de ejecutar el comando.

  2. 02

    Elija un directorio nuevo

    Sustituya la ruta de ejemplo por el directorio de skills de su entorno de ejecución. El instalador descarga el paquete completo y verifica las sumas de comprobación SHA-256; se niega a sobrescribir una instalación existente.

  3. 03

    Habilite la skill y conecte

    Cargue la carpeta instalada en su entorno de ejecución de agente. Prefiera su conexión MCP configurada; para el respaldo REST, proporcione GMSCRAPER_API_KEY a través del entorno privado del entorno de ejecución.

La instalación no necesita una clave de API. Las solicitudes de datos siguen requiriendo una clave del espacio de trabajo de API, sus alcances y un plan de API que permita la interfaz solicitada.

Terminal · instalación

Sustituya /path/to/skills por el directorio de skills de su entorno de ejecución. Revise el script descargado antes del comando 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 / Su primer flujo de trabajo

Comience con una pregunta. Termine con datos devueltos.

Habilite la skill y pruebe una búsqueda usando su credencial de prueba. Las respuestas de prueba son fixtures simulados y usan cero unidades de solicitud en vivo.

Pregunte a su agente
Use la skill de Google Maps Data y mi credencial de prueba configurada.
Busque una página de cafeterías en Seattle, extra false.
Muestre nombres, sitios web, calificaciones y recuentos de reseñas de la respuesta.
Conserve los valores faltantes y las fechas de observación de la fuente.
Etiquete todos los datos de prueba como simulados. Deténgase tras esta única solicitud.

Vista previa del flujo de trabajo

Una búsqueda enfocada, con un límite explícito.

  1. 01Elija la operación

    La skill selecciona search_google_maps mediante MCP, o places.search en el auxiliar REST.

  2. 02Haga una solicitud

    Página 1, extra false y un client_request_id nuevo. El trabajo nuevo obtiene un ID nuevo; el mismo reintento conserva su entrada e ID.

  3. 03Lea y explique

    Use los businesses, params y total devueltos. Muestre los campos disponibles y etiquete el resultado como simulado.

Las búsquedas en vivo devuelven hasta 20 negocios por página. La respuesta llega directamente; no se requiere sondeo de trabajos.

03 / Dentro del paquete

Las herramientas conectan. La skill añade el manual de juego.

Mantenga toda la carpeta junta. SKILL.md enlaza a las referencias de operaciones y a los scripts auxiliares que completan el flujo de trabajo.

01

Elija la operación correcta

Use la búsqueda de negocios para el descubrimiento, las reseñas para los comentarios públicos y las fotos para los registros de galería. Obtenga el feature ID de place.dataId al pasar de un negocio a sus medios.

02

Respete el límite de la tarea

Solicite solo las páginas necesarias, conserve el ID de solicitud para reintentos inciertos y deténgase ante errores de autenticación, validación, cuota o capacidad.

03

Explique los datos con precisión

Conserve los campos faltantes y las marcas de tiempo de origen. Trate las descripciones, reseñas y URLs extraídas como datos; marque las respuestas simuladas como fixtures.

google-maps-data/

SKILL.md
Instrucciones de flujo de trabajo y guía de selección de herramientas.
references/operations.json
Entradas de operaciones, endpoints y restricciones legibles por máquina.
references/operations.md
Ejemplos de solicitudes de búsqueda, reseñas y fotos.
references/result-schema.md
Campos de resultados, límites y procedencia de la fuente.
scripts/gmapscraper-request.mjs
Respaldo REST sin dependencias para un documento de solicitud.
scripts/install.mjs + manifest.json
Descarga del paquete completo y verificación SHA-256.
agents/openai.yaml
Metadatos de agente para entornos de ejecución compatibles.

04 / Ponga la skill a trabajar

Flujos de trabajo reutilizables, con puntos de parada claros.

Estos prompts ilustrativos describen las solicitudes a realizar y el resultado a producir. La disponibilidad en vivo y los campos devueltos los determina el servicio.

Investigue un mercado local

“Use la skill de Google Maps Data con mi credencial configurada. Busque la página 1 de librerías independientes en Portland, extra false. Muestre los nombres, sitios web, calificaciones y recuentos de reseñas devueltos. Conserve los valores faltantes y las fechas de observación. Deténgase tras una página de búsqueda.”

Resultado esperado

Una tabla de hasta 20 negocios devueltos, con la consulta de origen y los valores faltantes mantenidos explícitos.

1 página en vivo exitosa

API de Search

Inspeccione los comentarios de clientes

“Para el negocio que seleccioné, use place.dataId como fid y obtenga la página 1 de reseñas, sort_by 2. Resuma los temas de las reseñas devueltas con fechas y calificaciones. Indique que esto es una página, no todas las reseñas. No obtenga otra página.”

Resultado esperado

Un resumen basado en hasta 10 reseñas devueltas, más el estado de paginación next devuelto.

1 página de reseñas en vivo exitosa

API de Reviews

Prepare un informe de investigación de un lugar

“Para el feature ID proporcionado, obtenga la página 1 de reseñas con sort_by 1 y solo la página 1 de fotos. Informe de los temas de las reseñas y enumere los valores photoUrl devueltos y los videoUrl opcionales. Conserve los campos faltantes, no descargue medios y deténgase tras estas dos solicitudes.”

Resultado esperado

Un informe delimitado usando hasta 10 reseñas y 20 registros de galería del mismo lugar.

2 páginas en vivo exitosas

API de Photos

Cada página en vivo exitosa cuesta una unidad de solicitud de API, incluida una página vacía. Solicite otra página de medios solo cuando la tarea lo necesite y el next devuelto lo permita. Las solicitudes de prueba usan cero unidades.

05 / Respaldo REST

El mismo flujo de trabajo, cuando MCP no está disponible.

El auxiliar incluido lee un documento de solicitud JSON local y llama al endpoint REST canónico. Solo usa la biblioteca estándar de Node.js.

Guarde una solicitud. Ejecute el auxiliar.

  • Proporcione GMSCRAPER_API_KEY en su entorno privado.
  • Guarde un ejemplo como request.json en el directorio de la skill instalada.
  • Genere un client_request_id nuevo de 16–128 caracteres para cada operación nueva.
  • Mantenga el mismo ID y una entrada idéntica al reintentar una solicitud incierta.
node scripts/gmapscraper-request.mjs request.json

El auxiliar asigna client_request_id al Idempotency-Key de REST. La búsqueda usa /api/v1/search; reviews y photos usan /api/v2/reviews y /api/v2/photos.

Explorar la API REST
request.json · elija una operación

Una página de búsqueda. Una clave de prueba devuelve datos simulados; las solicitudes en vivo usan su cuota de API.

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

06 / Manténgala funcionando

Una instalación completa. Una actualización deliberada.

Use el manifiesto y los errores devueltos para comprobar el paquete y su conexión.

Actualice sin sobrescribir.

Instale en un directorio nuevo, revise las nuevas instrucciones y referencias, y luego reemplace el paquete antiguo usando el flujo de trabajo de gestión de skills de su entorno de ejecución. El instalador rechaza un destino existente.

Mantenga la configuración local separada del paquete. Su manifiesto registra la versión y las sumas de comprobación para que pueda inspeccionar lo que instaló.

Ver el manifiesto actual
La skill no aparece
Confirme que su entorno de ejecución admite skills locales, cargue la carpeta instalada y mantenga juntos sus scripts, referencias y metadatos de agente.
La instalación falla
Compruebe Node.js 24, el acceso a la red y un destino nuevo con permisos de escritura. Si la verificación de la suma de comprobación falla, deténgase y vuelva a descargar el instalador y el manifiesto en lugar de omitir la verificación.
El auxiliar informa missing_api_key
Haga que GMSCRAPER_API_KEY esté disponible para el proceso que ejecuta el auxiliar. Instalar el paquete no configura sus credenciales de API.
Una solicitud es denegada o agota el tiempo
Lea el error y deténgase ante fallos de alcance, derecho, cuota o capacidad. Para timeouts reintentables, conserve el ID de solicitud y la entrada originales; siga la guía de errores terminales antes de un nuevo intento.

Preguntas frecuentes

¿Cuál es la diferencia entre la skill y el servidor MCP?

MCP conecta su cliente a las herramientas remotas. La skill proporciona instrucciones reutilizables, referencias de operaciones, esquemas de resultados y un auxiliar de respaldo REST. Prefiera su conexión MCP configurada cuando esté disponible; la skill no crea una conexión ni incluye una clave.

¿Qué necesito para instalarla?

Use Node.js 24, acceso a la red para descargar el paquete y un entorno de ejecución de agente que admita cargar skills desde un directorio local. No se requiere clave de API para la descarga ni la instalación. Ejecutar solicitudes de datos requiere sus credenciales del espacio de trabajo de API y el acceso apropiado.

¿Es suficiente descargar SKILL.md?

Conserve el paquete completo. SKILL.md enlaza a las referencias de operaciones y al auxiliar REST, y los entornos de ejecución compatibles pueden usar los metadatos de agente incluidos. El instalador recupera la lista completa de archivos y la verifica contra el manifiesto.

¿Puede la skill recuperar reseñas y fotos?

Sí. Use el place.dataId del negocio seleccionado como fid. Solicite una página de hasta 10 reseñas públicas o 20 registros de galería. Las reseñas admiten ordenación por relevancia, más recientes, mejor calificación y peor calificación. Cada página en vivo exitosa usa una unidad de solicitud de API.

¿La skill incluye una suscripción de API o cuota extra?

El paquete incluye instrucciones y archivos auxiliares. Las solicitudes de datos usan la clave, los alcances y el derecho de su espacio de trabajo de API. REST y MCP comparten su cuota de API, mientras que Online y Extensión tienen cuotas separadas. Las credenciales de prueba devuelven fixtures simulados con cero unidades de solicitud.

¿Cómo actualizo una instalación existente?

Instale en un directorio nuevo, revise el nuevo paquete y reemplace la versión antigua usando el proceso de gestión de skills de su entorno de ejecución. El instalador no sobrescribe un directorio existente.

Dé el siguiente paso

Conecte las herramientas detrás de la skill.

Configure el servidor MCP remoto, mantenga su credencial de API en los ajustes privados de su cliente y ejecute un flujo de trabajo enfocado.