API Reference

Returns street-level imagery frames captured during a specific week within your polygon boundary. Use this for historical imagery queries or when you need data from a particular time period.

Each frame includes:

• Signed URL to download the image (expires after a limited time)
• Timestamp and GPS position with accuracy metrics (hdop, pdop, etc.)
• IMU data (accelerometer, gyroscope) at capture time
• Device type and image dimensions

Use /map-data instead if you need: point+radius queries, route-based queries, or both imagery and map features together.

Constraints:

• Max area: 5 sq km per request
• Coordinates: [longitude, latitude] order
• Image URLs are temporary—download promptly

> Billing: Imagery URLs returned in the response are metered per view. Each unique view deducts from your account's USD balance. See beemaps.com/pricing for details.

Returns the freshest available street-level imagery within your polygon, optionally filtered to exclude data older than a specified week. Use this when you want current conditions rather than historical data.

Ideal for:

• Real-time condition monitoring
• Verifying current state of a location
• Getting the newest available frames regardless of specific date

Constraints:

• Max area: 5 sq km per request
• Coordinates: [longitude, latitude] order

> Billing: Imagery URLs returned in the response are metered per view. Each unique view deducts from your account's USD balance. See beemaps.com/pricing for details.

Access action-rich video clips with synchronized ego-vehicle data for training AI driving systems and world models.

Search and retrieve video segments capturing specific driving behaviors and scenarios—harsh braking, lane changes, stop sign interactions, swerving maneuvers, and more.

Use Cases

• World model training data — Video clips paired with ego-vehicle actions (speed, steering, acceleration) for action-conditioned generation
• Edge case mining — Surface rare, safety-critical scenarios (near-misses, emergency maneuvers, unusual agent interactions) that are expensive or dangerous to collect intentionally
• Behavior cloning datasets — Real driver responses to real-world stimuli with ground-truth control outputs
• Simulation validation — Benchmark synthetic scenarios against authentic driving events

Response Data

Each event includes:

• Event type and timestamp
• GPS location
• Associated metadata (speed, acceleration, speed history array, etc.)
• Video URL (signed, temporary) when available

Constraints

• Date range must not exceed 31 days
• Max 500 results per request

Retrieve detailed information about a specific AI-detected driving event, including the video clip URL and synchronized ego-vehicle data.

Returns

• Event type and timestamp
• GPS location
• Associated metadata (speed, acceleration, firmware version, etc.)
• Video URL (signed, temporary) when available
• Optional: Frame-level sensor data (GPS + IMU)

Sensor Data Expansion

Use query parameters to optionally include frame-level sensor data:

• ?includeGnssData=true - Include GPS coordinates array (lat, lon, alt, timestamp)
• ?includeImuData=true - Include IMU array (accelerometer/gyroscope readings with timestamps)
• ?includeGnssData=true&includeImuData=true - Include both

Note: Sensor data adds 50-200 KB to response size. Only request when needed for detailed analysis, path reconstruction, or ML training.

Use this endpoint after searching to access the full event details and video for analysis, training, or validation purposes.

The primary endpoint for accessing Hivemapper road intelligence. Returns detected road features (speed limits, stop signs, turn restrictions, fire hydrants, lane lines) and/or street-level imagery within your specified geometry.

Use this endpoint when you need:

