API de reseñas de Google Maps: elige el punto de acceso correcto antes de registrar ubicaciones y opiniones

La frase "quiero obtener reseñas de Google Maps" puede referirse a tres tareas distintas: administrar las valoraciones de tu propio negocio, mostrar información de un sitio en un producto o investigar los comentarios de los usuarios sobre un grupo de ubicaciones. Todas involucran reseñas, pero no emplean el mismo conjunto de permisos, interfaces ni reglas de almacenamiento. Aumentar el volumen de solicitudes o cambiar el método de análisis tras elegir la entrada incorrecta no resolverá el problema de fondo.

Esta guía te ayuda primero a seleccionar el flujo de trabajo y luego utiliza google_maps_reviews.reviews de EveryInfra para explicar cómo confirmar ubicaciones, construir solicitudes pequeñas, procesar valoraciones y respuestas de los comerciantes, y organizar la observación continua. El objetivo clave es que cada dato pueda asociarse con su ubicación correcta y que sepas explicar los vacíos en la muestra, en lugar de prometer la exportación de todo el historial de reseñas de cualquier sitio.

La fecha de verificación del índice y la implementación es 2026-09-04. Las solicitudes de pago de este ejemplo no se han ejecutado en esta ronda; los registros sintéticos del código se emplean únicamente para demostrar la comprobación de cambios en los campos. Aplica la plantilla a tu entorno operativo solo después de confirmar la autorización específica para leer, procesar, almacenar y visualizar los datos.

Selecciona el punto de acceso inicial: gestión de comerciantes, visualización de ubicaciones y lectura para investigación

Cuando gestiones negocios que tengas autorización para operar, consulta primero la API de Google Business Profile. Las guías oficiales de reseñas organizan las operaciones de lectura y respuesta del comerciante por cuenta y ubicación, y la conexión requiere el registro de aplicaciones y credenciales de OAuth. Si necesitas responder a los comentarios de los usuarios, hazlo bajo los permisos de administración correspondientes en lugar de enviar una solicitud genérica de escritura a cualquier enlace de mapas.

deleteReply en la guía oficial sirve para eliminar respuestas de la empresa, no la reseña original del usuario. Esta distinción importa en los flujos de trabajo operativos: si tu tarea consiste en retirar una respuesta errónea que escribiste, trátala por separado de una evaluación de usuario que consideres inapropiada, sin asumir un uso idéntico solo por ver un ejemplo de DELETE.

Al mostrar detalles de ubicaciones en un producto, puedes usar Place Details de Google Places API. Esta herramienta realiza consultas por identificador de lugar y emplea un FieldMask para seleccionar los campos requeridos; dicha ruta de visualización no equivale a una interfaz de exportación masiva de todas las reseñas históricas. Respeta los requisitos de almacenamiento, caché y atribución al utilizar contenidos de Places.

EveryInfra proporciona otro contrato de lectura: platform como google_maps_reviews, action como reviews y la URL del lugar como entrada. Las secciones siguientes describen exclusivamente esta ruta de lectura, omitiendo modificaciones de perfiles de tiendas, respuestas o eliminaciones, y sin calificarlo como una API oficial de Google.

Elegir una interfaz de terceros no elimina las restricciones de uso de datos. Los términos adicionales de Google Maps imponen límites a la copia, redistribución y descarga masiva; Places API también cuenta con sus propias reglas de contenido. El hecho de que una solicitud única devuelva datos no implica que puedas acumularlos a largo plazo, revenderlos por lotes ni volver a exhibirlos libremente. Ajusta tu diseño si el uso planeado excede los permisos, en lugar de reemplazar el criterio de autorización con soluciones técnicas.

Si necesitas los parámetros específicos de la ruta oficial de gestión de comerciantes, examina directamente reviews.list: localiza por cuenta y ubicación para proporcionar la lista de reseñas, la puntuación media global, el recuento total de opiniones y el marcador de la página siguiente. Esta estructura explica por qué el número de elementos obtenidos en una página y el total de valoraciones del sitio se manejan por separado; no traslades sus campos o reglas de paginación como una garantía para EveryInfra.

Paso 1: verifica la identidad del lugar y no solo el nombre comercial

El nombre de un establecimiento no constituye un identificador único estable. Una misma marca puede operar múltiples sucursales, y un distrito comercial puede albergar nombres similares; tras el cambio de nombre de un local, los registros anteriores no deben asociarse automáticamente a la nueva ubicación. Confirma la referencia del sitio, la dirección y la pertenencia comercial en tu lista de objetivos antes de emitir solicitudes de reseñas.

