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@..."
    }
  ]
}

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
    },
  ]
}