Informes y analíticas - Rhombus Developer Documentation

Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, contáctenos.

Descripción general

El Report Webservice de Rhombus convierte las detecciones de sus cámaras en analíticas agregadas y agrupadas por tiempo. En lugar de recorrer eventos individuales, usted solicita un informe de conteo para un rango de tiempo y un intervalo, y Rhombus devuelve un punto de datos por cada segmento (bucket) con un conteo por tipo. A través de la API, puede:

Crear series temporales de conteo de personas, vehículos, movimiento, rostros y otros tipos de detección a nivel de organización, ubicación o dispositivo
Seguir conteos de personas y ocupación con las lecturas más recientes y tendencias de ocupación agrupadas
Medir conteos de cruce de línea (umbral) de personas o vehículos que cruzan una línea configurada
Exportar datos de informes como CSV para hojas de cálculo, herramientas de BI e informes de cumplimiento

Se aplican algunas convenciones en toda esta API:

Las marcas de tiempo están en milisegundos epoch en los endpoints V2, de ocupación y de umbral (startTimeMs / endTimeMs). El endpoint heredado v1 getCountReport usa cadenas de fecha "YYYY-MM-DD" en su lugar.
Los informes se describen con tres enumeraciones: un tipo de informe (qué contar), un intervalo (tamaño del segmento) y un alcance (organización, ubicación o dispositivo). Consulte las tablas de referencia más abajo.
No existe un endpoint para “listar tipos de informe”. Los tipos disponibles son fijos y están documentados en la tabla ReportType.

Requisitos previos

Antes de comenzar, asegúrese de tener:

Una clave de API de Rhombus con permisos de informes (generada en la Consola de Rhombus en Settings > API)
Al menos una cámara desplegada y reportando las analíticas que desea consultar (por ejemplo, una cámara con conteo de personas o LPR)
El UUID de la organización, ubicación o dispositivo al que desea limitar el informe
Para la exportación a CSV y los feeds de auditoría/diagnóstico: el permiso REPORT_ADMINISTRATION en la clave de API

Todas las solicitudes son POST, envían un cuerpo JSON y usan la URL base https://api2.rhombussystems.com con estos encabezados:

x-auth-scheme: api-token
x-auth-apikey: YOUR_API_KEY
Content-Type: application/json

Crear una serie temporal de conteo

getCountReportV2 es el endpoint principal de informes. Proporcione un rango de tiempo en milisegundos epoch, un intervalo, un alcance y uno o más tipos de informe. Rhombus devuelve un punto de datos por cada segmento del intervalo, cada uno con un eventCountMap indexado por tipo de informe. Este ejemplo obtiene conteos horarios de personas y vehículos para una sola ubicación durante las últimas 24 horas.

import requests
import time

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

now_ms = int(time.time() * 1000)
one_day_ago_ms = now_ms - (24 * 60 * 60 * 1000)

response = requests.post(
    "https://api2.rhombussystems.com/api/report/getCountReportV2",
    headers=headers,
    json={
        "scope": "LOCATION",
        "uuid": "YOUR_LOCATION_UUID",
        "types": ["PEOPLE", "VEHICLES"],
        "interval": "HOURLY",
        "startTimeMs": one_day_ago_ms,
        "endTimeMs": now_ms,
        "timeZone": "America/Los_Angeles"
    }
)

data = response.json()
for point in data.get("timeSeriesDataPoints", []):
    counts = point.get("eventCountMap", {})
    print(f"{point.get('dateLocal')}: "
          f"people={counts.get('PEOPLE', 0)}, "
          f"vehicles={counts.get('VEHICLES', 0)}")

Campos de la solicitud

scope

string

requerido

Nivel de agregación. Uno de ORG, LOCATION, DEVICE o REGION. Consulte la tabla ReportScope.

uuid

string

El UUID de la ubicación o dispositivo que coincide con su scope. Omítalo con scope: "ORG" para informar sobre toda la organización.

types

string[]

requerido

Uno o más tipos de informe a contar. Consulte la tabla ReportType.

interval

string

requerido

Tamaño del segmento de cada punto de datos. Uno de MINUTELY, QUARTERHOURLY, HOURLY, DAILY, WEEKLY, MONTHLY. Consulte la tabla ReportInterval.

startTimeMs

integer

requerido

Inicio del rango, en milisegundos epoch.

endTimeMs

integer

requerido

Fin del rango, en milisegundos epoch.

timeZone

string

Zona horaria IANA opcional (por ejemplo, America/New_York). Controla dónde caen los límites de los segmentos del intervalo y rellena dateLocal. Por defecto es UTC cuando se omite.