Conserva la URL completa de la ubicación que utilizaste en la solicitud, así como el place_id obtenido de forma confiable. Combina registros únicamente cuando la identidad esté confirmada; evita fusionar reseñas de dos tiendas basándose tan solo en la proximidad de coordenadas, nombres idénticos o similitudes de texto. Envía los objetivos inciertos a una lista de revisión pendiente para impedir que los análisis posteriores traten datos de tiendas incorrectas como tendencias de reclamaciones.

La implementación de lectura actual procesa la información de ubicación identificable en la URL, pero no toda dirección de mapas es igualmente apta para localizar un sitio. Los enlaces que solo contienen el nombre del negocio y las coordenadas de la vista de mapa no deben considerarse de forma autónoma como un ID de lugar confirmado. Da prioridad a los enlaces de origen completos y verificados, evitando construir direcciones temporales que simulen páginas de mapas.

Existe además un límite en la interfaz: que la implementación interna reconozca ciertos datos geográficos no significa que las peticiones públicas admitan añadir parámetros arbitrarios placeId o place_id. El parámetro obligatorio actual para reviews es url, y los clientes deben transmitir los datos según el contrato público.

Paso 2: comprueba las condiciones de idioma, ordenación y tiempo

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=google_maps_reviews' \
  | jq -e '.capabilities[] | select(.action == "reviews") | {
      platform, action, required_params, optional_params, param_meanings,
      mode, returns_list, default_limit, max_limit, response_fields
    }'

El directorio actual solicita url mediante una devolución de lista síncrona, con un recuento predeterminado de 20, un límite máximo de 100 y opciones que incluyen lang, language, since y sort. El identificador de plataforma exacto es google_maps_reviews; no lo abrevies como otro valor de platform basándose en los títulos de los artículos.

newest y relevance responden a intenciones de ordenamiento diferentes: el primero prioriza el contenido reciente y el segundo se enfoca en muestras de relevancia. No son páginas de datos intercambiables a voluntad. Mantén criterios de selección idénticos y guarda los ID de reseñas reales al comparar comercios; tras modificar el criterio de orden, los miembros de la muestra podrían cambiar.

El campo de idioma tampoco constituye un filtro de nacionalidad o residencia del autor. Los valores permitidos para lang se consultan en la enumeración de la interfaz (por ejemplo, los valores actuales en, zhcn y zhtw); no introduzcas otro código de idioma basándose en descripciones genéricas. Evita rellenar simultáneamente lang y language de forma ciega: en el mapeo actual, lang sobrescribe la configuración regional; basta con elegir inicialmente una opción claramente compatible.

since expresa el límite inferior de publicación de la reseña, y el directorio aconseja usar el formato YYYY-MM-DD. No representa la fecha de apertura del establecimiento, ni la fecha de actualización de la opinión, ni un cursor fiable sobre el procesamiento de los datos. Utilízalo como filtro cuando sea preciso y valida por separado las fechas límite frente a los resultados obtenidos.

Paso 3: comprueba un número reducido de resultados en una ubicación autorizada

Los supuestos siguientes asumen que has configurado EVERYINFRA_API_KEY y una EVERYINFRA_MAPS_PLACE_URL verificada en tu servidor. Envía el ejemplo una sola vez y sitúa limit dentro de params; colocarlo en el nivel superior de la solicitud no surtirá efecto como control de cantidad.

: "${EVERYINFRA_API_KEY:?configura primero la API Key}"
: "${EVERYINFRA_MAPS_PLACE_URL:?configura primero la URL completa autorizada del lugar}"
jq -cn --arg url "${EVERYINFRA_MAPS_PLACE_URL}" '{
  platform: "google_maps_reviews",
  action: "reviews",
  params: {url: $url, sort: "newest", limit: 3}
}' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

limit: 3 configura una muestra pequeña para facilitar la comprobación; esto no garantiza la devolución estricta de tres elementos ni implica que el lugar posea solo tres evaluaciones. 180 segundos representa un presupuesto de espera de ejemplo en el cliente y no un compromiso del servicio. Examina primero el estado HTTP y el error, y comprueba después si results arroja la lista esperada y si los registros corresponden al lugar buscado.

Una matriz vacía no equivale automáticamente a "este negocio no tiene opiniones". Puede deberse a la ausencia temporal de registros, o requerir la verificación del destino, los filtros o la accesibilidad. Mantén un estado desconocido si desconoces la causa real; si el cliente agota el tiempo de espera, no reintentes un POST de forma automática presuponiendo que la ejecución o tarificación previa no ocurrieron.

Paso 4: separa la puntuación de la ubicación, la calificación individual y las respuestas

