# Bee Maps — Complete API Reference

> This is the expanded LLM reference for Bee Maps Data APIs. For a concise overview, see [llms.txt](https://beemaps.com/llms.txt).

## Base URL

```
https://beemaps.com/api/developer
```

## Authentication

Two methods are supported (all endpoints accept both):

1. **Query Parameter** (works on all endpoints):
   ```
   ?apiKey=<API_KEY>
   ```

2. **Basic Auth Header**:
   ```
   Authorization: Basic <API_KEY>
   ```

Get an API key at https://beemaps.com/developers

---

## Endpoints

### 1. Street-Level Imagery

#### POST /latest/poly

Query the most recent dashcam frames within a GeoJSON polygon.

**Query Parameters:**
- `headings` (boolean, optional) — include orientation data per frame
- `min_week` (string, optional) — YYYY-MM-DD, earliest week to include

**Request Body:** GeoJSON Polygon geometry

```json
{
  "type": "Polygon",
  "coordinates": [[
    [-122.420, 37.780],
    [-122.410, 37.780],
    [-122.410, 37.790],
    [-122.420, 37.790],
    [-122.420, 37.780]
  ]]
}
```

**Response:**
```json
{
  "frames": [
    {
      "url": "https://...",
      "timestamp": "2026-01-15T18:32:10Z",
      "position": { "lat": 37.785, "lon": -122.415 },
      "device": "bee",
      "sequence": "abc123",
      "idx": 42,
      "width": 2028,
      "height": 1024
    }
  ]
}
```

**Pricing:** $0.005 per image

---

### 2. Map Features (Road Detections)

#### POST /map-data

Query ML-detected road objects by geometry. Pass a Point with radius or a Polygon.

**Request Body:**
```json
{
  "type": ["mapFeatures"],
  "geometry": {
    "type": "Point",
    "coordinates": [-122.413, 37.786],
    "radius": 250
  }
}
```

**Response:**
```json
{
  "totalCreditsUsed": 25,
  "totalCreditsRemaining": 10000,
  "mapFeatureResults": {
    "type": "mapFeatures",
    "data": [
      {
        "id": "feat_abc123",
        "class": "speed-sign",
        "status": "active",
        "position": { "lat": 37.785, "lon": -122.415, "azimuth": 180 },
        "properties": {
          "speedLimit": 35,
          "unit": "mph"
        },
        "confidence": 0.94,
        "observed": {
          "firstSeen": "2025-11-01T00:00:00Z",
          "lastSeen": "2026-01-20T00:00:00Z"
        },
        "n_detections": 3
      }
    ],
    "creditsUsed": 25
  }
}
```

**Detection Classes:** speed-sign, stop-sign, fire-hydrant, traffic-light, parking-restriction, turn-restriction-sign, crosswalk

**Coverage:** US, EU, UK

**Pricing:** $3 per 1,000 detections

---

### 3. AI Event Videos

#### POST /aievents/search

Search for AI-detected driving event videos. Date range must be 31 days or less.

**Request Body:**
```json
{
  "startDate": "2026-01-01T00:00:00Z",
  "endDate": "2026-01-31T00:00:00Z",
  "types": ["HARSH_BRAKING", "SWERVING"],
  "limit": 50,
  "offset": 0
}
```

**Event Types:** HARSH_BRAKING, AGGRESSIVE_ACCELERATION, SWERVING, HIGH_SPEED, HIGH_G_FORCE, STOP_SIGN_VIOLATION

**Response:**
```json
{
  "data": [
    {
      "id": "evt_abc123",
      "type": "HARSH_BRAKING",
      "timestamp": "2026-01-15T14:30:00Z",
      "lat": 37.785,
      "lng": -122.415,
      "videoUrl": "https://...",
      "duration": 8.5
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}
```

#### GET /aievents/{id}

Retrieve a single AI event by ID. Optionally include high-frequency sensor data.

**Query Parameters:**
- `includeGnssData` (boolean, optional) — include ~1Hz GPS trace
- `includeImuData` (boolean, optional) — include ~100Hz 6-axis IMU

**Response:** Same as search item, plus optional `gnssData` and `imuData` arrays for complete sensor data.

**Pricing:** $6 per video

---

### 4. Burst (On-Demand Mapping)

#### POST /burst/create

Request fresh imagery at specific locations.

**Request Body:** Array of location objects
```json
[
  {
    "geojson": {
      "type": "Point",
      "coordinates": [-122.413, 37.786],
      "radius": 50
    },
    "credits": 125
  }
]
```

**Response:**
```json
[
  {
    "id": "burst_abc123",
    "status": "active",
    "location": { "lat": 37.786, "lng": -122.413 },
    "geojson": { "type": "Polygon", "coordinates": [[...]] },
    "validFrom": "2026-01-15T00:00:00Z",
    "validUntil": "2026-02-14T00:00:00Z",
    "credits": 125
  }
]
```

#### GET /bursts

List all burst requests and their statuses.

**Response:**
```json
{
  "bursts": [
    {
      "id": "burst_abc123",
      "status": "active",
      "location": { "lat": 37.786, "lng": -122.413 },
      "hit": false,
      "hitTimestamp": null,
      "credits": 125
    }
  ],
  "total": 100,
  "limit": 100,
  "skip": 0
}
```

**Statuses:** active, expired, refunded, completed

**Pricing:** $1 per location (pay only on success)

---

### 5. Utility Endpoints

#### GET /balance

Check remaining API credits.

**Response:**
```json
{
  "balance": 4250.50,
  "currency": "USD"
}
```

#### GET /history

Query API usage history with credit consumption. Returns `{ history: [...] }`.

#### GET /devices

Returns camera calibration parameters keyed by device type (`hdc`, `hdc-s`, `bee`). No authentication required.

---

## Error Codes

| Code | Meaning |
|------|---------|
| 400  | Bad Request — invalid geometry, missing required fields, malformed JSON, or date range > 31 days |
| 403  | Forbidden — missing or invalid API key |
| 402  | Payment Required — insufficient credits |
| 429  | Too Many Requests — rate limit exceeded |

## Rate Limits

- Default: 100 requests/minute per API key
- Burst creation: 10 requests/minute
- Contact sales for higher limits

## Pricing Summary

| Product | Price |
|---------|-------|
| Street-Level Imagery | $0.005/image |
| Map Features (Road Detections) | $3/1K detections |
| AI Event Videos | $6/video |
| Burst (On-Demand Mapping) | $1/location |

No upfront commitments. Full pricing at https://beemaps.com/pricing

## Links

- Documentation: https://docs.beemaps.com
- API Playground: https://beemaps.com/developers?tab=playground
- Code Examples: https://beemaps.com/examples
- OpenAPI Spec: https://beemaps.com/openapi.json
- Pricing: https://beemaps.com/pricing
- Contact: https://beemaps.com/contact