Skip to main content

AirDetect

AirDetect turns the Bluetooth Low Energy (BLE) radios already present in your AdmiralOS devices into real-time presence and footfall sensors. No new hardware, no extra installs - any device in a fleet with a BLE radio can measure how many people are nearby and for how long.

AirDetect measures presence, not people. It estimates anonymised visitor counts and dwell time from radio signals. It does not capture imagery, identify individuals, or track any one device's location.

Billed value-added service

AirDetect is an opt-in, usage-based service. You pay only for the presence you detect (per person, per minute), billed monthly on your existing invoice. There is no free tier and no minimum commitment.

How it works​

StageWhat happens
CaptureEach device with a BLE radio listens for nearby signals and turns them into anonymised presence detections.
AmalgamateDetections from every device in the fleet are centralised and exposed through a single, unified interface.
DetectDetection algorithms convert noisy radio data into clean presence counts and dwell times - never identities.
ActivateUse the data to trigger signage content, measure dwell, prove audience, or feed occupancy systems.

Because detection runs on-device, enabling AirDetect requires no redeployment of hardware. Devices begin reporting on their next check-in after the feature is enabled.

Who can do what​

AirDetect access is governed at the organisation level:

ActionRequired role
View status, usage, analytics, sessions, exportsAny organisation member (airdetect_viewer)
Enable / disable AirDetect on a fleetOrganisation admin (airdetect_admin)

Enabling or disabling AirDetect is a billed action, so it is restricted to admins. Members can freely view all analytics once the feature is on.

Billing standing

If the organisation has an outstanding billing issue (suspended or terminated account), AirDetect is locked. Status and analytics calls return a billing error until the issue is resolved. Resolve it under Settings → Billing.

Enabling AirDetect (Portal)​

AirDetect is managed from a fleet's detail page, under the AirDetect analytics section.

  1. Open the fleet and go to AirDetect Analytics.
  2. If you are an organisation admin, click Enable AirDetect.
  3. Read the confirmation - it reminds you this is a billed service - and click Confirm & Enable.
  4. Devices begin BLE detection on their next check-in. There may be a short delay before data appears.

If you are not an admin, you'll see a note explaining that only organisation admins can enable billed services. You can still view analytics once an admin turns it on.

Disabling​

Admins can disable AirDetect at any time from Manage subscription → Disable AirDetect.

Usage already accrued is still billed

Disabling stops billing for new usage. Any usage already accrued in the current period still appears on your invoice.

Viewing analytics (Portal)​

Once enabled, the AirDetect panel shows analytics for a selectable date range (defaulting to the current calendar month, UTC).

Headline metrics​

  • Visitors - total visitor sessions detected.
  • Unique - distinct visitors, with a returning rate.
  • Person-minutes - total presence time, plus median dwell.
  • Estimated cost - an estimate for the period. Your monthly invoice is the source of truth.
Estimates vs. invoice

Costs shown in the portal are estimates calculated from the same usage data. The authoritative charge is computed at invoice time from the billing roll-up.

Analytics tabs​

TabShows
OverviewDwell distribution (mean/median/percentiles), engagement by dwell bucket, proximity breakdown, device ecosystem mix, peak period, and average associated devices per visitor.
TrendsVisitor and unique-visitor counts over time, bucketed by an auto-selected granularity.
DevicesA per-device leaderboard. Click a device to drill into its own metrics and time series.
SessionsA raw session inspector - individual visits, newest first, with infinite scroll.

Exporting​

Click Export CSV to download the raw sessions for the selected range. The export streams row-by-row, so it stays fast and memory-light regardless of size. If the server reports a partial result, you'll be prompted to retry.

Session retention

Raw session detail is retained for a limited period (shown in the Session inspector). Aggregated usage used for billing is retained independently.

Using the API​

Everything in the portal is backed by a REST API under the fleet path. These endpoints are ideal for automation and integrations - typically driven by a Service Account.

All endpoints require the standard authentication headers and an X-Organization-ID header (see Service Accounts → Authentication).

MethodPathPurposeRequired entitlement
GET/fleets/{fleetId}/airdetectGet feature status (returns enabled: false rather than 404 when off)airdetect_viewer
PUT/fleets/{fleetId}/airdetectEnable / disable (billed action)airdetect_admin
GET/fleets/{fleetId}/airdetect/usagePeriod usage, estimated cost, per-device breakdownairdetect_viewer
GET/fleets/{fleetId}/airdetect/usage/detailFull fleet breakdown: dwell stats, buckets, time seriesairdetect_viewer
GET/fleets/{fleetId}/airdetect/devices/{deviceId}/usageSingle-device breakdownairdetect_viewer
GET/fleets/{fleetId}/airdetect/sessionsPaginated raw sessions (keyset cursor + filters)airdetect_viewer
GET/fleets/{fleetId}/airdetect/sessions/exportStreaming CSV export of raw sessionsairdetect_viewer