Los campos actuales de los registros comprenden id, text, rating, rating_scale, posted_at, place_id, place_name, owner_response y owner_response_at, entre otros. La puntuación promedio en los detalles de la ubicación y la calificación de una reseña individual son entidades distintas; no repliques la nota media del establecimiento en cada opinión para rellenar valores vacíos.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=google_maps_reviews&action=reviews' \
  | jq '{fields, undocumented}'

Procesa la calificación y el cuerpo del texto por separado. Una entrada que contenga únicamente una puntuación sin texto puede servir para muestras de valoración, pero no debe introducirse directamente en la clasificación de temas de texto. Conserva el estado desconocido si falta rating; al realizar comparaciones entre plataformas, evalúa el campo junto con rating_scale y evita promediar directamente cifras procedentes de escalas diferentes.

detailed_rating, si se devuelve, puede albergar calificaciones multidimensionales, pero no asumas que todas las ubicaciones y reseñas cuentan con las mismas dimensiones. is_local_guide y la cantidad de reseñas históricas tampoco deben transformarse de forma directa en autenticación de usuario real o en puntuaciones de fiabilidad; se tratan de atributos proporcionados por la plataforma y no de una verificación de la exactitud fáctica de una opinión.

Guarda las respuestas de los comerciantes de forma separada. La ausencia de owner_response indica únicamente que dicho valor no se obtuvo en la ejecución actual, lo cual no prueba que el negocio jamás haya respondido; asimismo, obtener una respuesta posteriormente no significa que la reseña del usuario sea de reciente publicación. Mezclar ambos eventos como una nueva opinión generará alertas de incremento carentes de sentido.

Paso 5: crea registros separados para la identidad, la observación y los cambios

• Identidad de la ubicación: place_id verificado, referencia de origen y pertenencia comercial. Comprueba la identidad de tiendas duplicadas en lugar de fusionarlas basándose en el nombre.
• Identidad de la reseña: combinación de ID de lugar y de reseña; los registros sin un identificador fiable se manejan por separado, sin emplear el apodo del comentarista como clave única.
• Registro de observación: id de solicitud, hora de captura real, ordenamiento, condiciones de idioma o fecha, campos obtenidos y situaciones de ausencia.
• Registro de cambios: diferencias observables en el contenido, puntuación o respuesta del comerciante de una misma reseña, sin interpretar campos desconocidos como eliminaciones.

Guarda los campos necesarios para las comparaciones descritas únicamente dentro del alcance y los plazos permitidos por las licencias; si no puedes retener el texto, ajusta el registro al estado mínimo autorizado, evitando usar la conveniencia de auditoría como justificación para una retención indefinida. Los apartados siguientes emplean ubicaciones, reseñas y textos ficticios para ilustrar cómo distinguir cambios de valores, campos obtenidos por primera vez y datos no disponibles.

function compareReview(before, after) {
  const identity = row => {
    if (typeof row.place_id !== "string" || !row.place_id
        || typeof row.id !== "string" || !row.id) {
      throw new Error("place and review ids required");
    }
    return JSON.stringify([row.place_id, row.id]);
  };
  if (identity(before) !== identity(after)) throw new Error("different review");
  const t0 = Date.parse(before.observed_at);
  const t1 = Date.parse(after.observed_at);
  if (!Number.isFinite(t0) || !Number.isFinite(t1) || t1 <= t0) {
    throw new Error("observations must have increasing times");
  }
  const changed = [], firstObserved = [], notObserved = [];
  for (const field of ["text", "rating", "owner_response", "owner_response_at"]) {
    if (!Object.hasOwn(after, field) || after[field] == null) {
      notObserved.push(field);
    } else if (!Object.hasOwn(before, field) || before[field] == null) {
      firstObserved.push(field);
    } else if (before[field] !== after[field]) {
      changed.push(field);
    }
  }
  return {changed, firstObserved, notObserved};
}

console.log(compareReview(
  {place_id: "synthetic-place", id: "synthetic-review",
   text: "reseña sintética", rating: 3, observed_at: "2026-09-01T00:00:00Z"},
  {place_id: "synthetic-place", id: "synthetic-review",
   text: "reseña sintética", rating: 3, owner_response: "respuesta sintética",
   observed_at: "2026-09-02T00:00:00Z"}
));

Este ejemplo registrará owner_response como firstObserved en lugar de interpretarla como una reseña nueva; si la hora de respuesta no está disponible, se indicará como notObserved. Incluso si aparece text en changed, esto solo denota que el texto obtenido en ambas consultas difiere (lo que aún puede implicar traducciones o variaciones de representación), por lo que no debe afirmarse que el usuario editó el original si faltan pruebas.