El endpoint V2 acepta los campos heredados startDate / endDate como cadenas, pero están obsoletos. Use en su lugar los campos en milisegundos epoch startTimeMs / endTimeMs.

Campos de la respuesta

timeSeriesDataPoints

object[]

Una entrada por cada segmento del intervalo.

Mostrar TimeSeriesDataPointV2Type

dateUtc

string

Inicio del segmento expresado en UTC.

dateLocal

string

Inicio del segmento expresado en la timeZone solicitada.

eventCountMap

object

Mapa de tipo de informe a conteo para este segmento, por ejemplo {"PEOPLE": 42, "VEHICLES": 7}.

reportingDevicesMap

object

Mapa de tipo de informe a la lista de UUID de dispositivos que aportaron conteos en este segmento.

¿Necesita un total único en lugar de una serie por segmentos? Llame a /api/report/getSummaryCountReport con los mismos startTimeMs, endTimeMs, interval, scope y un solo type.

Informes heredados con cadenas de fecha

El endpoint v1 /api/report/getCountReport es anterior a las marcas de tiempo en milisegundos epoch. Toma startDate y endDate como cadenas "YYYY-MM-DD" y un único type en lugar de un arreglo types. Prefiera getCountReportV2 para nuevas integraciones; use v1 solo si ya depende de su comportamiento con cadenas de fecha.

cURL

curl -X POST https://api2.rhombussystems.com/api/report/getCountReport \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{
    "scope": "LOCATION",
    "uuid": "YOUR_LOCATION_UUID",
    "type": "PEOPLE",
    "interval": "DAILY",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }'

Crear un panel de conteo de personas y ocupación

Para un panel en vivo, combine dos endpoints: getMostRecentPeopleCountEvents para las lecturas más recientes de una cámara y getOccupancyCountsV2 para una tendencia de ocupación agrupada en el tiempo.

Lecturas de conteo de personas más recientes

import requests

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api2.rhombussystems.com/api/report/getMostRecentPeopleCountEvents",
    headers=headers,
    json={
        "deviceUuid": "YOUR_CAMERA_UUID",
        "numMostRecent": 10
    }
)

data = response.json()
for event in data.get("events", []):
    print(f"[{event.get('eventTimestamp')}] people={event.get('peopleCount')}")

Cada entrada de events es una lectura de conteo de personas:

events

object[]

Mostrar PeopleCountEventType

uuid

string

Identificador único de la lectura.

deviceUuid

string

La cámara que produjo la lectura.

locationUuid

string

Ubicación a la que pertenece el dispositivo.

orgUuid

string

Identificador de la organización.

eventTimestamp

integer

Momento de la lectura en milisegundos epoch.

peopleCount

integer

Número de personas contadas en este momento.

imageS3Key

string

Clave S3 del fotograma asociado (una clave, no una URL).

boundingBoxes

object[]

Cuadros delimitadores de detección de las personas contadas.

deviceLabels

string[]

Etiquetas aplicadas al dispositivo.

locationLabels

string[]

Etiquetas aplicadas a la ubicación.

subLocationsHierarchyKey

string

Clave de jerarquía de sububicación, cuando está configurada.

Tendencia de ocupación en el tiempo

getOccupancyCountsV2 devuelve la ocupación agrupada de un dispositivo a lo largo de un rango de tiempo, usando el mismo modelo de intervalos que los informes de conteo.

import requests
import time

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

now_ms = int(time.time() * 1000)
one_day_ago_ms = now_ms - (24 * 60 * 60 * 1000)

response = requests.post(
    "https://api2.rhombussystems.com/api/report/getOccupancyCountsV2",
    headers=headers,
    json={
        "deviceUuid": "YOUR_CAMERA_UUID",
        "startTimeMs": one_day_ago_ms,
        "endTimeMs": now_ms,
        "interval": "HOURLY"
    }
)

data = response.json()
for point in data.get("timeSeriesDataPoints", []):
    print(f"{point.get('dateLocal')}: {point.get('eventCountMap')}")

Los timeSeriesDataPoints de la respuesta llevan los mismos campos dateUtc, dateLocal, eventCountMap y reportingDevicesMap que los informes de conteo, además de un timestampMs (inicio del segmento en milisegundos epoch) y un approximateTimestampMsMap.

