API de reseñas de Google Maps: seleccione 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 su 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 le 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 usted sepa 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. Aplique la plantilla a su entorno operativo solo después de confirmar la autorización específica para leer, procesar, almacenar y visualizar los datos.

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

Cuando gestione negocios que tenga autorización para operar, consulte 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 necesita responder a los comentarios de los usuarios, hágalo 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 su tarea consiste en retirar una respuesta errónea que usted escribió, trátela por separado de una evaluación de usuario que considere inapropiada, sin asumir un uso idéntico solo por ver un ejemplo de DELETE.

Al mostrar detalles de ubicaciones en un producto, puede 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. Respete 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 pueda acumularlos a largo plazo, revenderlos por lotes ni volver a exhibirlos libremente. Ajuste su diseño si el uso planeado excede los permisos, en lugar de reemplazar el criterio de autorización con soluciones técnicas.

Si necesita los parámetros específicos de la ruta oficial de gestión de comerciantes, examine 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 traslade sus campos o reglas de paginación como una garantía para EveryInfra.

Paso 1: verifique 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. Confirme la referencia del sitio, la dirección y la pertenencia comercial en su lista de objetivos antes de emitir solicitudes de reseñas.

Conserve la URL completa de la ubicación que utilizó en la solicitud, así como el place_id obtenido de forma confiable. Combine registros únicamente cuando la identidad esté confirmada; evite fusionar reseñas de dos tiendas basándose tan solo en la proximidad de coordenadas, nombres idénticos o similitudes de texto. Envíe 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. Dé 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: compruebe 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 abrevie 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. Mantenga criterios de selección idénticos y guarde 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 introduzca otro código de idioma basándose en descripciones genéricas. Evite 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ícelo como filtro cuando sea preciso y valide por separado las fechas límite frente a los resultados obtenidos.

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

Los supuestos siguientes asumen que ha configurado EVERYINFRA_API_KEY y una EVERYINFRA_MAPS_PLACE_URL verificada en su servidor. Envíe el ejemplo una sola vez y sitúe 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. Examine primero el estado HTTP y el error, y compruebe 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. Mantenga un estado desconocido si desconoce la causa real; si el cliente agota el tiempo de espera, no reintente un POST de forma automática presuponiendo que la ejecución o tarificación previa no ocurrieron.

Paso 4: separe 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 replique 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}'

Procese 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. Conserve el estado desconocido si falta rating; al realizar comparaciones entre plataformas, evalúe el campo junto con rating_scale y evite promediar directamente cifras procedentes de escalas diferentes.

detailed_rating, si se devuelve, puede albergar calificaciones multidimensionales, pero no asuma 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.

Guarde 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: cree 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. Compruebe 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.

Guarde los campos necesarios para las comparaciones descritas únicamente dentro del alcance y los plazos permitidos por las licencias; si no puede retener el texto, ajuste 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 usted visualizó 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, puede 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, puede 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 asuma 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.

Consigne 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; evite 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 desea contrastar tipos de problemas, defina 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 visualiza, 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 emplea Places API para exposiciones públicas, cumpla los requisitos vigentes sobre atribución de contenido, información del autor y accesos de origen, en lugar de limitarse a copiar textos en su propia página. Si los datos proceden de otra ruta, determine 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, priorice 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 evite 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.

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

Al concluir la primera ronda de integración, debe ser capaz de explicar por qué está autorizado para procesar este conjunto de datos, cuál es el negocio objetivo, qué ordenamiento e idioma seleccionó, 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, debe 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 puede responder a todas estas cuestiones, proceda a ampliar su 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.