Status semantics​

The status endpoint deliberately returns enabled: false (HTTP 200) when the feature is off, so a UI can render the toggle state. The usage and analytics endpoints return 404 when AirDetect is not enabled on the fleet - the feature is hidden until activated.

Response codes to handle​

CodeMeaning
200Success
401Not authenticated
402Account is suspended or terminated - billing must be resolved
403Caller lacks the required entitlement (e.g. a viewer attempting to enable)
404Fleet not found / not accessible, or AirDetect not enabled

Common query parameters​

For usage, detail, sessions, and export endpoints:

  • start, end - RFC3339 timestamps. Defaults to the current calendar month (UTC) if omitted.
  • granularity (detail endpoints) - one of hour, day, week, month. If omitted, granularity is auto-selected from the span (and hour is clamped to day for spans over 14 days to avoid oversized series).

Sessions and export also accept filters: device_id, visitor_id, proximity, min_confidence, min_dwell, max_dwell. The sessions endpoint additionally takes limit (max 500, default 100) and a cursor for keyset pagination.

Example: check status​

curl -sS https://api.admrl.co/v1/fleets/$FLEET_ID/airdetect \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Organization-ID: $ORG_ID"
{
  "fleet_id": "550e8400-e29b-41d4-a716-446655440000",
  "enabled": true,
  "enabled_at": "2024-09-12T14:30:00Z"
}

Example: enable AirDetect (admin only)​

curl -X PUT https://api.admrl.co/v1/fleets/$FLEET_ID/airdetect \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Organization-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

A caller without airdetect_admin receives 403.

Example: usage summary​

curl -sS "https://api.admrl.co/v1/fleets/$FLEET_ID/airdetect/usage?start=2024-09-01T00:00:00Z&end=2024-09-30T23:59:59Z" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Organization-ID: $ORG_ID"
{
  "fleet_id": "550e8400-e29b-41d4-a716-446655440000",
  "period_start": "2024-09-01T00:00:00Z",
  "period_end": "2024-09-30T23:59:59Z",
  "visitor_count": 1284,
  "person_minutes": 45200.5,
  "estimated_cost_cents": 904,
  "devices": [
    {
      "device_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "visitor_count": 312,
      "person_minutes": 11050.0
    }
  ]
}

estimated_cost_cents is a UI estimate. The authoritative charge is computed at invoice time.

Example: export sessions to CSV​

curl -sS "https://api.admrl.co/v1/fleets/$FLEET_ID/airdetect/sessions/export?start=2024-09-01T00:00:00Z&end=2024-09-30T23:59:59Z" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Organization-ID: $ORG_ID" \
  -o airdetect_sessions.csv

The CSV columns are: session_id, organisation_id, fleet_id, device_id, visitor_id, first_seen, last_seen, dwell_seconds, dwell_bucket, proximity_bucket, confidence, associated_device_count, within_trial.

Streamed exports and truncation

The CSV is streamed with a 200 already sent, so it cannot switch to an error status mid-stream. If a server error occurs partway through, the export is truncated and a trailing line is written:

# ERROR: export truncated due to server error

Check for this sentinel line and retry if you see it.

Granting API access to a service account​

To let a Service Account use AirDetect, attach a policy with the appropriate organisation-level grants:

# Read-only: view status, usage, analytics, and exports
{ "airdetect_viewer", "organisation" }

# Manage: also enable/disable AirDetect (billed action)
{ "airdetect_admin", "organisation" }

Both grants are scoped to the organisation, not to individual fleets - a service account holding airdetect_viewer can read AirDetect data for any fleet in the organisation it has access to. Notably, the AirDetect viewer grant alone is sufficient to read; fleet viewer is not separately required.

Least privilege

For integrations that only read footfall data (dashboards, reporting, attribution), grant airdetect_viewer only. Reserve airdetect_admin for automation that genuinely needs to toggle the billed feature.

Privacy​

AirDetect is designed for audience insight without surveillance:

  • Presence, not identity. Counts and dwell are estimated within the bounds of BLE privacy. Individuals are not identified and individual device locations are not tracked.
  • Aggregated by design. Reporting is about how many people are present and for how long - not who they are.
  • No cameras, no PII. Presence is derived from anonymised radio signals. There is no imagery, facial data, or personally identifiable information in the pipeline.

Next Steps​