La forma más rápida de trabajar la API de Google Business Profile a escala.

Por qué la API de Google Business Profile es difícil

En el papel, las APIs de Google Business Profile son servicios REST directos: gestión de cuentas, información de negocio, métricas de rendimiento, medios, publicaciones y reseñas. En la práctica, los equipos que intentan construir directamente sobre ellas chocan siempre con el mismo muro: la superficie está repartida entre varias familias de API con versiones distintas, cuotas distintas y field masks distintas, y las operaciones interesantes son todas de listar y paginar, no de lectura simple.

Añade escala real y empeora. La cuota se otorga por proyecto y se consume por llamada, así que un bucle ingenuo sobre 800 ubicaciones para leer horarios agota la asignación diaria antes de la comida. Los errores no son uniformes: algunos son 429 transitorios que requieren backoff, otros son rechazos permanentes porque la categoría no existe en ese país, y otros significan que la ficha está suspendida y nada de lo que envíes se aplicará.

Mapgrid existe porque esa fontanería es igual para todos y no es la ventaja competitiva de nadie. El producto es un cliente endurecido sobre esas APIs más la capa operativa que las rodea: caché, orquestación de trabajos, política de reintentos, modelo de permisos y una interfaz que puede usar alguien que no programa.

Cómo envuelve Mapgrid la API

Cada request se proxifica bajo tu propio consentimiento OAuth, así que la cuota, los permisos y el rastro de auditoría pertenecen a tu proyecto de Google y a tu cuenta, no a una identidad compartida del proveedor. Mapgrid gestiona la paginación de forma transparente, aplica las field masks correctas por recurso y aplica throttling por cuenta para que un workspace ocupado no degrade a otro.

Las escrituras se encolan en lugar de dispararse en línea. Un cambio masivo se convierte en un trabajo en segundo plano con resultado persistido por ubicación, backoff exponencial ante errores reintentables y capacidad de reanudarse si una ejecución se interrumpe. Eso es lo que convierte una actualización de horarios en 800 ubicaciones en una operación confiable y no en un script que hay que vigilar.

Las lecturas se cachean en servidor con refresco programado, y por eso los listados y las analíticas cargan rápido sin golpear a Google en cada vista. Las páginas de detalle consultan con más frecuencia mientras están abiertas para que la pantalla en la que trabajas esté al día, y los agregados pesados de analítica se precalculan en la base de datos en lugar de ensamblarse en el navegador.

• Paginación automática y field masks correctas por recurso
• Throttling por cuenta y backoff exponencial ante 429/5xx
• Trabajos en segundo plano duraderos con resultado y reintento por ubicación
• Caché en servidor y agregados de analítica precalculados

MCP: un endpoint que los agentes de IA pueden llamar directo

Mapgrid expone un endpoint MCP (Model Context Protocol) protegido con OAuth. MCP es el estándar emergente para dar a los asistentes de IA herramientas tipadas en lugar de acceso a la pantalla, y significa que Claude, ChatGPT o tu propio framework de agentes pueden consultar tus datos locales como una capacidad de primera clase.

Las herramientas de solo lectura cubren la superficie operativa: list_locations, get_location, list_reviews, list_posts y list_nap_findings. Es suficiente para responder casi todas las preguntas de una revisión semanal de SEO local: qué ubicaciones están sin verificar, dónde se movieron las calificaciones, qué hallazgos NAP siguen abiertos, qué publicaciones salieron en una región.

La autorización es el detalle importante. Un agente se autentica como un asiento y hereda su rol, sus límites y su alcance de workspace, así que nunca puede leer datos de otro tenant ni exceder lo que la persona que lo autorizó podría hacer a mano. Mantener las herramientas de solo lectura por defecto hace seguro apuntar un asistente general a producción.

Lo que obtienen tus desarrolladores sin construir un cliente

Para equipos de ingeniería el cálculo suele ser construir o comprar las partes aburridas. Construir tu propio cliente implica implementar refresco de OAuth, contabilidad de cuota, field masks, clasificación de reintentos, durabilidad de trabajos y un modelo de permisos antes de escribir una línea de lógica de negocio — y luego mantenerlo mientras Google versiona los endpoints.