• Both imagery and map features in a single request
• Point-based queries with radius (e.g., whats within 100m of this location')
• Route-based queries with buffer (e.g., whats along this delivery path')
• Polygon-based queries for arbitrary areas

Common use cases: fleet route validation, robotaxi pickup/dropoff zone checks, POI verification, AI training data collection, infrastructure auditing.

Geometry options:

• Point with radius (meters): circular area query
• LineString with buffer (meters): corridor along a route
• Polygon: arbitrary boundary

Constraints:

• Max query area: 5 sq km. Split larger areas into multiple requests.
• Coordinates must be [longitude, latitude] order (GeoJSON standard).
• startDate defaults to 1 week ago if not specified for imagery queries.

Returns map features (road signs, infrastructure, lane markings) detected within your polygon boundary. Each feature includes precise positioning, confidence score, and feature-specific properties.

Feature types include:

• speed-limit-sign: Posted speed with value, unit (mph/kph), regulatory status
• stop-sign, yield-sign: Intersection control
• turn-restriction-sign: No left/right/U-turn indicators
• traffic-light: Signal locations
• fire-hydrant: Hydrant positions (useful for parking/dropoff validation)
• lane-line: Lane markings for determining road width and lane count
• parking-restriction-sign: No parking, time-limited zones
• highway-sign: Route markers and exit signs

Each feature includes:

• position: lon, lat, azimuth (direction sign faces), physical dimensions
• confidence: Detection confidence score (0-1)
• observed.firstSeen / observed.lastSeen: Detection timestamps
• properties: Feature-specific data (e.g., speed limit value)

Use /map-data instead if you need: point+radius queries, route-based queries, or both imagery and features together.

Constraints:

• Max area: 5 sq km per request
• Coordinates: [longitude, latitude] order
• Currently available in US, EU, and UK

Creates bursts that incentivize Hivemapper drivers to map specific locations. Once created, bursts appear in the Bee App and trigger push notifications to nearby drivers.

Use this when:

• You need fresh coverage of a location with stale or missing imagery
• You want to ensure an area gets mapped before a specific date
• Existing data doesn't meet your recency requirements

Input options:

• Point with radius: Specify center coordinates and radius in meters
• Polygon: Specify exact boundary to cover

Coverage timing (depends on local driver density):

• Urban areas: Often within hours to 1-2 days
• Suburban: Typically 1-3 days
• Rural: May take several days or longer

After creating a burst:

1. Monitor status via GET /bursts (check isHit field)
2. Query new imagery via /latest/poly or /map-data once coverage arrives

Returns a paginated list of bursts you've created, with their current status and coverage information.

Use this to:

• Check if bursts have been hit (driver collected imagery in the area)
• Monitor burst expiration dates
• Audit your burst creation history

Key fields in response:

• status: active (waiting for coverage), expired, or refunded
• isHit: true if a driver has mapped the burst area
• latestHitAt: Timestamp when coverage was detected
• validUntil: Burst expiration date

Returns camera intrinsic parameters (focal length, distortion coefficients) for each camera device type. No authentication required.

Use this when:

• Processing imagery for computer vision tasks
• Undistorting images for accurate measurements
• Building 3D reconstructions or photogrammetry pipelines

Device types:

• hdc: Hivemapper Dashcam (original)
• hdcs: Hivemapper Dashcam S
• bee: Bee camera

Parameters returned:

• focal: Focal length
• k1, k2: Radial distortion coefficients

Send JSON-RPC messages to the MCP server using Streamable HTTP transport.

Returns a paginated log of your past API queries, including the geometry queried, credits consumed, and timestamps.

Use this to:

• Audit API usage patterns
• Debug unexpected credit consumption
• Generate usage reports
• Review which areas you've queried

Each history entry includes:

• area: Query area in sq km
• credits: Credits consumed
• payload: The geometry you queried
• timestamp: When the query was made
• weeks: Which data weeks were included

Returns the video requests you've created, newest first.

To poll for newly fulfilled requests, pass since set to the time of your last check.

Once a request is fulfilled, its videos field lists the qualifying videos, each with a signed download URL. Until then, videos is omitted.

Signed URLs expire after 24 hours. Call this endpoint again to get fresh URLs.

Creates a request for fresh video footage covering a polygon, or driving along a LineString, during a time window. Bee drivers are rewarded for recording qualifying video inside the area.

Video only qualifies if it is:

• Recorded inside the requested area between validFrom and validUntil
• Recorded within the optional local time-of-day window (the time zone is taken from the requested location)
• At least 1080 pixels high and at least 15 frames per second
• For a LineString, driven along the line in the direction it is drawn

Constraints:

• geojson must be a Polygon between 10 m² and 50,000 m², or a LineString up to about 950 m long
• A LineString needs at least two positions 1 m apart
• validFrom must be before validUntil
• eligibleLocalTimeStart and eligibleLocalTimeEnd are milliseconds since local midnight (0 to 86399999). When both are given, start must be before end

To make sure a request is only created once, pass an idempotencyKey. Retrying the same request with a key you've already used returns the id of the request first created with it. Using the key for a different request is rejected with 409. Neither creates anything new.

After creating a request, poll GET /requestVideo/{id} until videos is present.

Returns one of your video requests. Once it is fulfilled, videos lists the qualifying videos, each with a signed download URL that expires after 24 hours.

Returns 404 if the request doesn't exist or belongs to another account.

Cancels one of your active video requests. Video recorded after cancellation won't be collected.

Returns 404 if the request doesn't exist, belongs to another account, or is no longer active (already fulfilled, expired or cancelled).