Wherebox
On this page

Locator maps

A locator map frames an area, highlights it, and fades what is around it. Everything here is about area and how it is highlighted.

Naming an area#

area takes a name or an id. Names are convenient; ids never change meaning.

Form Example
Name Czechia, Zlínský kraj
ISO 3166 code iso:CZ, iso:CZ-72
OpenStreetMap relation osm:r51684
Wikidata wikidata:Q213
GET/v1/map.png
GET /v1/map.png?area=Zlínský+kraj&w=400&h=300
Try it (opens the API in a new tab)
Zlín Region
GET/v1/map.png
GET /v1/map.png?area=iso:CZ-72&w=400&h=300
Try it (opens the API in a new tab)
Map rendered by the area-by-id example

An id returns the same area as its name, but it cannot become ambiguous when the database gains a same-named place. Use ids in anything you store. Look ids up with GET /v1/areas/search?q=…, which also returns each match's parent hierarchy.

Ambiguous names#

Many names exist more than once ("Nová Ves" is the name of dozens of villages). The API refuses to guess:

GET/v1/map.png
GET /v1/map.png?area=Nová+Ves&w=400&h=300
Try it (opens the API in a new tab)

This returns 409 with a candidates array. Each candidate has an id, an adminLevel and a context showing where it is, for example Česko › Kraj Vysočina › okres Žďár nad Sázavou › …. The ambiguous error reference lists the fields. You have two ways out.

Pick a candidate by id. Take its id from the response and use it as the area:

GET/v1/map.png
GET /v1/map.png?area=osm:r442590&w=360&h=260
Try it (opens the API in a new tab)
Nová Ves in the Vysočina region, picked by id

Narrow the lookup. level restricts the match to one administrative level, country to one ISO country code. They only make sense together with a name area (level, country). If the narrowed lookup is still ambiguous you get another 409, so check the candidates rather than adding filters blindly.

GET/v1/map.png
GET /v1/map.png?area=Zlín&level=8&country=CZ&w=360&h=260
Try it (opens the API in a new tab)
Map rendered by the narrowed-lookup example

In a POST body the same thing is an object instead of a string:

POST/v1/map
{
  "area": { "query": "Zlín", "level": 8, "country": "CZ" },
  "width": 360,
  "height": 260
}
Map rendered by the narrowed-lookup-post example

Admin levels differ per country. In Czechia 2 is the country, 4 the regions (kraje), 5 the districts (okresy) and 8 the municipalities.

Highlighting#

The highlight is made of a fade of the surroundings, an outline, an optional tint, and inner borders. Defaults depend on the basemap, so a plain request already looks right; override only what you want to change.

GET/v1/map.png
GET /v1/map.png?area=Czechia&w=468&h=280&fade=0.7&fadecolor=%23dedede&outline=%23333333&outlinewidth=2
Try it (opens the API in a new tab)
Stronger fade with a darker outline
GET/v1/map.png
GET /v1/map.png?area=iso:CZ-10&w=420&h=300&tint=%23d03030&tintopacity=0.12&outline=%23a01010&outlinewidth=2
Try it (opens the API in a new tab)
Prague with a red tint

Parameters: fade, fadecolor, outline, outlinewidth, tint, tintopacity. Colors are hex; write # as %23 in a URL.

Subdivisions#

Inner borders show how the area splits. By default (auto) the next administrative level that splits the area is drawn. Force a level with a number, or turn them off.

GET/v1/map.png
GET /v1/map.png?area=Czechia&w=468&h=280&subdivisions=5
Try it (opens the API in a new tab)
Czechia split into districts
GET/v1/map.png
GET /v1/map.png?area=Czechia&w=468&h=280&subdivisions=false
Try it (opens the API in a new tab)
Map rendered by the subdivisions-off example

See subdivisions.

Highlighting a sub-area#

subarea highlights a second, smaller area inside the framed one, the classic "this region within its country":

GET/v1/map.png
GET /v1/map.png?area=Czechia&subarea=Zlínský+kraj&subareacolor=%23c0392b&w=468&h=280
Try it (opens the API in a new tab)
Zlín Region highlighted within Czechia

It accepts the same names and ids as area. Color, opacity and outline are subareacolor, subareaopacity and subareaoutlinewidth.

Desaturate and blur the outside#

To push the surroundings back further than a fade can, drain their color and soften them. This runs only outside the area; labels and markers stay sharp.

GET/v1/map.png
GET /v1/map.png?area=Czechia&w=468&h=280&desaturate=0.8&blur=1.5&fade=0.2
Try it (opens the API in a new tab)
Muted, softened surroundings

See desaturate and blur.

Your own area#

Send a GeoJSON Polygon, MultiPolygon or Feature instead of a name. This is POST only. Turn subdivisions off, since a custom shape has no administrative children:

POST/v1/map
{
  "area": {
    "geojson": {
      "type": "Polygon",
      "coordinates": [[[16.5, 49.1], [16.8, 49.1], [16.8, 49.3], [16.5, 49.3], [16.5, 49.1]]]
    }
  },
  "highlight": { "subdivisions": false },
  "width": 360,
  "height": 260
}
A custom rectangle around Brno

Presets#

A preset is a complete basemap and a matching set of highlight and text defaults. locator-relief is the default (shaded relief, like Wikipedia locator maps); light and dark are flat.

GET/v1/map.png
GET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&w=468&h=280&preset=dark
Try it (opens the API in a new tab)
The dark preset
GET/v1/map.png
GET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&w=468&h=280&preset=light
Try it (opens the API in a new tab)
Map rendered by the preset-light example

Because defaults follow the preset, switching preset also re-themes the fade, outline, labels and start/finish markers. What each preset sets is in the presets reference; the parameter is preset.

To use your own style, pass a MapLibre style.json URL as style together with your provider key. Prefer the X-Provider-Key request header over the key parameter so the key stays out of URLs and logs. In JSON this is basemap.styleUrl, with {key} in the URL replaced by the key.

Disputed borders#

By default the basemap draws borders as OpenStreetMap records them, which follows control on the ground. Set worldview to draw country borders as a particular country sees them. For example, in draws Kashmir the way India does, and cn the way China does:

GET/v1/map.png
GET /v1/map.png?bounds=70,30,82,38&w=420&h=320&worldview=in
Try it (opens the API in a new tab)
Kashmir as India sees it
GET/v1/map.png
GET /v1/map.png?bounds=70,30,82,38&w=420&h=320&worldview=cn
Try it (opens the API in a new tab)
Kashmir as China sees it

With a worldview, three things follow that country's view:

  • Country borders. The basemap's country, disputed and claimed lines are replaced. International borders are solid. Disputed borders, claim lines and lines of control are dashed. Lines the view does not recognize are not drawn (with cn, there is no border between Kosovo and Serbia).
  • A highlighted country. It takes the view's shape where that view draws it differently, such as India with all of Kashmir under in. Countries that every view draws the same keep their OpenStreetMap shape.
  • Neighbor labels. They come from the view's country list, so Taiwan has no label under cn.

Regions, cities and everything below country level stay OpenStreetMap, whatever the worldview.

The worldview data is Natural Earth's point-of-view editions (31 countries, public domain), and the attribution adds "Borders: Natural Earth". Natural Earth is drawn at 1:10 million scale. That suits country and regional maps; on a map of a few kilometres a border can sit slightly off the basemap's roads and coastline. The accepted codes are listed under worldview. A self-hosted server serves only the worldviews it imported (NE_WORLDVIEWS; see the configuration reference). Any other code returns 400 bad-request.