Este informe de ocupación se deriva de las analíticas de la cámara mediante el Report Webservice. Es distinto del Occupancy Webservice (/api/occupancy/*), que lee sensores físicos BLE y de movimiento, un producto aparte.

Contar cruces de línea (conteos de umbral)

Cuando una cámara tiene configurada una línea de cruce, Rhombus cuenta los objetos que la cruzan. getThresholdCrossingCounts devuelve esos conteos agrupados en el tiempo para uno o más dispositivos, filtrados a una sola clase de objeto. El campo dailyResetTimeMinute establece el minuto del día (0–1439, en la hora local del dispositivo) en el que el conteo diario acumulado se reinicia: útil para alinear los conteos a una jornada comercial en lugar de a la medianoche.

import requests
import time

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

now_ms = int(time.time() * 1000)
one_week_ago_ms = now_ms - (7 * 24 * 60 * 60 * 1000)

response = requests.post(
    "https://api2.rhombussystems.com/api/report/getThresholdCrossingCounts",
    headers=headers,
    json={
        "devices": ["YOUR_CAMERA_UUID"],
        "startTimeMs": one_week_ago_ms,
        "endTimeMs": now_ms,
        "crossingObject": "HUMAN",
        "dailyResetTimeMinute": 0
    }
)

data = response.json()
for entry in data.get("counts", []):
    print(f"[{entry.get('timestampMs')}] crossings={entry.get('count')}")

Campos de la solicitud

devices

string[]

Uno o más UUID de cámaras a incluir en los conteos.

startTimeMs

integer

Inicio del rango, en milisegundos epoch.

endTimeMs

integer

Fin del rango, en milisegundos epoch.

crossingObject

string

La clase de objeto a contar. Los valores comunes son HUMAN y VEHICLE. Consulte la tabla CrossingObject.

dailyResetTimeMinute

integer

Minuto del día (0–1439) en el que se reinicia el conteo diario, en la hora local del dispositivo.

Campos de la respuesta

counts

object[]

Mostrar ThresholdCrossingCountType

count

integer

Número de cruces en este segmento.

timestampMs

integer

Inicio del segmento en milisegundos epoch.

Exportar datos de informes como CSV

El Export Webservice transmite los datos de informes como CSV (text/csv) en lugar de JSON. No existe exportación a PDF: CSV es el único formato de exportación.

Los endpoints de exportación (y los feeds de auditoría/diagnóstico) requieren el permiso REPORT_ADMINISTRATION en su clave de API. Sin él, estas llamadas se rechazan.

/api/export/countReports refleja los parámetros del informe de conteo pero devuelve un flujo CSV. Tenga en cuenta que la exportación toma un único campo type, no un arreglo types, y tanto startTimeMs como endTimeMs son obligatorios.

import requests
import time

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

now_ms = int(time.time() * 1000)
thirty_days_ago_ms = now_ms - (30 * 24 * 60 * 60 * 1000)

response = requests.post(
    "https://api2.rhombussystems.com/api/export/countReports",
    headers=headers,
    json={
        "scope": "LOCATION",
        "uuidList": ["YOUR_LOCATION_UUID"],
        "type": "PEOPLE",
        "interval": "DAILY",
        "startTimeMs": thirty_days_ago_ms,
        "endTimeMs": now_ms,
        "timeZone": "America/Los_Angeles"
    }
)

# La respuesta es texto CSV, no JSON
with open("people_count_report.csv", "w") as f:
    f.write(response.text)
print("Informe exportado a people_count_report.csv")

Como el cuerpo de la respuesta es CSV, léalo como texto (response.text / .text()) o escríbalo directamente en un archivo con la opción -o en cURL. No intente analizarlo como JSON.

Para exportar lecturas de conteo de personas sin agregar en lugar de informes agregados, use /api/export/peopleCountEvents con un startInterval y un endInterval (milisegundos epoch). Devuelve CSV de la misma manera.

Referencia de enumeraciones

Los informes se describen con un pequeño conjunto de enumeraciones fijas. No hay ningún endpoint que las liste en tiempo de ejecución: los valores siguientes son el conjunto completo.

ReportType

Valores aceptados por el arreglo types (V2) y el campo único type (v1 y exportación).

Valor	Cuenta
`CROWD`	Detecciones de densidad de multitud
`PEOPLE`	Detecciones de personas / conteo de personas
`FACES`	Detecciones de rostros
`MOTION`	Eventos de movimiento
`BANDWIDTH`	Uso de ancho de banda del dispositivo
`VEHICLES`	Detecciones de vehículos
`LICENSEPLATES`	Lecturas de matrículas
`ALERTS`	Eventos de alerta / política
`AM_VERIFICATION`	Verificaciones de monitoreo de alarmas
`DWELL`	Detecciones de tiempo de permanencia

ReportInterval

Tamaño del segmento de cada punto de datos.

Valor	Segmento
`MINUTELY`	Por minuto
`QUARTERHOURLY`	Cada 15 minutos
`HOURLY`	Por hora
`DAILY`	Por día
`WEEKLY`	Por semana
`MONTHLY`	Por mes

ReportScope

Nivel de agregación de un informe de conteo. Proporcione un uuid correspondiente para LOCATION, DEVICE o REGION; omítalo para ORG.

Valor	Agrega sobre
`ORG`	Toda la organización
`LOCATION`	Una sola ubicación
`DEVICE`	Un solo dispositivo
`REGION`	Una región configurada

CrossingObject

Clase de objeto para getThresholdCrossingCounts.

Valor	Objeto
`HUMAN`	Personas
`VEHICLE`	Vehículos
`FACE`	Rostros
`LPR`	Matrículas
`POSE`	Detecciones de pose
`CLIP_EMBED`	Coincidencias por embedding visual
`UNKNOWN`	Sin clasificar

Casos de uso

Paneles de tráfico peatonal: grafique conteos horarios o diarios de PEOPLE por ubicación con getCountReportV2 para comparar tiendas o seguir tendencias en el tiempo.
Monitoreo de ocupación: combine getMostRecentPeopleCountEvents (lectura en vivo) con getOccupancyCountsV2 (tendencia) para mostrar la ocupación actual e histórica en una sola pantalla.
Conteo de entradas y carriles: use getThresholdCrossingCounts con crossingObject: "HUMAN" o "VEHICLE" para contar personas por una puerta o vehículos por un carril.
Informes programados: ejecute /api/export/countReports con un cron y coloque el CSV en una herramienta de BI o un almacén de datos para informes semanales y mensuales.

Avanzado: analíticas con AI Scene Query

Rhombus también ofrece Scene Query, una función de IA que cuenta eventos personalizados definidos en lenguaje natural (por ejemplo, “montacargas sin señalador”). Scene Query se configura mediante los endpoints /api/scenequery/* y se informa a través de /api/report/getCustomEventsReport. Es una capacidad distinta y con licencia, más que parte del flujo de trabajo principal de informes anterior: trátela como una extensión opcional cuando los tipos de informe estándar no capturen lo que necesita medir.

Solución de problemas

timeSeriesDataPoints vacío o conteos todos en cero

Confirme que el dispositivo realmente produce la analítica que solicitó: una cámara sin conteo de personas habilitado no devuelve datos de PEOPLE. Verifique también que su rango de tiempo esté en milisegundos epoch (no segundos) y que el par scope/uuid sea correcto.

Los segmentos están desfasados respecto a la hora local

Establezca el campo timeZone en la zona IANA correspondiente (por ejemplo, America/Chicago). Sin él, los límites de los segmentos y dateLocal caen en UTC.

La solicitud de exportación es rechazada

La exportación a CSV requiere el permiso REPORT_ADMINISTRATION. Revise los permisos de la clave de API en la Consola de Rhombus y recuerde que el cuerpo de la exportación usa un único campo type en lugar del arreglo types que usa getCountReportV2.

La respuesta de exportación parece JSON corrupto

Los endpoints de exportación devuelven text/csv, no JSON. Lea la respuesta como texto o escríbala en un archivo en lugar de llamar a .json().

Próximos pasos

Rostros y conteo de personas

Registre personas, consulte eventos de rostros y profundice en las analíticas de conteo de personas

LPR y vehículos

Consulte lecturas de matrículas y detecciones de vehículos que alimentan los tipos de informe de vehículos

Referencia de la API

Explore los esquemas completos de solicitud y respuesta de cada endpoint de informe y exportación

​Descripción general

​Requisitos previos

​Crear una serie temporal de conteo

​Campos de la solicitud

​Campos de la respuesta

​Informes heredados con cadenas de fecha

​Crear un panel de conteo de personas y ocupación

​Lecturas de conteo de personas más recientes

​Tendencia de ocupación en el tiempo

​Contar cruces de línea (conteos de umbral)

​Campos de la solicitud

​Campos de la respuesta

​Exportar datos de informes como CSV

​Referencia de enumeraciones

​ReportType

​ReportInterval

​ReportScope

​CrossingObject

​Casos de uso

​Avanzado: analíticas con AI Scene Query

​Solución de problemas

​Próximos pasos

Rostros y conteo de personas

LPR y vehículos

Referencia de la API

Descripción general

Requisitos previos

Crear una serie temporal de conteo

Campos de la solicitud

Campos de la respuesta

Informes heredados con cadenas de fecha

Crear un panel de conteo de personas y ocupación

Lecturas de conteo de personas más recientes

Tendencia de ocupación en el tiempo

Contar cruces de línea (conteos de umbral)

Campos de la solicitud

Campos de la respuesta

Exportar datos de informes como CSV

Referencia de enumeraciones

ReportType

ReportInterval

ReportScope

CrossingObject

Casos de uso

Avanzado: analíticas con AI Scene Query

Solución de problemas

Próximos pasos