Wherebox
On this page

Getting started

A map is one URL. No account, no SDK.

The first map: GET in an <img>#

GET/v1/map.png
GET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&w=468&h=280
Try it (opens the API in a new tab)
Czechia with a marker on Chřiby

Put that URL (with your host in front) into an image tag:

<img src="https://YOUR-HOST/v1/map.png?…the query above…" width="468" height="280" alt="Czechia, Chřiby highlighted">

What happened: area was looked up by name and framed, everything outside it faded, inner borders were drawn, and poi put a labeled marker on a named place. w and h are the size in CSS pixels. Commas, pipes and non-ASCII characters can stay as they are in a browser; use + or %20 for spaces and %23 for #.

Every parameter is listed in the query parameter reference. The area, poi and w/h parameters used above are area, poi, w and h.

The same map as a POST#

GET is convenient and cacheable, but URLs are limited in length and cannot carry some things (custom fonts, GeoJSON areas, more than one route, labels containing |). For those, send the same description as JSON to POST /v1/map with Content-Type: application/json:

POST/v1/map
{
  "area": "Czechia",
  "pois": [{ "place": "Chřiby", "marker": { "shape": "triangle" } }],
  "width": 468,
  "height": 280
}
Map rendered by the first-map-post example

The response is the image itself. Add ?response=json to the POST URL to get {url, key, meta, …} instead, where url points at the cached image (/v1/images/{key}, immutable, safe to store). The body fields are listed in the request body reference.

GET and POST describe the same thing; every example in these guides is labeled with the method it uses, and the GET ones can be turned into JSON and back.

Retina#

scale multiplies the pixel density without changing the layout: the image is w × scale pixels wide, and markers, labels and line widths grow with it.

GET/v1/map.png
GET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&w=360&h=220&scale=2
Try it (opens the API in a new tab)
A 360 by 220 map rendered at 2x

Use it with an <img> that has width="360" and let the browser downscale. See scale.

Formats#

Pick the format with the path extension (.png, .jpg, .webp) or with the format parameter. PNG is lossless and the default; JPEG and WebP take a quality.

GET/v1/map.webp
GET /v1/map.webp?area=Czechia&w=468&h=280&quality=85
Try it (opens the API in a new tab)
Map rendered by the webp-format example

See format and quality.