Map Image API

Fresh, geolocated street-level imagery from around the globe

Overview

Bee Maps designed the Map Image API to allow developers and enterprises to easily access imagery from the Hivemapper Network.

1. API Key Provisioning

  • Log in to Bee Maps

  • Go to Developers tabs

  • On Map Data API Keys click Generate API Key

  • Copy and save the Map API Key securely — it will only be shown once

  • Copy and save the Org ID.

2. Encoding and Authorization

Routes requiring Basic authorization

  • Encode the orgID and Map API Key in base64

  • The encoding format is OrgID:MapAPIKey

3. Image API Documentation

Access imagery for a specific week

post

Query imagery contained by a GeoJSON (Multi)Polygon for a given week

Authorizations
Query parameters
weekstringOptional

YYYY-mm-dd of a day in the week to query

Example: 2023-10-31
Body
typestringOptional

Polygon or MultiPolygon

Example: Polygon
Responses
200

Successful operation

application/json
post
const url = 'https://hivemapper.com/api/developer/imagery/poly'
const resp = await fetch(url,
  {
    method: 'post',
    body: JSON.stringify({
      coordinates: [
        [
          [-122.41927011115149,37.775414437036275],
          [-122.41605628337065,37.7763 86631642566],
          [-122.41597692959819,37.77889546188183],
          [-122.42299973845249,37.7772647319 11615],
          [-122.41927011115149,37.775414437036275]
        ]
      ],
      type: 'Polygon'
      }),
  headers: {
    'content-type': 'application/json',
    authorization: 'Basic XXXYYYZZZ'
  }
});
const data = await resp.json();
const frames = data.frames;

{
  "frames": [
    {
      "url": "https://www.cdn.com/image?signed=yoursdearly",
      "timestamp": "2023-11-09T02:30:48.974Z",
      "sequence": "60cb39e7cce2931a8cd2fa2d",
      "idx": 0,
      "device": "hdc",
      "position": {
        "lat": 37.76910370072376,
        "lat_ref": "n",
        "lon": -122.48185591741223,
        "lon_ref": "e",
        "gdop": 0.123,
        "hdop": 0.123,
        "pdop": 0.123,
        "eph": 0.123
      },
      "width": 2028,
      "height": 1024,
      "imu": {
        "acc_x": 0.123,
        "acc_y": 0.123,
        "acc_z": 0.123,
        "gyro_x": 0.123,
        "gyro_y": 0.123,
        "gyro_z": 0.123
      }
    }
  ],
  "creditsUsed": 42,
  "creditsRemaining": 1000000
}

Access dashcam device metadata

get

Fetch camera intrinsic parameters for dashcams

Responses
200

Camera Intrinsic Parameters

application/json
get
GET /api/developer/devices HTTP/1.1
Host: hivemapper.com
Accept: */*
200

Camera Intrinsic Parameters

{
  "device": {
    "focal": 0.1,
    "k1": 0.2,
    "k2": 0.3
  }
}

Balance of remaining API credits

get

Get remaining API Credits balance

Authorizations
Responses
200

Account balance

application/json
get
GET /api/developer/balance HTTP/1.1
Host: hivemapper.com
Authorization: Basic username:password
Accept: */*

{
  "balance": 42
}

Access query history

get

Fetch history of API queries

Authorizations
Query parameters
limitintegerOptional

Max results to return

Example: 100
skipintegerOptional

Results to skip

Example: 0
Responses
200

Paginated API transactions

application/json
get
GET /api/developer/history HTTP/1.1
Host: hivemapper.com
Authorization: Basic username:password
Accept: */*
200

Paginated API transactions

{
  "history": [
    {
      "area": 101.123,
      "credits": 4,
      "payload": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -122.48185591741223,
              37.76910370072376
            ]
          ]
        ]
      },
      "timestamp": "2023-11-09T03:09:40.131Z",
      "weeks": [
        "2023-10-31"
      ]
    }
  ]
}

Additional API Tools

Hive-Py is a Python wrapper for the Map Image API, see GitHub here.

Example query Python query using Hive-Py

> python -m imagery.query
usage: query.py [-h] -i INPUT_FILE [-s START_DAY] [-e END_DAY] [-L] [-x] [-d MAX_DIST] [-l MAX_LAG] [-z MAX_ANGLE] -o OUTPUT_DIR [-g] [-w WIDTH] [-M]
                [-I CUSTOM_ID_FIELD] [-S CUSTOM_MIN_DATE_FIELD] [-k] [-E] [-K SKIP_GEO_FILE] [-P IMAGE_POST_PROCESSING] -a AUTHORIZATION [-c NUM_THREADS] [-v]
                [-C] [-b] [-N]

API Billing

  • Cost

    • $1 per road km per week. For example, requesting imagery for the same 1 km of road over 3 weeks costs $3.

  • Billing Cycle

    • Charges are billed every two weeks to the credit card on file. If usage reaches $500 before the cycle ends, the card is charged immediately.

Sample Map Image API data

Before using the API, you can quickly evaluate a large set of sample imagery.

Imagery specs

  • Forward facing (interior or exterior mounted)

  • 1080p

  • Lane-level positional accuracy

  • Frames collected and uploaded every 6 to 8 meters — can be dynamically adjusted in certain regions.

PreviousDeveloper APIsNextRoad Intelligence API

Last updated