On this page

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.

GET/v1/map.png

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

Try it (opens the API in a new tab)

GET/v1/map.png

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

Try it (opens the API in a new tab)

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.

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.

GET/v1/map.png

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

Try it (opens the API in a new tab)

Names of every visible country, uppercase

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.

GET/v1/map.png

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

Try it (opens the API in a new tab)

A tight frame: the image grew to fit Austria and Slovakia

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:

GET/v1/map.png

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

Try it (opens the API in a new tab)

The same frame at the requested size, labels dropped where they do not fit

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, 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):

GET/v1/map.png

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

Try it (opens the API in a new tab)

English country names on the dark preset

See lang.

The same in POST, using the nested neighbors object:

POST/v1/map

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

Map rendered by the neighbors-post example