Conceptos
Posiciones
Cuándo entrega la API una posición, qué significa location_withheld, cómo se representan las zonas de privacidad y qué precisión trae cada punto.
En esta página
Una posición es dónde está una persona. Es el dato más delicado de la API, y por eso sigue exactamente la misma regla que el panel: si una persona del panel con esos permisos no la ve, la API tampoco.
Cuándo se ve una posición
Lo decide el nivel de privacidad de cada centro (privacy_mode en GET /v1/sites):
- «Solo en emergencia» (
on_demand), el valor de serie. La posición de una persona solo se ve cuando tiene una alerta abierta con gravedad igual o superior aunveil_min_severity, durante una evacuación o con una solicitud aprobada en el panel. - Continuo (
continuous). La planta ha elegido ver las posiciones de forma continua.
Dentro de una zona de privacidad (vestuarios, comedores) no se registra la posición de nadie, con cualquier nivel.
En una alerta: location_withheld
Cada alerta trae location y location_withheld:
- Si la privacidad deja ver la posición,
locationla trae ylocation_withheldesfalse. - Si la posición existe pero no se entrega —en «Solo en emergencia», una alerta por debajo de la gravedad que destapa—,
location_withheldestrue. Tampoco se ve en el panel.
Tu sala tiene que contemplar los dos casos. Una alerta sin posición no es un error: es la planta protegiendo a su gente. Para ese caso, panel_url lleva a la ficha de la alerta en el panel.
Últimas posiciones
GET /v1/positions/latest (scope positions:read) devuelve las posiciones que la privacidad deja ver en ese instante. En «Solo en emergencia», quien no tiene nada abierto no aparece.
| Campo | Qué es |
|---|---|
device_id | El reloj. |
worker | La persona. |
location | La posición. |
in_vehicle | Si va en un vehículo. |
Cada posición que se sirve con una alerta detrás queda registrada en esa alerta, en «Quién ha visto su posición».
El objeto location
| Campo | Qué es |
|---|---|
latitude, longitude | Coordenadas WGS84. |
uncertainty_m | Radio de incertidumbre en metros. null si no se conoce, que no es lo mismo que tenerla perfecta. |
source | De dónde sale el punto. |
masked | true si el punto es el representativo de una zona de privacidad y no el de la persona. |
position_date_utc | Cuándo se tomó. |
height | Altura sobre el suelo por barómetro, con su incertidumbre, edificio y planta, cuando se puede afirmar. Si no, null. |
| source | Qué significa |
|---|---|
gps | GPS del reloj. |
network | Posición por red. |
zone | La persona estaba en una zona de privacidad: el punto es el de la zona, no el suyo. |
Pinta siempre el radio de uncertainty_m junto al punto: un punto sin radio da una precisión que no tiene.
Distancias sin posición
En una alerta crítica, nearby dice quién había a menos de 100 metros y a qué distancia, nunca dónde. Quien estaba en una zona de privacidad no cuenta. Ver Alertas.
No sigas a nadie en bucle
Consultar GET /v1/positions/latest cada pocos segundos no te da más que las alertas: en «Solo en emergencia» solo aparecen las personas que ya tienen una alerta abierta, y esa alerta ya te llega por webhook con la posición dentro. Además, cada consulta cuenta para tus límites de uso.