Bee Maps logoDOCS

Fleet Data APIs

Fleet Data APIs

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:

code
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

json
{
  "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

json
{
  "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)

json
{
  "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:

code
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

bash
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

json
{
  "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

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

Response Format

json
{
  "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:

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

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

json
{
  "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

json
{
  "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
    }
  ]
}
Previous
Fleet API & Webhook
Next
Fleet Data Webhooks