Map Image API

The Map Image API is the network's first Map API enabling forwarding looking businesses and organizations to use the decentralized map.

API Routes

The Hivemapper Network API receives HTTPS requests and returns JSON responses.

The base url is https://hivemapper.com/api/

API routes have the following structure: <apiBaseUrl>/<freshnessLimit>/<apiMethod>/<args>/<...>

  • apiBaseUrl - the api base you are hitting

  • freshnessLimit - this is a date in YYYY-MM or YYYY-MM-DD format that designates the limit of how far back you want to reach, i.e., return all content collected on or after this date.

  • apiMethod - see below for more information, but typically methods are either coverage or consume calls

    • coverage calls are free and return the number of results contained by a query

    • consume calls will return the assets contained by the query

API Key

All requests must have your username and API Key attached as an Authorization header. Please contact us for an API Key.

headers: {
authorization: "Basic <Base64 encoded string of username:apiKey>"
}

For example,

curl -X GET \
https://hivemapper.com/api/dashcam/v1/2021-05-01/consume/box/-96.784994/32.856266/40 \
-H "Authorization: Basic <Base64 encoded string of username:apiKey>"

Query Parameters

We support query parameters that apply to all coverage and consume endpoints.

Dashcam

  • mount - optionally specify a mount position to filter on for dashcam content:

    • front - front facing

    • side - side facing

Query for Coverage

Coverage request queries are free, and they return the available number of files that would be returned for each area and recency you are requesting.

For example,

# How much data is available in some area newer than some maximum-age date
# defined by a date in YYYY-MM-DD format,
# <lat, lon> degree coordinates and a radius in meters
GET
https://api.hivemapper.com/dashcam/v1/YYYY-MM-DD/coverage/box/lon/lat/radius
=> JSON { count: <number files that would be returned by a consumption query> }

URL Parameters

  • mode

    • dashcam dascham imagery at street level

    • orthoairborne based imagery from drone

  • date

    • YYYY-MM-DD - an ISO 8601 style string specifying a date in UTC to return data that was collected on or after

Dashcam

The coverage endpoints mirror the consume endpoints listed below under Fetch Content, see there for parameter descriptions and output shapes.

GET coverage/tile/<z>/<x>/<y> - count content for a web mercator tile

GET coverage/box/<lon>/<lat>/<radius> - count content for a web mercator box

POST coverage/polygon - count content for a geojson polygon

Fetch Content

If there is coverage in the area you want and you want to retrieve the content you do so with the Retrieve Content request. Only successful requests to retrieving content incurs an API charge, and will be billed by only the areas contained with content. There are two types of API retrieve requests - one for dashcam ground based imagery and one for aerial

Dashcam

Hivemapper currently offers high resolution raw 4k street-level imagery.

An optional URL query parameter mount can be added to filter based on mount type with possible values:

  • all - both front and side facing

  • side - side facing

  • front - front facing

GET consume/tile/<z>/<x>/<y> - fetch content for a web mercator tile

# return content collected on or after May 1st, 2021 (UTC) for a tile <10, 20, 24>
curl -X GET \
https://hivemapper.com/api/dashcam/v1/2021-05-01/consume/tile/10/20/24 \
-H "Authorization: Basic <Base64 encoded string of username:apiKey>"

GET consume/box/<lon>/<lat>/<radius> - fetch content for a web mercator box

  • lon - longitude of box center (degrees)

  • lat - latitude of box center (degrees)

  • radius - radius of box (meters), i.e., given a circle with radius at this point, define a box that contains it

  • returns 24-hour signed urls asJSON { "assets": [<urls>] }

# return content collected on or after May 1st, 2021 (UTC) for a box in Dallas
curl -X GET \
https://hivemapper.com/api/dashcam/v1/2021-05-01/consume/box/-96.784994/32.856266/40 \
-H "Authorization: Basic <Base64 encoded string of username:apiKey>"

