Fleet Data APIs

These endpoints allow you to securely access and interact with your fleet’s data, including device info, location updates, and trip history.

API Key Provisioning

• Log in to your Bee Maps Dashboard

• Go to Developers tabs

• On Fleet Data API Key click Generate API Key

• Copy and save the key securely — it will only be shown once

Authorization

All API requests require the API Key in the header:

Authorization: Bearer <your API key>

Devices API

Endpoint

GET https://api.trybeekeeper.ai/v1/devices

Returns a list of all devices in your fleet.

Response Format

{
  "devices": [
    {
      "id": "string",
      "serialNumber": "string",
      "name": "string",
      "description": "string",
      "deviceModel": "string",
      "firmwareVersion": "string",
      "vehiclePlate": "string",
      "imei": "string"
    }
  ]
}

Location API

Endpoint

GET https://api.trybeekeeper.ai/v1/location

Query Params

• deviceId (required)

Returns the latest known location of the specified device.

Response Format

{
  "device": { "id": "681da6f00000000000000000", "name": "Device A" },
  "lat": 37.7371066,
  "lon": -122.4027606,
  "speedKmH": 89.37,
  "timestamp": "2025-05-09T15:58:59.465Z"
}

Trips API

Endpoint

GET https://api.trybeekeeper.ai/v1/trips

Query Params

• deviceId (required)

• startDate (required, ISO format)

• endDate (required, ISO format)

Returns trips taken by a device within a specified date range.

Response Format (truncated for clarity)

{
  "device": { "id": "681da6f00000000000000000", "name": "Device A" },
  "startDate": "2025-03-29T00:00:00.000Z",
  "endDate": "2025-04-01T00:00:00.000Z",
  "totalDistanceKm": 169.49,
  "trips": [
    {
      "id": "681da7f00000000000000000",
      "firstStop": {
        "lat": 37.44178556,
        "lon": -122.15897415,
        "stopBeganAt": "2025-03-30T21:56:28.573Z",
        "stopEndedAt": "2025-03-30T22:23:22.322Z"
      },
      "secondStop": {
        "lat": 37.43422606,
        "lon": -122.20949056,
        "stopBeganAt": "2025-03-30T22:35:56.935Z",
        "stopEndedAt": "2025-03-31T14:43:54.499Z"
      },
      "distanceKm": 6.41,
      "durationMs": 754613,
      "polyline": "uvocFfmrhVSd@..."
    }
  ]
}

Fleet Video Incidents API

Query AI-detected driving events (harsh braking, swerving, speeding, etc.) across your fleet, including video clips and optional sensor data.

Authorization

All API requests require your Fleet Data API Key in the header:

Authorization: Bearer <your API key>

Keys with all scope (the default "Full Access" key) have access automatically. Keys with the aievents scope also have access.

Search Events

Endpoint

POST https://api.trybeekeeper.ai/v1/aievents/search

Request Body (JSON)

• startDate (required, ISO 8601 datetime) — beginning of the time range

• endDate (required, ISO 8601 datetime) — end of the time range. Range must be 31 days or less.

• deviceIds (optional, string array) — filter to specific device IDs

• types (optional, string array) — filter by event type. See Event Types below.

• polygon (optional, array of [lon, lat] coordinate pairs) — filter to events within a geographic area. The polygon must be closed (first and last point identical) and must not self-intersect.

• limit (optional, integer 1–500, default 100) — max events to return

• offset (optional, integer, default 0) — pagination offset

Example Curl Request

curl -X POST "https://api.trybeekeeper.ai/v1/aievents/search" \
  -H "Authorization: Bearer <your API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-02-01T00:00:00Z",
    "endDate": "2026-02-28T00:00:00Z",
    "types": ["HARSH_BRAKING", "HIGH_SPEED"],
    "limit": 50
  }'

Response Format

{
  "pagination": {
    "total": 263,
    "limit": 5,
    "offset": 0
  },
  "startDate": "2026-02-01T00:00:00.000Z",
  "endDate": "2026-02-27T23:59:59.000Z",
  "events": [
    {
      "id": "69a2237ec8d407cbf76aa063",
      "type": "SWERVING",
      "timestamp": "2026-02-27T23:05:57.750Z",
      "location": {
        "lat": 40.3326506,
        "lon": -74.3254135
      },
      "metadata": {
        "ACCELERATION_MS2": 1.141302,
        "SPEED_ARRAY": [
          { "AVG_SPEED_MS": 16.24, "TIMESTAMP": 1772233548000 },
          { "AVG_SPEED_MS": 15.18, "TIMESTAMP": 1772233552000 }
        ],
        "FIRMWARE_VERSION": "6.68.4"
      },
      "videoUrl": "https://...presigned-s3-url..."
    }
  ]
}

Get Event by ID

Endpoint

GET https://api.trybeekeeper.ai/v1/aievents/:id

Query Params

• includeGnssData (optional, true/false) — include high-frequency GPS data (lat, lon, altitude at millisecond resolution)

• includeImuData (optional, true/false) — include inertial measurement unit data (accelerometer + gyroscope)

Example Curl Request

curl "https://api.trybeekeeper.ai/v1/aievents/69a2237ec8d407cbf76aa063?includeGnssData=true&includeImuData=true" \
  -H "Authorization: Bearer <your API key>"

Response Format

{
  "id": "69a2237ec8d407cbf76aa063",
  "type": "SWERVING",
  "timestamp": "2026-02-27T23:05:57.750Z",
  "location": {
    "lat": 40.3326506,
    "lon": -74.3254135
  },
  "metadata": {
    "ACCELERATION_MS2": 1.141302,
    "FIRMWARE_VERSION": "6.68.4"
  },
  "videoUrl": "https://...presigned-s3-url..."
}

When includeGnssData=true, the response includes a gnssData array:

{
  "gnssData": [
    {
      "timestamp": 1772233548000,
      "lat": 40.3326506,
      "lon": -74.3254135,
      "alt": 42.1
    }
  ]
}

When includeImuData=true, the response includes an imuData array:

{
  "imuData": [
    {
      "timestamp": 1772233548000,
      "acc_x": 0.12,
      "acc_y": -0.03,
      "acc_z": 9.81,
      "gyro_x": 0.001,
      "gyro_y": -0.002,
      "gyro_z": 0.015
    }
  ]
}

Rewards API

Lists rewards information for all devices in fleet, for a given reward period. A reward period is a calendar week.

Endpoint

GET https://api.trybeekeeper.ai/v1/hivemapperRewards

Query Params

• rewardPeriod required. date must be a Monday e.g. 2025-05-12

Returns rewards for your devices in your fleet

Response Format

{
  "periodStart": "2025-04-28",
  "periodEnd": "2025-05-05",
  "devicesWithRewards": [
    {
      "deviceId": "6789bd99bfa474f4ca7d0001",
      "deviceName": "Device A",
      "rewardAmountHoney": 285.84,
      "rewardedTotalKms": 602.56,
      "rewardMountRating": 2
    },
    {
      "deviceId": "6789c4a14f09505cee530002",
      "deviceName": "Device B",
      "rewardAmountHoney": 453.87,
      "rewardedTotalKms": 1101.51,
      "rewardMountRating": 4
    },
    {
      "deviceId": "678acefa8e37f96443f60003",
      "deviceName": "Device C",
      "rewardAmountHoney": 253.15,
      "rewardedTotalKms": 803.73,
      "rewardMountRating": 3
    },
  ]
}