Wherebox

Generated from code

On this page

Query parameters

Parameters for GET /v1/map and GET /v1/map.{ext}. The same options exist in the JSON body of POST /v1/map (see Request body).

Area and framing#

What the map is about and how it is framed. All of these are optional, but a map needs an area, bounds, a route or at least one point.

Parameter Value Default Description Example
area string | object — 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. area=Czechia
level integer, 1–11 — 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}). level=8
country string — Only match areas inside this ISO 3166-1 alpha-2 country. Narrows a name lookup. country=CZ
bounds string — Explicit frame [west, south, east, north]; overrides automatic framing. west,south,east,north. bounds=12.09,48.55,18.86,51.06
padding number, 0–0.45 0.04 Space around the framed content as a fraction of the image size. padding=0.04
projection mercator | globe | auto mercator 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. projection=globe
globeview full | fit 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. full (default) or fit. globeview=fit

Points#

Labeled markers. Repeat poi for each point; options go after the location, separated by |.

Parameter Value Default Description Example
poi string (repeatable) — 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. poi=49.13,17.33|label:Chřiby|marker:triangle

Route#

One route per GET request (use POST for several). Give from and to, or a polyline.

Parameter Value Default Description Example
from string — Start point when the server should compute the line. lat,lon or place:Name. A route needs from+to or polyline. from=40.4168,-3.7038
to string — Finish point when the server should compute the line. to=place:Sevilla
via string (repeatable) — Points the route must pass through, in order. via=38.98,-3.93
profile car | bike | foot | straight | geodesic 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. profile=straight
polyline string — The line as an encoded polyline (Google algorithm). URL-encode it (polylines can contain |, ? and \). polyline=_p~iF~ps|U_ulLnnqC_mqNvxq`@
polylineprecision 5 | 6 5 Polyline precision: 5 (Google) or 6 (Valhalla/OSRM). polylineprecision=6
routeprovider valhalla | openrouteservice | graphhopper — Routing provider (default: the server's). openrouteservice and GraphHopper need a key (server-side or X-Routing-Key). routeprovider=valhalla
routecolor string #d01c1c Color of the route line. routecolor=#d01c1c
routewidth number, 0.5–20 3 Line width in px. routewidth=3
routecasing string #ffffff Outline drawn under the line so it reads on busy basemaps. routecasing=#ffffff
routedash string — Dash pattern in line widths, e.g. [2, 1.5]. Comma-separated. routedash=2,1.5
routeopacity number, 0–1 1 Line opacity. routeopacity=0.9
fromlabel string — Label at this end (default: the place name, if the end was given as a place). fromlabel=Madrid
tolabel string — Label at this end (default: the place name, if the end was given as a place). tolabel=Sevilla
frommarker 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. frommarker=dot
tomarker 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. tomarker=pin
showfrom boolean true false hides the marker and label for this end. showfrom=false
showto boolean true false hides the marker and label for this end. showto=false

Image#

Size, format and attribution of the output image.

Parameter Value Default Description Example
w
alias width		 integer, 64–2048 600 Image width in CSS px (the output is width × scale pixels). w=468
h
alias height		 integer, 64–2048 400 Image height in CSS px, including the title band if any. h=280
scale integer, 1–3 1 Pixel ratio for high-DPI output (2 = retina). scale=2
format png | jpeg | webp png Image format (GET can also use the path extension: /v1/map.png, .jpg, .webp). Or use the path extension: /v1/map.webp. format=webp
quality integer, 1–100 90 JPEG/WebP quality. quality=85
attribution bottom-right | bottom-left | top-right | top-left bottom-right Corner for the data attribution (always drawn; required by the data licenses). attribution=bottom-left

Basemap#

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

Parameter Value Default Description Example
preset locator-relief | light | dark locator-relief Built-in basemap: shaded relief (Wikipedia locator style), light, or dark. No key needed. preset=dark
style string — Any MapLibre style.json URL; overrides preset. {key} in the URL is replaced with providerKey. URL-encode it. style=https://api.maptiler.com/maps/streets-v2/style.json?key={key}
key 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. key=your-provider-key

Highlight#

How the area stands out. Unset values use the defaults of the chosen basemap preset.

Parameter Value Default Description Example
fade number, 0–1 0.45 (varies by preset) How much the surroundings are washed out: 0 = not at all, 1 = fully covered. fade=0.6
fadecolor string #ffffff (varies by preset) Color the surroundings fade towards. URL-encode # as %23. fadecolor=#ffffff
outline string #555555 (varies by preset) Area outline color. outline=#555555
outlinewidth number, 0–10 1.1 (varies by preset) Area outline width in px; 0 = none. outlinewidth=2
tint string — Optional color tint drawn over the area. tint=#d03030
tintopacity number, 0–1 0.15 (varies by preset) Opacity of tint. tintopacity=0.12
subdivisions boolean | string | integer, auto, 3–11 auto (varies by preset) 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. subdivisions=auto
desaturate number, 0–1 0 (varies by preset) Outside the area: 0 = full color, 1 = grayscale (applied on top of fade). desaturate=0.8
blur number, 0–20 0 (varies by preset) Outside the area: blur radius in CSS px; 0 = sharp. blur=1.5
subarea string | object — A second, smaller area highlighted inside the framed one (e.g. a region within its country). subarea=Zlínský kraj
subareacolor string #d03030 (varies by preset) Fill and outline color of subArea. subareacolor=#c0392b
subareaopacity number, 0–1 0.35 (varies by preset) Fill opacity of subArea. subareaopacity=0.35
subareaoutlinewidth number, 0–10 1.2 (varies by preset) Outline width of subArea in px; 0 = none. subareaoutlinewidth=1.2
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 — 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"). worldview=in

Neighboring countries#

Labels for the countries around the area. Requires neighbors; the other options refine it.

Parameter Value Default Description Example
neighbors name | code | flag | flag+code | flag+name 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. neighbors=flag+code
neighborfit extend | shrink | drop 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. neighborfit=extend
neighborwhich touching | visible touching touching = countries bordering the area; visible = every other country in the frame. neighborwhich=visible
neighborsize number, 6–32 12 Text size in CSS px; flags are sized to match. neighborsize=12
neighborcolor string — Text color (default: the theme's muted label color). neighborcolor=#666666
neighborupper boolean false Uppercase country names. neighborupper=true

Labels and typography#

Language and font of everything drawn on top of the basemap.

Parameter Value Default Description Example
lang string — Label language (ISO 639-1). Default: local names (Deutschland, Polska), as on Wikipedia locator maps. lang=en
font noto-sans | noto-serif | noto-sans-mono noto-sans 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. font=noto-serif
fontweight integer, 100–900 400 Weight for all labels (100–900; the nearest bundled weight is used). fontweight=600

Title band#

An optional title band inside the requested width and height. Requires title; the other options refine it.

Parameter Value Default Description Example
title string — Title text (one line; long titles shrink, then get an ellipsis). title=Madrid – Seville
titlepos top | bottom top Band above or below the map. titlepos=bottom
titlealign left | center | right left Text alignment in the band. titlealign=center
titlesize number, 8–64 18 Text size in CSS px. titlesize=20
titleweight integer, 100–900 600 Font weight. titleweight=700
titlecolor string — Text color (default: the theme label color). titlecolor=#1a1a1a
titlebg string — Band background (default: white, or near-black on the dark preset). titlebg=#ffffff

POI options (inside poi=)#

A poi value is a location followed by |key:value options: lat,lon|label:Chřiby|marker:triangle. The location is lat,lon or place:Name.

Option Value Default Description Example
label string — Label text. A newline (\n in GET) starts a new line. \n (backslash-n) starts a new line. | cannot appear in a label in GET; use POST. label:Chřiby
pos auto | right | left | top | bottom | top-right | top-left | bottom-right | bottom-left auto Where the label goes relative to the marker. auto picks the first free spot and falls back to a leader line. pos:bottom
labelsize number, 6–48 16 Label text size in CSS px. labelsize:16
weight integer, 100–900 — Font weight for this label (overrides font.weight). weight:700
labelcolor string — Label color (default: the basemap theme's label color). labelcolor:#1a1a1a
leader boolean true When no free spot is next to the marker, place the label further out with a thin leader line. leader:false
marker 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. marker:triangle
color string — Marker fill color. color:#e02020
size number, 4–64 — Marker height in CSS pixels (multiplied by scale). Default depends on the shape. size:14
stroke string — Outline color (default white where the shape has an outline). stroke:#ffffff
strokewidth number, 0–8 — Outline width in px; 0 = none. dot and pin have a thin default outline. strokewidth:1.5
icon string — 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. URL-encode the value (base64 contains +, / and =). icon:data:image/svg+xml;base64,PHN2Zy8+
anchor center | bottom — Which point of a custom icon sits on the location: its center, or its bottom edge (pin-shaped icons). anchor:bottom

POST-only#

These MapSpec fields cannot be set from a query string; send them in the JSON body of POST /v1/map.

  • shapes
  • routes.1+
  • font.family (custom fonts)
  • area (GeoJSON)
  • pois.*.marker.icon (long data URIs work but POST is recommended)

Unknown parameters and cache busters#

An unknown parameter is rejected with 400 (invalid-spec) and, when one is close, a "did you mean" hint. Parameters starting with _ (for example _v=3) are ignored by the parser, so they can be used to bust caches.