POST consume/polygon - fetch content for a geojson polygon

  • body - geojson polygon

    • JSON { "polygon": { "type": "Polygon", "coordinates": [<number>, <number>] } }

      • optionally include a custom crs

  • returns 24-hour signed urls asJSON { "assets": [<urls>] }

# return content collected on or after May 1st, 2021 (UTC) for a polygon covering roads in Dallas
curl -X GET \
https://hivemapper.com/api/dashcam/v1/2021-05-01/consume/box/-96.784994/32.856266/40 \
-H "Content-Type: application/json" \
-H "Authorization: Basic <Base64 encoded string of username:apiKey>" \
-d '{
"type": "Polygon",
"coordinates": [
[
[
-96.77354335784912,
32.79034113533471
],
[
-96.77277088165283,
32.791243058853645
],
[
-96.77740573883057,
32.79521141367352
],
[
-96.76624774932861,
32.804374029124304
],
[
-96.76693439483643,
32.80509545480257
],
[
-96.77937984466553,
32.79517533851821
],
[
-96.77354335784912,
32.79034113533471
]
]
]
}'

In the near future we will release an interactive query tool, but for now, we recommend using https://geojson.io/ if you don't already have a method of producing geojson data

Additionally, each dashcam image is encoded with metadata describing its:

  • precise location

  • mount position (when available)

  • camera intrinsics

  • speed

Airborne

Hivemapper currently offers high resolution 256x256 L18 tiles with a target GSD less than 6cm/pixel. Hivemapper provides access to its ortho data via a Tile API using Google Maps Tile Coordinates, also known as Slippy Tilenames.

# Via a Tile API using Google Maps Tile Coordinates, also known as Slippy Tilenames.
# Get ortho imagery at <x, y> that's newer than some minimum date YYYY-MM-DD
GET https://api.hivemapper.com/ortho/YYYY-MM-DD/consume/18/x/y
--> RESP <raw data>
# Via a Tile API using Google Maps Tile Coordinates zoom level and lon, lat.
# Get ortho imagery at <x, y> that's newer than some minimum date YYYY-MM-DD
GET https://api.hivemapper.com/ortho/YYYY-MM-DD/consume/18/lon/lat?lla=1
--> RESP <raw data>
# This will return the most recent ortho tile imagery file for the desired location
that's newer than some maximum-age collection date, or a 404 if not found.

Additionally, each ortho image is encoded with metadata describing its

  • precise location

  • camera intrinsic data

  • camera extrinsic data

In the near future we will also return airborne content in GeoTiff format

Example - Fetching Dashcam Imagery (Node.js )

const request = require('request-promise');
// this is the root url of all the dashcam api requests
const dashcamApi = `https://hivemapper.com/api/dashcam/v1`;
// take your username and API key delimited by a `:`
const credentials = `${USERNAME}:${API_KEY}`;
// base64 encode it
const encoded = Buffer.from(credentials).toString('base64');
// and append it to a string `Basic `
const authorization = `Basic ${encoded}`;
// this is your authorization header
const headers = { authorization };
/**
* Helper to make an api call to fetch assets contained by
* box on a mercator-projected earth
*
* contentSince - specify a time filter to return data that was collected
* greater than to equal to some date
* dates are typically in YYYY-MM-DD format, but you can
* use any valid JS-compatible ISO 9601 timestamp or seconds since epoch
*
* lon - longitude in degrees of box center
* lat - latitude in degrees of box center
* radius (meters) describes a circle centered at these coordinates
* (we'll draw a box around it and that's our query)
*/
async function makeConsumeBoxApiCall(contentSince, lon, lat, radius) {
const apiCall = `consume/box`;
const uri = [dashcamApi, contentSince, apiCall, lon, lat, radius].join('/');
const response = await request({
method: 'GET',
uri,
headers
});
return response;
}
const results = await makeConsumeBoxApiCall(
'2020-05-01',
-96.784994,
32.856266,
40
);
console.log(response);
// { "assets": [url1, url2, url3, ...] }
// urls point to images and will expire in 24 hours