# 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` |

```http
GET /v1/map.png?area=Zlínský+kraj&w=400&h=300
```

![Zlín Region](/docs/images/examples/zlin-region.png)

```http
GET /v1/map.png?area=iso:CZ-72&w=400&h=300
```

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:

```http
GET /v1/map.png?area=Nová+Ves&w=400&h=300
```

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](/docs/errors.md#ambiguous) 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:

```http
GET /v1/map.png?area=osm:r442590&w=360&h=260
```

![Nová Ves in the Vysočina region, picked by id](/docs/images/examples/nova-ves-by-id.png)

**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`](/docs/reference/parameters.md#param-level), [`country`](/docs/reference/parameters.md#param-country)). If the narrowed lookup is still ambiguous you get another 409, so check the candidates rather than adding filters blindly.

```http
GET /v1/map.png?area=Zlín&level=8&country=CZ&w=360&h=260
```

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

```json
{
  "area": { "query": "Zlín", "level": 8, "country": "CZ" },
  "width": 360,
  "height": 260
}
```

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.

```http
GET /v1/map.png?area=Czechia&w=468&h=280&fade=0.7&fadecolor=%23dedede&outline=%23333333&outlinewidth=2
```

![Stronger fade with a darker outline](/docs/images/examples/highlight-fade.png)

```http
GET /v1/map.png?area=iso:CZ-10&w=420&h=300&tint=%23d03030&tintopacity=0.12&outline=%23a01010&outlinewidth=2
```

![Prague with a red tint](/docs/images/examples/highlight-tint.png)

Parameters: [`fade`](/docs/reference/parameters.md#param-fade), [`fadecolor`](/docs/reference/parameters.md#param-fadecolor), [`outline`](/docs/reference/parameters.md#param-outline), [`outlinewidth`](/docs/reference/parameters.md#param-outlinewidth), [`tint`](/docs/reference/parameters.md#param-tint), [`tintopacity`](/docs/reference/parameters.md#param-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.

```http
GET /v1/map.png?area=Czechia&w=468&h=280&subdivisions=5
```

![Czechia split into districts](/docs/images/examples/subdivisions-districts.png)

```http
GET /v1/map.png?area=Czechia&w=468&h=280&subdivisions=false
```

See [`subdivisions`](/docs/reference/parameters.md#param-subdivisions).

## Highlighting a sub-area

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

```http
GET /v1/map.png?area=Czechia&subarea=Zlínský+kraj&subareacolor=%23c0392b&w=468&h=280
```

![Zlín Region highlighted within Czechia](/docs/images/examples/sub-area.png)

It accepts the same names and ids as `area`. Color, opacity and outline are [`subareacolor`](/docs/reference/parameters.md#param-subareacolor), [`subareaopacity`](/docs/reference/parameters.md#param-subareaopacity) and [`subareaoutlinewidth`](/docs/reference/parameters.md#param-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.

```http
GET /v1/map.png?area=Czechia&w=468&h=280&desaturate=0.8&blur=1.5&fade=0.2
```

![Muted, softened surroundings](/docs/images/examples/desaturate-blur.png)

See [`desaturate`](/docs/reference/parameters.md#param-desaturate) and [`blur`](/docs/reference/parameters.md#param-blur).

## Outline only, or your own background

To keep the map at full strength and mark the area with its outline alone, turn the fade off:

```http
GET /v1/map.png?area=Czechia&w=468&h=280&fade=0
```

![Czechia outlined on an unfaded map](/docs/images/examples/fade-off.png)

To drop the map entirely, use `preset=none`. You get the area outline on a plain white background, with your points, labels, shapes and routes on top, like an outline of a country with a star and a city name:

```http
GET /v1/map.png?area=Czechia&poi=49.195,16.608|label:BRNO|marker:star|color:%23d03030|size:18&w=468&h=280&preset=none
```

![Only the outline of Czechia, with a red star at Brno](/docs/images/examples/outline-only.png)

`background` sets any color behind it, for example black to match a dark website. On a dark background the outline, labels and attribution switch to light colors:

```http
GET /v1/map.png?area=Czechia&poi=49.195,16.608|label:BRNO|marker:star|color:%23d03030|size:18&w=468&h=280&preset=none&background=%23000000
```

![The outline on black](/docs/images/examples/outline-black.png)

`background=transparent` returns a PNG (or WebP) with a transparent background that sits on any page. JPEG has no transparency, so `format=jpeg` with it is a `400`.

```http
GET /v1/map.png?area=Czechia&poi=49.195,16.608|label:BRNO|marker:star|color:%23d03030|size:18&w=468&h=280&preset=none&background=transparent
```

A tint at full opacity fills the area, which gives a solid silhouette:

```http
GET /v1/map.png?area=Czechia&w=468&h=280&preset=none&tint=%232d6a4f&tintopacity=1&outlinewidth=0
```

![Czechia as a filled silhouette](/docs/images/examples/silhouette.png)

With no map shown, the attribution still credits OpenStreetMap whenever the area or a place name comes from it. See [`preset`](/docs/reference/parameters.md#param-preset), [`background`](/docs/reference/parameters.md#param-background) and [`fade`](/docs/reference/parameters.md#param-fade).

## 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:

```json
{
  "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](/docs/images/examples/area-geojson.png)

## 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.

```http
GET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&w=468&h=280&preset=dark
```

![The dark preset](/docs/images/examples/preset-dark.png)

```http
GET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&w=468&h=280&preset=light
```

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](/docs/reference/presets.md); the parameter is [`preset`](/docs/reference/parameters.md#param-preset).

To use your own style, pass a MapLibre `style.json` URL as [`style`](/docs/reference/parameters.md#param-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:

```http
GET /v1/map.png?bounds=70,30,82,38&w=420&h=320&worldview=in
```

![Kashmir as India sees it](/docs/images/examples/worldview-kashmir-in.png)

```http
GET /v1/map.png?bounds=70,30,82,38&w=420&h=320&worldview=cn
```

![Kashmir as China sees it](/docs/images/examples/worldview-kashmir-cn.png)

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](https://www.naturalearthdata.com/downloads/10m-cultural-vectors/) (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`](/docs/reference/parameters.md#param-worldview). A self-hosted server serves only the worldviews it imported (`NE_WORLDVIEWS`; see the [configuration reference](/docs/reference/configuration.md)). Any other code returns `400 bad-request`.