Con Mapgrid, las mismas server functions que alimentan la app son alcanzables por MCP tras OAuth, así que un script o un agente puede leer los mismos datos normalizados que lee la UI. Obtienes formas consistentes para ubicaciones, reseñas, publicaciones, medios y hallazgos NAP, ya reconciliadas contra las inconsistencias de Google.

Como el acceso está acotado a un asiento, las integraciones también son fáciles de gobernar: emites un asiento con el rol mínimo, apuntas el agente ahí y lo revocas en un solo lugar cuando el proyecto termina. No queda una credencial de servicio de larga vida circulando con permisos amplios de escritura.

Vivir dentro de las cuotas de Google

La gestión de cuota es la diferencia entre una demo y un sistema en producción. Mapgrid presupuesta llamadas por cuenta, prefiere lecturas cacheadas para todo lo que una persona esté navegando y programa el trabajo de refresco en ventanas de baja demanda para que el uso interactivo siempre tenga margen.

Las operaciones masivas van deliberadamente pausadas. En lugar de disparar todas las escrituras a la vez, los trabajos avanzan en lotes controlados, se detienen ante señales de rate limit y se reanudan solos, de modo que una actualización grande termina algo más despacio pero nunca quema la asignación del día ni deja la red a medio cambiar.

Cuando un request de verdad no puede tener éxito, el fallo se muestra con el estado y el mensaje propios de Google en lugar de un error genérico, porque el motivo real — categoría no soportada, ficha suspendida, permiso faltante — es lo que le dice a tu equipo qué hacer después.

De OAuth a la primera consulta

Inicia sesión con la cuenta de Google que gestiona tus fichas y otorga el acceso. Las ubicaciones se importan automáticamente, incluyendo estado de verificación, categorías, horarios, reseñas y medios, y las redes muy grandes se importan con un trabajo reanudable para que una cuenta de 2.000 fichas no sea un ejercicio manual.

Luego elige tu superficie. Los equipos de operaciones trabajan en el editor masivo y la bandeja de reseñas; los analistas usan las vistas agregadas de rendimiento; los desarrolladores y agentes de IA se conectan por MCP con un asiento acotado. Los tres leen los mismos datos normalizados, así que no hay desviación entre lo que reporta un agente y lo que ve un gerente.

Si estás evaluando, la prueba significativa más rápida es un cambio masivo real sobre un subconjunto filtrado pequeño — horarios especiales en una ciudad — y luego el mismo trabajo en toda una región. Si aguanta en los dos tamaños, aguantará en el tuyo.

El modelo de datos normalizado detrás de la API

Google devuelve el mismo concepto de negocio en varias formas según la familia de API que consultes. Las ubicaciones vienen de Business Information, las métricas de Performance, las reseñas y respuestas de una superficie heredada aparte, y los medios de otra distinta. Los nombres de campo, los formatos de identificador y la granularidad temporal no siempre coinciden.

Mapgrid normaliza todo eso en un solo modelo: una entidad de ubicación con identificadores estables, sus categorías, atributos, horarios y estado de verificación; filas de rendimiento como series temporales por día y métrica; reseñas con estado de respuesta e idioma; activos de medios con categoría y procedencia; y hallazgos NAP que vinculan un campo con su valor canónico en Google.

Esa normalización es lo que hace baratas las preguntas que cruzan superficies. Correlacionar una caída de calificación con un descenso en solicitudes de ruta, o comprobar si las sucursales con hallazgos NAP abiertos también rinden peor en llamadas, es una sola consulta contra formas consistentes en lugar de tres reconciliaciones contra tres APIs.

• Identificadores de ubicación estables en todas las superficies
• Series temporales diarias de rendimiento por métrica
• Reseñas con idioma, estado de respuesta e histórico completo
• Hallazgos NAP que vinculan un campo con el valor canónico de Google