{map} · PAD tags

Syntax

{map 'world', data='name', key='field', value='field', scale='quantile', title='text', width=720, height=400}
{map 'europe', key='field', value='field'} ... {/map}

Parameters

view: The part of the world drawn: world (default), europe, africa, asia, north-america, south-america or oceania.

Options

data: The rows: a {data} store, a page array or a _data file, as for {chart}. As a pair the content is the rows - JSON, YAML, XML or CSV.
key: The field with the country: its ISO 3166 alpha-2 or alpha-3 code or its English name, in any case - else the first field that is no number.
value: The field with the number - else the first numeric field.
scale: linear (default: seven equal steps from the lowest value to the highest) or quantile (seven steps by rank).
width: The width in pixels, default 720.
height: The height in pixels; by default it follows from the view.
title: The accessible name, default <Value> by country.

Description

{map} draws countries filled by a value of their row - a choropleth - as inline SVG on the server (tags/_lib/map.php), from Natural Earth's outlines kept in PAD itself: no JavaScript, no map tiles, no remote service. The first parameter picks the view: the whole world, or a crop of the same projection at full detail for a continent. An unknown view is an error under the strict check.

The rows come from data= as for {chart}, or from the content of the pair - JSON, YAML, XML or CSV, read before the level walks it. key names the country, written as an alpha-2 code (NL), an alpha-3 code (NLD) or the English name; value the number. Rows of one country add up. A key that is no country is not drawn but named in the title (not on the map: ...), so a typo shows instead of disappearing.

The values are put in seven colour steps - the heatmap's --pad-chart-heat-0 to -6 - with a scale under the map. scale='linear' spaces the steps evenly between the lowest and highest value; scale='quantile' gives each step the same number of countries, which keeps a few very large values from washing out the rest. A country without a value is --pad-map-empty, and a map without any data is drawn all in grey.

Every country has a <title> - Netherlands: 1,234, the tooltip on hover - and the <desc> lists the values for a screen reader. Countries too small to keep an outline at the scale drawn are shown as small diamonds. For a single flag, see {country}.

Examples

A region from a data store

The south-america view, the countries by their alpha-3 codes.

Templateexamples/map/1-region.pad

{data 'forest'}
[ {"code": "SUR", "forest": 97.4}, {"code": "GUY", "forest": 93.5}, {"code": "BRA", "forest": 59.1},
  {"code": "PER", "forest": 56.4}, {"code": "COL", "forest": 52.9}, {"code": "VEN", "forest": 52.3},
  {"code": "ECU", "forest": 50.2}, {"code": "BOL", "forest": 46.6}, {"code": "PRY", "forest": 39.9},
  {"code": "CHL", "forest": 24.5}, {"code": "URY", "forest": 11.9}, {"code": "ARG", "forest": 10.4} ]
{/data}
{map 'south-america', data='forest', key='code', value='forest', width=320, title='Forest, % of land area, 2021'}

Resultopen alone

CSV in the pair, by quantile

Countries by English name in the content; scale=quantile puts the same number of countries in each step.

Templateexamples/map/2-pair.pad

{map 'europe', key='country', value='share', scale='quantile', width=480, title='Renewable share of energy use, 2022 (%)'}
  country,share
  Iceland,85.0
  Norway,75.8
  Sweden,66.0
  Finland,47.9
  Denmark,41.6
  Portugal,34.7
  Austria,33.8
  Spain,22.1
  Germany,20.8
  France,20.3
  Italy,19.1
  Poland,16.9
  Netherlands,15.0
  Belgium,13.8
  Ireland,13.1
{/map}