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

BasicAuth

AuthorizationstringRequired

Query parameters

weekstringOptional

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

Example: 2023-10-31

Body

application/json

typestringOptional

Polygon or MultiPolygon

Example: Polygon

Responses

200

Successful operation

application/json

400

Invalid GeoJSON Polygon/MultiPolygon

403

Forbidden (couldn't extract valid API key)

post

/imagery/poly

JavaScriptPython

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

/devices

HTTPcURLJavaScriptPython

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

BasicAuth

AuthorizationstringRequired

Responses

200

Account balance

application/json

403

Forbidden (couldn't extract valid API key)

get

/balance

HTTPcURLJavaScriptPython

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

BasicAuth

AuthorizationstringRequired

Query parameters

limitintegerOptional

Max results to return

Example: 100

skipintegerOptional

Results to skip

Example: 0

Responses

200

Paginated API transactions

application/json

get

/history

HTTPcURLJavaScriptPython

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.