API Documentation

Ingest one event or a batch (max 1000). The camera auto-registers to your org on first sight. Each event needs at least ts (unix seconds) and tracking_id.

curl -X POST http://localhost:8000/events \
  -H "X-API-Key: aa_..." -H "Content-Type: application/json" \
  -d '{"events":[{
    "ts": 1753600000, "camera_id": "cam-01", "tracking_id": "cam-01:p1",
    "age": 30, "gender": "male", "dwell_seconds": 12.4,
    "viewing": true, "viewing_seconds": 5.1, "confidence": 0.92
  }]}'

{ "ok": true, "count": 1 }

Footfall & unique visitors. total_unique_people counts distinct people; total_visits counts visits (a person who leaves and returns after a gap is one person but a new visit); repeat_visitors is how many of those people came back more than once. Same split per hour under by_hour.

{
  "total_unique_people": 3,
  "total_visits": 4,
  "repeat_visitors": 1,
  "by_hour": [{ "hour": "2026-07-27T12:00:00+05:30", "people": 3, "visits": 4 }],
  "filter": { "min_events": 5, "min_dwell_seconds": 1.5 }
}

Gender split + age distribution. Age is the median per person (robust to per-frame jitter); gender is the per-person mode. mask breaks down how many wore a face mask, and avg_confidence (0..1) is how much to trust the age/gender (masked / off-angle faces score low). age_by_gender gives the age groups split by gender — female and male as separate distributions (0-10 … 70+), never combined. Query params: ?viewers_only=true (only people who looked at the screen) and ?min_confidence=0.5 (drop low-trust masked / off-angle guesses). All accept ?camera_id= / ?device_id=, ?location_id=.

{
  "gender_split": { "male": 1, "female": 2, "unknown": 0 },
  "gender_pct": { "male": 33.3, "female": 66.7, "unknown": 0.0 },
  "age_distribution": { "18-24": 1, "25-34": 2 },
  "age_brackets": { "21-30": 2, "31-40": 1 },
  // age groups split by gender — female vs male, counted separately
  "age_by_gender": {
    "female": { "0-10": 0, "21-30": 2, "31-40": 0, "70+": 0 },
    "male":   { "0-10": 0, "31-40": 1, "51-60": 0, "70+": 0 }
  },
  "avg_age": 24.3,
  "mask": { "masked": 1, "unmasked": 2 },
  "glasses": { "with_glasses": 1, "without_glasses": 2 },
  "avg_confidence": 0.82,
  "avg_mood": 0.31,                // -1 negative .. +1 positive
  "emotion_distribution": { "happy": 2, "neutral": 1, "sad": 0 },
  "viewers_only": false
}

