# Neighboring countries

Neighbor labels name the countries around your area, placed inside each country's visible part. They need an `area`.

## What to show

`neighbors` picks what each label shows: the country name, its international vehicle registration code (D, A, SK, PL), its flag, or a flag combined with the code or the name.

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

![Czechia with flags and vehicle codes](/docs/images/examples/neighbors-flag-code.png)

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

![Czechia with neighbor names](/docs/images/examples/neighbors-names.png)

Both `flag+code` and `flag code` work; a literal `+` in a query string is read as a space, and the server treats the two the same. `neighbors=false` turns labels off. Values: [`neighbors`](/docs/reference/parameters.md#param-neighbors).

Which countries get a label is `neighborwhich`: `touching` (the default) labels countries that border the area, `visible` labels every other country in the frame too. Size, color and uppercase names are `neighborsize`, `neighborcolor`, `neighborupper`.

```http
GET /v1/map.png?area=iso:CZ-72&w=420&h=320&padding=0.3&neighbors=name&neighborwhich=visible&neighborupper=true
```

![Names of every visible country, uppercase](/docs/images/examples/neighbors-visible.png)

## When a label does not fit

A label has to fit inside the visible part of its country. When a frame is tight, a neighbor such as Austria may show only a sliver. `neighborfit` decides what happens:

| Fit | Behavior |
|---|---|
| `extend` (default) | grows the image on the side nearest the country until the label fits |
| `shrink` | reduces the label text |
| `drop` | omits the label |

`extend` is the one to understand: the result can be **larger than the `w` and `h` you asked for.** The real size is in the response headers `X-Image-Width` and `X-Image-Height`, in pixels (already multiplied by `scale`). Read them if your layout depends on the dimensions, or use `shrink` or `drop` for a guaranteed size.

```http
GET /v1/map.png?area=Czechia&w=468&h=270&padding=0&neighbors=flag+name
```

![A tight frame: the image grew to fit Austria and Slovakia](/docs/images/examples/neighbors-extend.png)

With `padding=0` the country touches the edges, so the neighbors' labels have nowhere to go and the canvas grows. The same request that must keep its size:

```http
GET /v1/map.png?area=Czechia&w=468&h=270&padding=0&neighbors=flag+name&neighborfit=drop
```

![The same frame at the requested size, labels dropped where they do not fit](/docs/images/examples/neighbors-drop.png)

In a browser, give the `<img>` the size you requested and let the headers tell you when you need to adapt. With `?response=json` on POST, the `meta.neighbors` object lists `labeled`, `dropped` and how many pixels each side was `extended`.

Parameters: [`neighborfit`](/docs/reference/parameters.md#param-neighborfit), [`neighborwhich`](/docs/reference/parameters.md#param-neighborwhich).

## Language

Names are local by default: Deutschland, Polska, Slovensko, the way Wikipedia locator maps do it. `lang` switches the label language (a two- or three-letter code):

```http
GET /v1/map.png?area=iso:CZ-72&w=420&h=320&neighbors=name&lang=en&neighborupper=true&preset=dark
```

![English country names on the dark preset](/docs/images/examples/neighbors-lang-en.png)

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

The same in POST, using the nested `neighbors` object:

```json
{
  "area": "Czechia",
  "neighbors": { "show": "flag+code", "which": "touching", "fit": "shrink", "size": 12 },
  "lang": "en",
  "width": 468,
  "height": 280
}
```