Las comprobaciones de orden cronológico evitan únicamente que observaciones obsoletas sobrescriban registros más recientes, pero no garantizan la inmediatez de los datos del servidor. observed_at registra el momento en que visualizaste la respuesta, y no la fecha de actualización de los campos en la plataforma.

Al almacenar registros de observación entre distintas zonas horarias, puedes emplear formatos de tiempo con desplazamiento según el RFC 3339, manteniendo intacto el valor del origen original. La normalización del formato facilita exclusivamente la comparación temporal, sin transformar el tiempo de observación en la fecha de actualización de la reseña ni incrementar la cobertura de esta lectura.

Paso 6: la observación incremental debe explicar la cobertura y no limitarse a avanzar fechas

Al realizar supervisiones continuas, puedes observar repetidamente un conjunto fijo de ubicaciones bajo los permisos permitidos, conservando intervalos de superposición adecuados para el filtrado de fechas y aplicando deduplicación por identidad de reseña. La duración óptima del intervalo se determina según los retrasos registrados en la práctica y la frecuencia de las tareas, sin que exista un número de días genérico aplicable directamente desde una muestra pequeña.

Sin embargo, las ventanas superpuestas no resuelven todas las omisiones: los resultados individuales tienen límites de cantidad, las reseñas antiguas pueden recibir respuestas de comerciantes con posterioridad y el ordenamiento también modifica la muestra devuelta. En particular, no asumas que since capturará todas las opiniones antiguas modificadas, ya que se trata de un filtro de fecha de publicación y no de un flujo de cambios completo.

Consigna para cada ejecución el número de ubicaciones planificadas a comprobar, el recuento de sitios con registros disponibles, las ubicaciones fallidas o desconocidas y los elementos devueltos por cada sitio. Únicamente al conocer el alcance de la recolección, el orden y las condiciones de truncamiento se puede hablar de cobertura; evita dividir el volumen devuelto en una ejecución concreta entre un total de origen desconocido para simular una tasa de cobertura precisa.

La comparación entre tiendas requiere prudencia similar. La puntuación promedio de un puñado de reseñas recientes no equivale a la calificación total del lugar mostrada en el mapa; asimismo, un descenso en las notas no puede confirmarse basándose únicamente en un conjunto de muestras cambiantes. Si deseas contrastar tipos de problemas, define primero los criterios de clasificación antes de exhibir las ventanas de tiempo y los vacíos de las muestras por cada establecimiento.

Paso 7: el análisis, el procesamiento interno y la exposición pública poseen licencias distintas

La selección del idioma puede alterar la representación del contenido que visualizas, sin garantizar que cada reseña devuelta corresponda al texto original en dicha lengua. Los textos traducidos y los originales no deben considerarse opiniones de usuarios independientes; los resultados analíticos deben registrar las condiciones de idioma empleadas y conservar la revisión manual para los cambios multilingües.

Si empleas Places API para exposiciones públicas, cumple los requisitos vigentes sobre atribución de contenido, información del autor y accesos de origen, en lugar de limitarte a copiar textos en tu propia página. Si los datos proceden de otra ruta, determina primero las licencias aplicables sin aplicar ni eximir automáticamente las exigencias de Places. Los ejemplos almacenados en memoria descritos en este artículo no otorgan autorización de almacenamiento o republicación.

Para análisis internos, prioriza el tratamiento exclusivo de los campos necesarios para la tarea, limitando el acceso de usuarios y los plazos de retención; la clasificación por modelos y los niveles de urgencia deben marcarse como juicios derivados. El sistema puede organizar colas de revisión humana, pero evita responder de forma automática, contactar públicamente al autor o alterar el estado operativo del negocio basándose en una sola reseña de baja puntuación.

Verifica una ubicación por completo antes de ampliar el flujo de trabajo

Al concluir la primera ronda de integración, debes ser capaz de explicar por qué estás autorizado para procesar este conjunto de datos, cuál es el negocio objetivo, qué ordenamiento e idioma seleccionaste, qué campos están respaldados por evidencias, cómo se identifican los cambios en las respuestas y qué elementos faltaron en la ejecución. Asimismo, debes poder rastrear los problemas hasta el id de solicitud y verificar la facturación real, en lugar de conservar únicamente un archivo de reseñas anónimo.

Si puedes responder a todas estas cuestiones, procede a ampliar tu lista de ubicaciones o a incrementar las ejecuciones programadas. Un flujo de reseñas sostenible requiere no solo obtener datos, sino mantener claros en todo momento la identidad del sitio, el propósito, el alcance de las muestras y el registro de cambios.