Facial-expression breakdown of the audience — how many people read as happy (smiling), neutral, sad, angry, surprise, fear or disgust. Counted per person (each visitor's dominant expression across their frames), so a lingering smile isn't counted a hundred times. Returns per-emotion counts and percentages, an average mood valence (−1 negative .. +1 positive) with a mood_label, the dominant_emotion, a smiling headline (count + rate), a positive / neutral / negative sentiment rollup, and an hourly by_hour mood + smile trend. Same scoping as demographics: ?camera_id= / ?device_id=, ?location_id=, ?content_id=, ?viewers_only=true, ?from=&to=.

curl "http://localhost:8000/analytics/emotion?camera_id=entrance" \
  -H "X-API-Key: aa_..."

{
  "people": 6,
  "avg_mood": 0.17, "mood_label": "positive",
  "dominant_emotion": "happy",
  "emotion_distribution": { "happy": 2, "surprise": 1, "neutral": 1, "sad": 1, "angry": 1, "fear": 0, "disgust": 0 },
  "emotion_pct": { "happy": 33.3, "neutral": 16.7, … },
  "smiling": { "count": 2, "rate": 33.3 },
  "sentiment": { "positive": 3, "neutral": 1, "negative": 2 },
  "sentiment_pct": { "positive": 50.0, "neutral": 16.7, "negative": 33.3 },
  "by_hour": [ { "hour": "2026-08-07T18:00", "avg_mood": 0.2, "happy": 12, "faces": 36 } ]
}

Historical trend bucketed by day, week or month — visitors, gender split, avg age, avg dwell, viewers and avg mood per bucket. Query params: ?period=day|week|month (default day), plus the usual ?camera_id= / ?device_id=, ?location_id=, ?from=&to=. With no window it returns the last ~30 days (day), ~12 weeks (week) or ~6 months (month). Ideal for daily / weekly / monthly reports and charts.

curl "http://localhost:8000/analytics/trends?period=day&camera_id=HVQA" \
  -H "X-API-Key: aa_..."

{
  "period": "day", "from": "2026-07-08T…", "to": null,
  "buckets": [
    { "bucket": "2026-08-06", "visitors": 128, "male": 70, "female": 58,
      "male_pct": 54.7, "female_pct": 45.3, "avg_age": 31.2,
      "avg_dwell_seconds": 22.4, "viewers": 61, "avg_mood": 0.18 }
  ],
  "totals": { "visitors": 128, "viewers": 61, "buckets": 1 }
}

Dwell-time stats across qualified visitors.

{ "people": 3, "avg_dwell_seconds": 20.6, "min_dwell_seconds": 7.1, "max_dwell_seconds": 37.1 }

Attention (opportunity-to-see): how many present people actually looked at the screen (head pose), the viewer rate, viewing time, and the demographics of the viewers — who looked, not who merely walked past.

{
  "people": 3, "viewers": 1, "viewer_rate": 0.333,
  "avg_viewing_seconds": 4.1, "avg_dwell_seconds": 6.0,
  "viewer_gender_split": { "male": 0, "female": 1 },
  "avg_viewer_age": 28.0
}

Who is in front of the camera right now (default window 10s). Optional ?window= seconds and ?camera_id=.

{
  "current_people": 1, "current_viewers": 1, "crowded": false,
  "people": [{ "tracking_id": "cam-01:p1", "gender": "female", "age": 25, "viewing": true }],
  "cameras": [{ "camera_id": "cam-01", "online": true }]
}

Live occupancy vs the crowd threshold.

{ "occupancy": 0, "threshold": 3, "status": "normal", "crowded": false }

Precomputed hourly rollup for fast dashboard queries. Refresh it with POST /admin/rollups/refresh (admin/manager).

{ "hourly": [{ "hour": "2026-07-27T12:00:00+05:30", "camera_id": "cam-01", "people": 3, "avg_dwell": 10.5 }] }

Per-content attribution — impressions (people who looked), view rate and attention per ad/creative that was playing (from each event's content_id). The core DOOH monetisation metric.

{ "content": [{ "content_id": "ad-nike", "impressions": 2, "people": 2, "view_rate": 1.0, "avg_attention_seconds": 3.0 }] }

Programmatic-DOOH audience feed: per-screen opportunity-to-see, impressions, and an impression_multiplier (the camera's extrapolation factor → estimated reach).

{ "screens": [{ "screen_id": "cam-01", "opportunity_to_see": 3, "impressions": 2, "impression_multiplier": 2.0, "estimated_impressions": 4 }] }

Register/name a camera and start its analyzer. Returns the camera_id used for everything after.

curl -X POST http://localhost:8000/camera/session/start \
  -H "X-API-Key: aa_..." -H "Content-Type: application/json" \
  -d '{"name": "Entrance - Main Store"}'
# → {"camera_id": "entrance-main-store", ...}

Report the device details & location captured on connect — model, GPS latitude/longitude, and any extra info. Shown in the dashboard.

curl -X POST http://localhost:8000/cameras/entrance-main-store/device \
  -H "X-API-Key: aa_..." -H "Content-Type: application/json" \
  -d '{"device_name": "Galaxy A54", "latitude": 12.9716, "longitude": 77.5946}'

Frame mode — send the raw JPEG bytes of each frame (~5 fps, 640×480). The server detects people, age, gender, dwell and viewing.

curl -X POST "http://localhost:8000/camera/frame?camera_id=entrance-main-store" \
  -H "X-API-Key: aa_..." -H "Content-Type: image/jpeg" \
  --data-binary @frame.jpg

Stop the camera's analyzer when the device disconnects.

Register a device under your org (no new key minted). Returns the camera_id + a pairing_code.

curl -X POST http://localhost:8000/devices \
  -H "X-API-Key: aa_..." -H "Content-Type: application/json" \
  -d '{"name": "Entrance - Main Store", "device_code": "YE7F"}'
# → {"camera_id": "entrance-main-store", "pairing_code": "E7JV46GV"}

The app claims a device by its code — the code IS the credential (single-use). Returns the existing camera's id, location, org and the org api_key.

curl -X POST http://localhost:8000/devices/pair \
  -H "Content-Type: application/json" -d '{"code": "E7JV46GV"}'

Issue a fresh pairing code (e.g. after the old one was claimed).

A device reports image quality {blur, brightness}; the API derives a status (good / blurry / dark / washed_out / covered).

List cameras for your org — id, name, location, device code, device, GPS, live/offline status and last-seen.

One device's full record plus a quick stats summary — people seen, visits, events, and how many are in view right now.

{
  "id": "usb-camera", "name": "Front Entrance", "pair_code": "HVQA",
  "location_name": "Main Store", "online": true, "health_status": "good",
  "stats": { "unique_people": 63, "visits": 63, "events": 13599, "current_people": 9 }
}

device_id is accepted everywhere as an alias for camera_id — the response also echoes both.

Everything for one device in a single call. Bundles people, demographics, dwell, viewing, attention, live, occupancy and content, all scoped to this device. Accepts the same ?from=&to= window. {camera_id} may be the device_id too. Saves you several round-trips when a dashboard opens a single device. A metric that can't compute comes back as {"error": …} instead of failing the whole payload.

curl "http://localhost:8000/cameras/usb-camera/analytics" \
  -H "X-API-Key: aa_..."

{
  "device_id": "usb-camera", "camera_id": "usb-camera",
  "window": { "from": null, "to": null },
  "people": { "total_unique_people": 63, "total_visits": 71, … },
  "demographics": { "gender": {…}, "age": {…}, "avg_mood": 0.31, … },
  "dwell": {…}, "viewing": {…}, "attention": {…},
  "live": {…}, "occupancy": {…}, "content": {…}
}

Rename a device, assign a location, set a custom device_code, or set the extrapolation_factor. The camera_id itself is fixed — the name is a label you can change anytime.

curl -X PUT http://localhost:8000/cameras/cam-01 \
  -H "X-API-Key: aa_..." -H "Content-Type: application/json" \
  -d '{"name": "Front Entrance", "location_id": 1, "device_code": "HVQA"}'

List locations (each with a camera count and timezone).

curl -X POST http://localhost:8000/locations \
  -H "X-API-Key: aa_..." -H "Content-Type: application/json" \
  -d '{"name": "Front Store", "timezone": "Asia/Kolkata"}'

Recent crowd threshold-crossing alerts for your org.

View or change the crowd threshold, live window, and webhook URL.

curl -X PUT http://localhost:8000/config/alerts \
  -H "X-API-Key: aa_..." -H "Content-Type: application/json" \
  -d '{"threshold": 5, "webhook_url": "https://you.example.com/hook"}'

Download raw events or the hourly rollup as CSV. Accepts the same ?from=&to= window.

curl "http://localhost:8000/export/hourly.csv?from=2026-07-27T00:00:00" \
  -H "X-API-Key: aa_..." -o hourly.csv