Generated from code

On this page

Wherebox API v0.2.0

Static locator-map images: highlight an area, fade the surroundings, add labeled points.

openapi.json License AGPL-3.0-only

GET `/v1/map`#

Render a map from query parameters

Path and header parameters

Name	In	Type	Description
`X-Provider-Key`	header	string	API key for a commercial basemap style
`X-Routing-Key`	header	string	API key for openrouteservice / GraphHopper routing

Query parameters

Name	In	Type	Description
`area`	query	string	The area to frame and highlight. Ambiguous names return 409 with candidates. Name, `iso:CZ`, `iso:CZ-72`, `osm:r51684` or `wikidata:Q213`. Country-level areas fall back to Natural Earth when the OSM import does not cover them (`area=Japan`, `iso:IT`); regions and cities need the OSM import. example `"Czechia"`
`level`	query	integer	Only match areas at this OSM admin level (2 = country; regions and municipalities vary by country). Narrows a name lookup (turns `area` into `{query, level}`). example `"8"`
`country`	query	string	Only match areas inside this ISO 3166-1 alpha-2 country. Narrows a name lookup. example `"CZ"`
`bounds`	query	string	Explicit frame `[west, south, east, north]`; overrides automatic framing. `west,south,east,north`. example `"12.09,48.55,18.86,51.06"`
`padding`	query	number	Space around the framed content as a fraction of the image size. example `"0.04"`
`projection`	query	"mercator" \| "globe" \| "auto"	Map projection. `mercator` is the usual flat web map. `globe` draws an orthographic globe, which keeps continent-spanning routes and high latitudes true to shape; the content must fit on one hemisphere (within 85° of the view center), and neighbor labels are not available. `auto` picks the globe when the content spans more than 50° or Mercator would stretch it more than 2.5× between its lowest and highest latitude, else Mercator. `mercator` (default), `globe` or `auto`. example `"globe"`
`globeview`	query	"full" \| "fit"	How much of the globe to show. `full` (default): the whole globe, centered on your content, with space around it; recognizable at a glance as a globe. `fit`: zoomed in until the content fills the image; a larger scale with more detail along the route, but only part of the globe is visible. `full` (default) or `fit`. example `"fit"`
`poi`	query	array of string	Points with markers and labels (up to 50). `lat,lon` or `place:Name`, followed by `\|option:value` pairs (see POI options). Repeat for more points. example `["49.13,17.33\|label:Chřiby\|marker:triangle"]`
`from`	query	string	Start point when the server should compute the line. `lat,lon` or `place:Name`. A route needs `from`+`to` or `polyline`. example `"40.4168,-3.7038"`
`to`	query	string	Finish point when the server should compute the line. example `"place:Sevilla"`
`via`	query	array of string	Points the route must pass through, in order. example `["38.98,-3.93"]`
`profile`	query	"car" \| "bike" \| "foot" \| "straight" \| "geodesic"	How endpoints are connected: routed by `car`/`bike`/`foot` (needs a routing engine on the server or your `X-Routing-Key`), or locally as `straight` segments or `geodesic` great-circle arcs. The default `geodesic` always works (no routing engine, key or plan feature needed) and is the true shortest path, so it suits flights and locator maps; ask for `car`/`bike`/`foot` explicitly for roads. example `"straight"`
`polyline`	query	string	The line as an encoded polyline (Google algorithm). URL-encode it (polylines can contain `\|`, `?` and `\`). example "_p~iF~ps\|U_ulLnnqC_mqNvxq`@"
`polylineprecision`	query	"5" \| "6"	Polyline precision: 5 (Google) or 6 (Valhalla/OSRM). example `"6"`
`routeprovider`	query	"valhalla" \| "openrouteservice" \| "graphhopper"	Routing provider (default: the server's). openrouteservice and GraphHopper need a key (server-side or `X-Routing-Key`). example `"valhalla"`
`routecolor`	query	string	Color of the route line. example `"#d01c1c"`
`routewidth`	query	number	Line width in px. example `"3"`
`routecasing`	query	string	Outline drawn under the line so it reads on busy basemaps. example `"#ffffff"`
`routedash`	query	string	Dash pattern in line widths, e.g. `[2, 1.5]`. Comma-separated. example `"2,1.5"`
`routeopacity`	query	number	Line opacity. example `"0.9"`
`fromlabel`	query	string	Label at this end (default: the place name, if the end was given as a place). example `"Madrid"`
`tolabel`	query	string	Label at this end (default: the place name, if the end was given as a place). example `"Sevilla"`
`frommarker`	query	"pin" \| "dot" \| "ring" \| "flag" \| "triangle" \| "circle" \| "square" \| "star" \| "diamond"	Marker preset. Defaults depend on the role: plain point → `pin`, route start → `ring`, route finish → `flag`. example `"dot"`
`tomarker`	query	"pin" \| "dot" \| "ring" \| "flag" \| "triangle" \| "circle" \| "square" \| "star" \| "diamond"	Marker preset. Defaults depend on the role: plain point → `pin`, route start → `ring`, route finish → `flag`. example `"pin"`
`showfrom`	query	string	`false` hides the marker and label for this end. example `"false"`
`showto`	query	string	`false` hides the marker and label for this end. example `"false"`
`w`	query	integer	Image width in CSS px (the output is width × `scale` pixels). example `"468"`
`h`	query	integer	Image height in CSS px, including the title band if any. example `"280"`
`scale`	query	integer	Pixel ratio for high-DPI output (2 = retina). example `"2"`
`format`	query	"png" \| "jpeg" \| "webp"	Image format (GET can also use the path extension: /v1/map.png, .jpg, .webp). Or use the path extension: `/v1/map.webp`. example `"webp"`
`quality`	query	integer	JPEG/WebP quality. example `"85"`
`attribution`	query	"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"	Corner for the data attribution (always drawn; required by the data licenses). example `"bottom-left"`
`preset`	query	"locator-relief" \| "light" \| "dark"	Built-in basemap: shaded relief (Wikipedia locator style), light, or dark. No key needed. example `"dark"`
`style`	query	string	Any MapLibre style.json URL; overrides `preset`. `{key}` in the URL is replaced with `providerKey`. URL-encode it. example `"https://api.maptiler.com/maps/streets-v2/style.json?key={key}"`
`key`	query	string	Key for a commercial style (prefer the `X-Provider-Key` header so it stays out of URLs). Prefer the `X-Provider-Key` header so the key stays out of URLs and logs. example `"your-provider-key"`
`fade`	query	number	How much the surroundings are washed out: 0 = not at all, 1 = fully covered. example `"0.6"`
`fadecolor`	query	string	Color the surroundings fade towards. URL-encode `#` as `%23`. example `"#ffffff"`
`outline`	query	string	Area outline color. example `"#555555"`
`outlinewidth`	query	number	Area outline width in px; 0 = none. example `"2"`
`tint`	query	string	Optional color tint drawn over the area. example `"#d03030"`
`tintopacity`	query	number	Opacity of `tint`. example `"0.12"`
`subdivisions`	query	"auto"	Inner admin borders: `auto` draws the next level that splits the area, a number forces that admin level, `false` hides them. `auto`, `false`, or an admin level number. example `"auto"`
`desaturate`	query	number	Outside the area: 0 = full color, 1 = grayscale (applied on top of `fade`). example `"0.8"`
`blur`	query	number	Outside the area: blur radius in CSS px; 0 = sharp. example `"1.5"`
`subarea`	query	string	A second, smaller area highlighted inside the framed one (e.g. a region within its country). example `"Zlínský kraj"`
`subareacolor`	query	string	Fill and outline color of `subArea`. example `"#c0392b"`
`subareaopacity`	query	number	Fill opacity of `subArea`. example `"0.35"`
`subareaoutlinewidth`	query	number	Outline width of `subArea` in px; 0 = none. example `"1.2"`
`worldview`	query	"ar" \| "bd" \| "br" \| "cn" \| "de" \| "eg" \| "es" \| "fr" \| "gb" \| "gr" \| "id" \| "il" \| "in" \| "it" \| "jp" \| "kr" \| "ma" \| "nl" \| "np" \| "pk" \| "pl" \| "ps" \| "pt" \| "ru" \| "sa" \| "se" \| "tr" \| "tw" \| "ua" \| "us" \| "vn"	Draw country borders as this country sees them (ISO 3166-1 alpha-2, e.g. `in`, `cn`, `us`, `ma`). Replaces the basemap's country and disputed borders with Natural Earth's borders for that worldview, and uses its country shapes for a highlighted country and for neighbor labels. Regions, cities and everything below country level stay OpenStreetMap. Default: the basemap's borders (OpenStreetMap, on-the-ground control). One of the 31 Natural Earth worldviews; the Locator maps guide explains what changes ("Disputed borders"). example `"in"`
`neighbors`	query	"name" \| "code" \| "flag" \| "flag+code" \| "flag+name"	What to show for each neighboring country: its name, its international vehicle registration code (D, A, SK…), its flag, or a flag with code/name. `false`/`none` turns them off. A literal `+` may arrive as a space; both work. example `"flag+code"`
`neighborfit`	query	"extend" \| "shrink" \| "drop"	When a label does not fit in the visible part of its country: `extend` grows the image on that side (the output becomes larger than width×height; see `X-Image-Width`), `shrink` reduces the label to 70 %, `drop` omits it. example `"extend"`
`neighborwhich`	query	"touching" \| "visible"	`touching` = countries bordering the area; `visible` = every other country in the frame. example `"visible"`
`neighborsize`	query	number	Text size in CSS px; flags are sized to match. example `"12"`
`neighborcolor`	query	string	Text color (default: the theme's muted label color). example `"#666666"`
`neighborupper`	query	string	Uppercase country names. example `"true"`
`lang`	query	string	Label language (ISO 639-1). Default: local names (Deutschland, Polska), as on Wikipedia locator maps. example `"en"`
`font`	query	"noto-sans" \| "noto-serif" \| "noto-sans-mono"	A bundled family, or your own TTF/OTF/WOFF as a `data:` URI or an https URL on an allowed host (`WHEREBOX_FONT_HOSTS`). Missing glyphs fall back to Noto Sans, then Noto Sans Mono. Bundled families only in GET; custom fonts via POST. example `"noto-serif"`
`fontweight`	query	integer	Weight for all labels (100–900; the nearest bundled weight is used). example `"600"`
`title`	query	string	Title text (one line; long titles shrink, then get an ellipsis). example `"Madrid – Seville"`
`titlepos`	query	"top" \| "bottom"	Band above or below the map. example `"bottom"`
`titlealign`	query	"left" \| "center" \| "right"	Text alignment in the band. example `"center"`
`titlesize`	query	number	Text size in CSS px. example `"20"`
`titleweight`	query	integer	Font weight. example `"700"`
`titlecolor`	query	string	Text color (default: the theme label color). example `"#1a1a1a"`
`titlebg`	query	string	Band background (default: white, or near-black on the dark preset). example `"#ffffff"`

Responses

Status	Description
200	The rendered image `image/png` `image/jpeg` `image/webp` `ETag` string `X-Cache` "HIT" \| "MISS" `X-Image-Width` integer: Final pixel width (can exceed w×scale with neighborfit=extend) `X-Image-Height` integer: Final pixel height
304	Not modified
400	RFC 7807 problem details `application/problem+json` Problem
404	RFC 7807 problem details `application/problem+json` Problem
409	RFC 7807 problem details `application/problem+json` Problem
502	RFC 7807 problem details `application/problem+json` Problem
503	RFC 7807 problem details `application/problem+json` Problem

POST `/v1/map`#

Render a map from a JSON MapSpec

Path and header parameters

Name	In	Type	Description
`X-Provider-Key`	header	string	API key for a commercial basemap style
`X-Routing-Key`	header	string	API key for openrouteservice / GraphHopper routing

Query parameters

Name	In	Type	Description
`response`	query	string	"json" returns { url, key, meta } instead of the image

Request body

application/json required as MapSpec

area string or object example "Czechia"

The area to frame and highlight. Ambiguous names return 409 with candidates.

One of:

string length 1 to 200 example "Czechia" A name ("Czechia", "Zlínský kraj"), or an id: iso:CZ, iso:CZ-72, osm:r51684, wikidata:Q213.
object A name lookup narrowed by admin level and/or country, for ambiguous names.
query string required length 1 to 200 example "Nová Ves"
Name or id, as in the string form.
level integer 1 to 11 example 8
Only match areas at this OSM admin level (2 = country; regions and municipalities vary by country).
country string length 2 to 2 example "CZ"
Only match areas inside this ISO 3166-1 alpha-2 country.
object Your own area geometry instead of a lookup.
geojson object required
A GeoJSON Polygon, MultiPolygon, or Feature with one of those geometries.
type "Polygon" | "MultiPolygon" | "Feature" required example "Polygon"
GeoJSON type.
Other keys: any

bounds [number, number, number, number] 4 to 4 items example [12.09,48.55,18.86,51.06]

Explicit frame [west, south, east, north]; overrides automatic framing.

[0] number required -180 to 180

[1] number required -85.06 to 85.06

[2] number required -180 to 180

[3] number required -85.06 to 85.06

routes array of object 0 to 10 items default []

Routes to draw (GET supports one; POST up to 10).

Each item:

geometry object

A line you already have (e.g. from your own routing provider).

type "LineString" | "MultiLineString" | "Feature" required example "LineString"

GeoJSON type.

Other keys: any

polyline string length 0 to 200000 example "_p~iF~ps|U_ulLnnqC_mqNvxq`@"

The line as an encoded polyline (Google algorithm).

polylinePrecision 5 or 6 default 5 example 5

Polyline precision: 5 (Google) or 6 (Valhalla/OSRM).

One of:

from object example {"lat":40.4168,"lon":-3.7038}

Start point when the server should compute the line.

One of:

object Coordinates.
lat number required -90 to 90 example 40.4168
Latitude (WGS84).
lon number required -180 to 180 example -3.7038
Longitude (WGS84).
object A place name to look up.
place string required length 1 to 200 example "Sevilla"
Place name to look up (imported OSM places first, then the server's geocoder if configured); its name becomes the default label.

to object example {"lat":40.4168,"lon":-3.7038}

Finish point when the server should compute the line.

One of:

object Coordinates.
lat number required -90 to 90 example 40.4168
Latitude (WGS84).
lon number required -180 to 180 example -3.7038
Longitude (WGS84).
object A place name to look up.
place string required length 1 to 200 example "Sevilla"
Place name to look up (imported OSM places first, then the server's geocoder if configured); its name becomes the default label.

via array of object 0 to 20 items default []

Points the route must pass through, in order.

Each item:

One of:

object Coordinates.
lat number required -90 to 90 example 40.4168
Latitude (WGS84).
lon number required -180 to 180 example -3.7038
Longitude (WGS84).
object A place name to look up.
place string required length 1 to 200 example "Sevilla"
Place name to look up (imported OSM places first, then the server's geocoder if configured); its name becomes the default label.

profile "car" | "bike" | "foot" | "straight" | "geodesic" default "geodesic" example "geodesic"

How endpoints are connected: routed by car/bike/foot (needs a routing engine on the server or your X-Routing-Key), or locally as straight segments or geodesic great-circle arcs. The default geodesic always works (no routing engine, key or plan feature needed) and is the true shortest path, so it suits flights and locator maps; ask for car/bike/foot explicitly for roads.

provider "valhalla" | "openrouteservice" | "graphhopper" example "valhalla"

Routing provider (default: the server's). openrouteservice and GraphHopper need a key (server-side or X-Routing-Key).

color string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ default "#d01c1c" example "#d01c1c"

Color of the route line.

width number 0.5 to 20 default 3 example 3

Line width in px.

casingColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ default "#ffffff" example "#ffffff"

Outline drawn under the line so it reads on busy basemaps.

casingWidth number 0 to 10 default 1.5 example 1.5

Outline width on each side in px; 0 = none.

dash array of number 0 to 8 items example [2,1.5]

Dash pattern in line widths, e.g. [2, 1.5].

opacity number 0 to 1 default 1 example 1

Line opacity.

start object default {}

Marker and label for one end of the route.

label string length 0 to 160 example "Madrid"

Label at this end (default: the place name, if the end was given as a place).

Where the label goes relative to the marker. auto picks the first free spot and falls back to a leader line.

labelSize number 6 to 48 default 16 example 16

Label text size in CSS px.

labelWeight integer 100 to 900 example 700

Font weight for this label (overrides font.weight).

labelColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#1a1a1a"

Label color (default: the basemap theme's label color).

marker object

Marker style; every field is optional and falls back to the role default.

Marker preset. Defaults depend on the role: plain point → pin, route start → ring, route finish → flag.

color string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#e02020"

Marker fill color.

size number 4 to 64 example 20

Marker height in CSS pixels (multiplied by scale). Default depends on the shape.

strokeColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#ffffff"

Outline color (default white where the shape has an outline).

strokeWidth number 0 to 8 example 1.5

Outline width in px; 0 = none. dot and pin have a thin default outline.

icon string length 0 to 200000 example "data:image/svg+xml;base64,PHN2Zy8+"

Custom icon instead of the shape: an SVG/PNG data: URI, or an https URL on a host the server allows (WHEREBOX_ICON_HOSTS). SVGs with external references or scripts are rejected.

anchor "center" | "bottom" example "bottom"

Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons).

show boolean default true example true

false hides the marker and label for this end.

finish object default {}

Marker and label for one end of the route.

label string length 0 to 160 example "Madrid"

Label at this end (default: the place name, if the end was given as a place).

Where the label goes relative to the marker. auto picks the first free spot and falls back to a leader line.

labelSize number 6 to 48 default 16 example 16

Label text size in CSS px.

labelWeight integer 100 to 900 example 700

Font weight for this label (overrides font.weight).

labelColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#1a1a1a"

Label color (default: the basemap theme's label color).

marker object

Marker style; every field is optional and falls back to the role default.

Marker preset. Defaults depend on the role: plain point → pin, route start → ring, route finish → flag.

color string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#e02020"

Marker fill color.

size number 4 to 64 example 20

Marker height in CSS pixels (multiplied by scale). Default depends on the shape.

strokeColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#ffffff"

Outline color (default white where the shape has an outline).

strokeWidth number 0 to 8 example 1.5

Outline width in px; 0 = none. dot and pin have a thin default outline.

icon string length 0 to 200000 example "data:image/svg+xml;base64,PHN2Zy8+"

Custom icon instead of the shape: an SVG/PNG data: URI, or an https URL on a host the server allows (WHEREBOX_ICON_HOSTS). SVGs with external references or scripts are rejected.

anchor "center" | "bottom" example "bottom"

Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons).

show boolean default true example true

false hides the marker and label for this end.

shapes array of object 0 to 50 items default []

Extra lines and polygons (POST only).

Each item:

geojson object required

Any GeoJSON geometry, Feature or FeatureCollection.

type string required example "LineString"

GeoJSON type (LineString, Polygon, Feature, FeatureCollection, …).

Other keys: any

color string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ default "#555555" example "#555555"

Line color of the shape.

width number 0 to 20 default 2 example 2

Line width in px; 0 = no line.

dash array of number 0 to 8 items example [3,2]

Dash pattern in line widths.

opacity number 0 to 1 default 1 example 1

Line opacity.

fill string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#ffcc00"

Fill color for polygons (no fill if unset).

fillOpacity number 0 to 1 default 0.25 example 0.25

Fill opacity for polygons.

font object default {}

Font for everything we draw (labels, title); the basemap keeps its own fonts.

family "noto-sans" | "noto-serif" | "noto-sans-mono" or string default "noto-sans" example "noto-serif"

A bundled family, or your own TTF/OTF/WOFF as a data: URI or an https URL on an allowed host (WHEREBOX_FONT_HOSTS). Missing glyphs fall back to Noto Sans, then Noto Sans Mono.

One of:

"noto-sans" | "noto-serif" | "noto-sans-mono" example "noto-sans" Bundled font family.
string length 0 to 2000000

weight integer 100 to 900 default 400 example 600

Weight for all labels (100–900; the nearest bundled weight is used).

title object

A title band, drawn inside the requested width×height (the map gets the rest).

text string required length 1 to 200 example "Madrid – Seville"

Title text (one line; long titles shrink, then get an ellipsis).

position "top" | "bottom" default "top" example "top"

Band above or below the map.

align "left" | "center" | "right" default "left" example "left"

Text alignment in the band.

size number 8 to 64 default 18 example 18

Text size in CSS px.

weight integer 100 to 900 default 600 example 600

Font weight.

color string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#1a1a1a"

Text color (default: the theme label color).

background string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#ffffff"

Band background (default: white, or near-black on the dark preset).

dividerColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#cfcfcf"

Line between the band and the map.

dividerWidth number 0 to 6 default 1 example 1

Divider width in px; 0 = none.

padding number 0 to 40 default 10 example 10

Space around the text in px.

pois array of object 0 to 50 items default []

Points with markers and labels (up to 50).

Each item:

lat number -90 to 90 example 49.13

Latitude (WGS84). Any coordinate works; no lookup is done.

lon number -180 to 180 example 17.33

Longitude (WGS84).

place string length 1 to 200 example "Chřiby"

A place name to look up instead of coordinates (cities, peaks, mountain ranges…). Looked up in the imported OSM places first, then in the server's geocoder if one is configured. The label defaults to the place name.

label string length 0 to 160 example "Crash Site\n(near Urda)"

Label text. A newline (\n in GET) starts a new line.

Where the label goes relative to the marker. auto picks the first free spot and falls back to a leader line.

labelSize number 6 to 48 default 16 example 16

Label text size in CSS px.

labelWeight integer 100 to 900 example 700

Font weight for this label (overrides font.weight).

labelColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#1a1a1a"

Label color (default: the basemap theme's label color).

marker object

Marker style; every field is optional and falls back to the role default.

Marker preset. Defaults depend on the role: plain point → pin, route start → ring, route finish → flag.

color string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#e02020"

Marker fill color.

size number 4 to 64 example 20

Marker height in CSS pixels (multiplied by scale). Default depends on the shape.

strokeColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#ffffff"

Outline color (default white where the shape has an outline).

strokeWidth number 0 to 8 example 1.5

Outline width in px; 0 = none. dot and pin have a thin default outline.

icon string length 0 to 200000 example "data:image/svg+xml;base64,PHN2Zy8+"

Custom icon instead of the shape: an SVG/PNG data: URI, or an https URL on a host the server allows (WHEREBOX_ICON_HOSTS). SVGs with external references or scripts are rejected.

anchor "center" | "bottom" example "bottom"

Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons).

leader boolean default true example true

When no free spot is next to the marker, place the label further out with a thin leader line.

width integer 64 to 2048 default 600 example 468

Image width in CSS px (the output is width × scale pixels).

height integer 64 to 2048 default 400 example 280

Image height in CSS px, including the title band if any.

scale integer 1 to 3 default 1 example 2

Pixel ratio for high-DPI output (2 = retina).

format "png" | "jpeg" | "webp" default "png" example "png"

Image format (GET can also use the path extension: /v1/map.png, .jpg, .webp).

quality integer 1 to 100 default 90 example 90

JPEG/WebP quality.

padding number 0 to 0.45 default 0.04 example 0.04

Space around the framed content as a fraction of the image size.

projection "mercator" | "globe" | "auto" default "mercator" example "globe"

Map projection. mercator is the usual flat web map. globe draws an orthographic globe, which keeps continent-spanning routes and high latitudes true to shape; the content must fit on one hemisphere (within 85° of the view center), and neighbor labels are not available. auto picks the globe when the content spans more than 50° or Mercator would stretch it more than 2.5× between its lowest and highest latitude, else Mercator.

globe object default {}

Globe options (with projection globe, or auto when it picks the globe).

view "full" | "fit" default "full" example "full"

How much of the globe to show. full (default): the whole globe, centered on your content, with space around it; recognizable at a glance as a globe. fit: zoomed in until the content fills the image; a larger scale with more detail along the route, but only part of the globe is visible.

basemap object default {}

The map underneath: a built-in preset or your own style.

preset "locator-relief" | "light" | "dark" default "locator-relief" example "locator-relief"

Built-in basemap: shaded relief (Wikipedia locator style), light, or dark. No key needed.

styleUrl string (uri) example "https://api.maptiler.com/maps/streets-v2/style.json?key={key}"

Any MapLibre style.json URL; overrides preset. {key} in the URL is replaced with providerKey.

providerKey string length 0 to 200 example "your-provider-key"

Key for a commercial style (prefer the X-Provider-Key header so it stays out of URLs).

highlight object default {}

How the area stands out. Unset fields use the basemap preset's defaults (see the presets reference).

fade number 0 to 1 example 0.45

How much the surroundings are washed out: 0 = not at all, 1 = fully covered.

fadeColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#ffffff"

Color the surroundings fade towards.

outlineColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#555555"

Area outline color.

outlineWidth number 0 to 10 example 1.1

Area outline width in px; 0 = none.

tint string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#d03030"

Optional color tint drawn over the area.

tintOpacity number 0 to 1 example 0.15

Opacity of tint.

subdivisions boolean or "auto" or integer example "auto"

Inner admin borders: auto draws the next level that splits the area, a number forces that admin level, false hides them.

One of:

boolean
"auto"
integer 3 to 11

subdivisionColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#8a8a8a"

Color of the inner admin borders.

subdivisionWidth number 0 to 6 example 0.6

Width of the inner admin borders in px.

desaturate number 0 to 1 example 0.8

Outside the area: 0 = full color, 1 = grayscale (applied on top of fade).

blur number 0 to 20 example 1.5

Outside the area: blur radius in CSS px; 0 = sharp.

subArea string or object example "Zlínský kraj"

A second, smaller area highlighted inside the framed one (e.g. a region within its country).

One of:

string length 1 to 200 example "Czechia" A name ("Czechia", "Zlínský kraj"), or an id: iso:CZ, iso:CZ-72, osm:r51684, wikidata:Q213.
object A name lookup narrowed by admin level and/or country, for ambiguous names.
query string required length 1 to 200 example "Nová Ves"
Name or id, as in the string form.
level integer 1 to 11 example 8
Only match areas at this OSM admin level (2 = country; regions and municipalities vary by country).
country string length 2 to 2 example "CZ"
Only match areas inside this ISO 3166-1 alpha-2 country.
object Your own area geometry instead of a lookup.
geojson object required
A GeoJSON Polygon, MultiPolygon, or Feature with one of those geometries.
type "Polygon" | "MultiPolygon" | "Feature" required example "Polygon"
GeoJSON type.
Other keys: any

subAreaColor string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#d03030"

Fill and outline color of subArea.

subAreaOpacity number 0 to 1 example 0.35

Fill opacity of subArea.

subAreaOutlineWidth number 0 to 10 example 1.2

Outline width of subArea in px; 0 = none.

attribution "bottom-right" | "bottom-left" | "top-right" | "top-left" default "bottom-right" example "bottom-right"

Corner for the data attribution (always drawn; required by the data licenses).

neighbors object

Label the countries around the area (needs an area).

show "name" | "code" | "flag" | "flag+code" | "flag+name" default "name" example "flag+code"

What to show for each neighboring country: its name, its international vehicle registration code (D, A, SK…), its flag, or a flag with code/name.

which "touching" | "visible" default "touching" example "touching"

touching = countries bordering the area; visible = every other country in the frame.

fit "extend" | "shrink" | "drop" default "extend" example "extend"

When a label does not fit in the visible part of its country: extend grows the image on that side (the output becomes larger than width×height; see X-Image-Width), shrink reduces the label to 70 %, drop omits it.

size number 6 to 32 default 12 example 12

Text size in CSS px; flags are sized to match.

color string pattern ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$ example "#666666"

Text color (default: the theme's muted label color).

uppercase boolean default false example true

Uppercase country names.

max integer 1 to 30 default 12 example 12

At most this many countries are labeled (largest visible first).

worldview "ar" | "bd" | "br" | "cn" | "de" | "eg" | "es" | "fr" | "gb" | "gr" | "id" | "il" | "in" | "it" | "jp" | "kr" | "ma" | "nl" | "np" | "pk" | "pl" | "ps" | "pt" | "ru" | "sa" | "se" | "tr" | "tw" | "ua" | "us" | "vn" example "in"

Draw country borders as this country sees them (ISO 3166-1 alpha-2, e.g. in, cn, us, ma). Replaces the basemap's country and disputed borders with Natural Earth's borders for that worldview, and uses its country shapes for a highlighted country and for neighbor labels. Regions, cities and everything below country level stay OpenStreetMap. Default: the basemap's borders (OpenStreetMap, on-the-ground control).

lang string pattern ^[a-z]{2,3}$ example "en"

Label language (ISO 639-1). Default: local names (Deutschland, Polska), as on Wikipedia locator maps.

Responses

Status	Description
200	The rendered image `image/png` `image/jpeg` `image/webp` `application/json` `ETag` string `X-Cache` "HIT" \| "MISS" `X-Image-Width` integer: Final pixel width (can exceed w×scale with neighborfit=extend) `X-Image-Height` integer: Final pixel height
400	RFC 7807 problem details `application/problem+json` Problem
404	RFC 7807 problem details `application/problem+json` Problem
409	RFC 7807 problem details `application/problem+json` Problem
502	RFC 7807 problem details `application/problem+json` Problem
503	RFC 7807 problem details `application/problem+json` Problem

GET `/v1/map.{ext}`#

Render a map; the extension picks the format

Path and header parameters

Name	In	Type	Description
`ext`	path	"png" \| "jpg" \| "webp"	required
`X-Provider-Key`	header	string	API key for a commercial basemap style

Query parameters

Same 65 query parameters as GET /v1/map.

Responses

Status	Description
200	The rendered image `image/png` `image/jpeg` `image/webp` `ETag` string `X-Cache` "HIT" \| "MISS" `X-Image-Width` integer: Final pixel width (can exceed w×scale with neighborfit=extend) `X-Image-Height` integer: Final pixel height
400	RFC 7807 problem details `application/problem+json` Problem
404	RFC 7807 problem details `application/problem+json` Problem
409	RFC 7807 problem details `application/problem+json` Problem
502	RFC 7807 problem details `application/problem+json` Problem
503	RFC 7807 problem details `application/problem+json` Problem

GET `/v1/images/{key}`#

Fetch a cached image by content hash

Path and header parameters

Name	In	Type	Description
`key`	path	string	required

Responses

Status	Description
200	The rendered image `image/png` `image/jpeg` `image/webp` `ETag` string `X-Cache` "HIT" \| "MISS" `X-Image-Width` integer: Final pixel width (can exceed w×scale with neighborfit=extend) `X-Image-Height` integer: Final pixel height
404	RFC 7807 problem details `application/problem+json` Problem

GET `/v1/areas/search`#

Search areas by name (with hierarchy context for disambiguation)

Query parameters

Name	In	Type	Description
`q`	query	string	Search text required
`limit`	query	integer	1–50

Responses

Status	Description
200	Matching areas

GET `/v1/areas/{id}`#

Get one area

Path and header parameters

Name	In	Type	Description
`id`	path	string	required example `"r51684"`

Responses

Status	Description
200	Area
404	RFC 7807 problem details `application/problem+json` Problem

GET `/v1/places/search`#

Search named places (cities, peaks, mountain ranges…)

Query parameters

Same 2 query parameters as GET /v1/areas/search.

Responses

Status	Description
200	Matching places

Problem details#

RFC 7807 problem details. type identifies the error (see the error reference).

type string

Error code URI, one of the problem types below.

title string

Fixed summary for the error type.

status integer

detail string

What happened in this request.

issues array of any

[{path, message}] — one entry per problem.

candidates array of any

Matching areas with ref (pass it as area, e.g. osm:r439539), adminLevel and context (e.g. "Česko › Liberecký kraj").

suggestions array of any

Close matches, when there are any.

requestId string

Id of the request (same as the X-Request-Id header). Quote it when reporting a problem.

Problem types

Each type links to its entry in the error reference.

Wherebox API v0.2.0

GET /v1/map#

Path and header parameters

Query parameters

Responses

POST /v1/map#

Path and header parameters

Query parameters

Request body

Responses

GET /v1/map.{ext}#

Path and header parameters

Query parameters

Responses

GET /v1/images/{key}#

Path and header parameters

Responses

GET /v1/areas/search#

Query parameters

Responses

GET /v1/areas/{id}#

Path and header parameters

Responses

GET /v1/places/search#

Query parameters

Responses

Problem details#

Problem types

GET `/v1/map`#

POST `/v1/map`#

GET `/v1/map.{ext}`#

GET `/v1/images/{key}`#

GET `/v1/areas/search`#

GET `/v1/areas/{id}`#

GET `/v1/places/search`#