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
dashcam - https://hivemapper.com/api/dashcam/v1/​
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.
1
headers: {
2
  authorization: "Basic <Base64 encoded string of username:apiKey>"
3
}
Copied!
For example,
1
curl -X GET \
2
https://hivemapper.com/api/dashcam/v1/2021-05-01/consume/box/-96.784994/32.856266/40 \
3
-H "Authorization: Basic <Base64 encoded string of username:apiKey>"
Copied!
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,
1
# How much data is available in some area newer than some maximum-age date
2
# defined by a date in YYYY-MM-DD format,
3
# <lat, lon> degree coordinates and a radius in meters
4
​
5
GET 
6
https://api.hivemapper.com/dashcam/v1/YYYY-MM-DD/coverage/box/lon/lat/radius
7
​
8
=> JSON { count: <number files that would be returned by a consumption query> }
Copied!
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
​https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames​
z - zoom level (int)
x - tile x coordinate (int)
y - tile y coordinate (int)
returns 24-hour signed urls asJSON { "assets": [<urls>] }
1
# return content collected on or after May 1st, 2021 (UTC) for a tile <10, 20, 24>
2
curl -X GET \
3
https://hivemapper.com/api/dashcam/v1/2021-05-01/consume/tile/10/20/24 \
4
-H "Authorization: Basic <Base64 encoded string of username:apiKey>"
Copied!
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>] }
1
# return content collected on or after May 1st, 2021 (UTC) for a box in Dallas
2
curl -X GET \
3
https://hivemapper.com/api/dashcam/v1/2021-05-01/consume/box/-96.784994/32.856266/40 \
4
-H "Authorization: Basic <Base64 encoded string of username:apiKey>"
Copied!
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>] }
1
# return content collected on or after May 1st, 2021 (UTC) for a polygon covering roads in Dallas
2
curl -X GET \
3
https://hivemapper.com/api/dashcam/v1/2021-05-01/consume/box/-96.784994/32.856266/40 \
4
-H "Content-Type: application/json" \
5
-H "Authorization: Basic <Base64 encoded string of username:apiKey>" \
6
-d '{
7
      "type": "Polygon",
8
      "coordinates": [
9
        [
10
          [
11
            -96.77354335784912,
12
            32.79034113533471
13
          ],
14
          [
15
            -96.77277088165283,
16
            32.791243058853645
17
          ],
18
          [
19
            -96.77740573883057,
20
            32.79521141367352
21
          ],
22
          [
23
            -96.76624774932861,
24
            32.804374029124304
25
          ],
26
          [
27
            -96.76693439483643,
28
            32.80509545480257
29
          ],
30
          [
31
            -96.77937984466553,
32
            32.79517533851821
33
          ],
34
          [
35
            -96.77354335784912,
36
            32.79034113533471
37
          ]
38
        ]
39
      ]
40
    }'
Copied!
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.
1
# Via a Tile API using Google Maps Tile Coordinates, also known as Slippy Tilenames.  
2
# Get ortho imagery at <x, y> that's newer than some minimum date YYYY-MM-DD
3
​
4
GET https://api.hivemapper.com/ortho/YYYY-MM-DD/consume/18/x/y
5
​
6
--> RESP <raw data>
7
​
8
# Via a Tile API using Google Maps Tile Coordinates zoom level and lon, lat.
9
# Get ortho imagery at <x, y> that's newer than some minimum date YYYY-MM-DD
10
​
11
GET https://api.hivemapper.com/ortho/YYYY-MM-DD/consume/18/lon/lat?lla=1
12
​
13
--> RESP <raw data>
14
​
15
​
16
# This will return the most recent ortho tile imagery file for the desired location
17
that's newer than some maximum-age collection date, or a 404 if not found.
Copied!
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 )
1
const request = require('request-promise');
2
​
3
// this is the root url of all the dashcam api requests
4
const dashcamApi = `https://hivemapper.com/api/dashcam/v1`;
5
// take your username and API key delimited by a `:`
6
const credentials = `${USERNAME}:${API_KEY}`;
7
// base64 encode it
8
const encoded = Buffer.from(credentials).toString('base64');
9
// and append it to a string `Basic `
10
const authorization = `Basic ${encoded}`;
11
// this is your authorization header
12
const headers = { authorization };
13
​
14
/**
15
 * Helper to make an api call to fetch assets contained by
16
 * box on a mercator-projected earth
17
 *
18
 * contentSince - specify a time filter to return data that was collected
19
 * 	greater than to equal to some date
20
 * 	dates are typically in YYYY-MM-DD format, but you can
21
 * 	use any valid JS-compatible ISO 9601 timestamp or seconds since epoch
22
 *
23
 * lon - longitude in degrees of box center
24
 * lat - latitude in degrees of box center
25
 * radius (meters) describes a circle centered at these coordinates
26
 * (we'll draw a box around it and that's our query)
27
 */
28
async function makeConsumeBoxApiCall(contentSince, lon, lat, radius) {
29
  const apiCall = `consume/box`;
30
  const uri = [dashcamApi, contentSince, apiCall, lon, lat, radius].join('/');
31
  const response = await request({
32
    method: 'GET',
33
    uri,
34
    headers
35
  });
36
  return response;
37
}
38
​
39
const results = await makeConsumeBoxApiCall(
40
  '2020-05-01',
41
  -96.784994,
42
  32.856266,
43
  40
44
);
45
console.log(response);
46
// { "assets": [url1, url2, url3, ...] }
47
// urls point to images and will expire in 24 hours
Copied!
​