Thenmap API v1

This documentation refers to version 1 of the Thenmap API. The latest version is version 2.

General syntax:

api-version/dataset/modules/date

Only api-version and dataset are required, though you will generally want all four parts in there.

Here is an example, returning geodata for Swedish municipalities as of 1982:

v1/se-7/geo/1982

All url parts after api-version can also be provided as url parameters:

v1/?dataset=se-7&modules=geo&date=1982

Version

version/dataset/modules/date

The only valid version is v1

Datasets

version/dataset/modules/date

We name our datasets like this: area-level. For the area, we use ISO 3166 codes where available, and for level, we use the ten levels of administrative border from Open Streetmap. In other words yd-4 would be the governorates of South Yemen. Not that we have them (yet), but let us know if you need them!

fi-8

Finnish municipalities, from 2010

Aliases:finland-8,finland8,fi8,finland,fi

Languages: sv.fi.en.ru.se.et.no.The default language is fi.

Recommended projections:tm35fin

ch-8

Swiss municipalities, from 2010. Data source: Federal Office of Topography. Please note the source when reusing the data.

Aliases:ch8,switzerland,switzerland-8,switzerland8,ch

Languages: als.frp.lmo.de.fr.it.rm.en.sq.es.tr.pt.The default language is de.

Recommended projections:swissgrid

no-7

Norwegian municipalities, from 2006

Aliases:norway,norway-7,norway7,no,no7

Languages: nb.nn.no.en.se.fi.da.The default language is nb.

Recommended projections:euref89no

no-4

Norwegian counties, from 1919

Aliases:norway-4,norway4,no4

Languages: nb.nn.no.en.se.fi.da.The default language is nb.

Recommended projections:euref89no

dk-7

Danish municipalities, from 1970

Aliases:

Languages: da.de.en.sv.ffr.nds.fo.The default language is da.

Recommended projections:euref89dk

se-7

Swedish municipalities, from 1974 (a few borders in southern Sweden still missing from 1973)

Aliases:sweden-7,sweden7,se7,sweden,se

Languages: sv.en.fi.se.The default language is sv.

Recommended projections:sweref99tm

se-4

Swedish counties, from 1968

Aliases:sweden-4,sweden4,se4

Languages: sv.en.fi.se.The default language is sv.

Recommended projections:sweref99tm

us-4

US states

Aliases:us4,us

Languages: sv.en.es.zh.fr.de.it.nl.tl.vi.ik.ko.ru.fa.nv.th.chr.ar.The default language is en.

Recommended projections:albersUsa

gl-7

Municipalities of Greenland since the home rule

Aliases:

Languages: kl.da.sv.no.en.The default language is kl.

Recommended projections:gr96

world-2

Countries of the world. Generally speaking, de-facto independent nation are included, even if when they enjoy limited international recognition.

Aliases:world

Languages: sv.en.fi.fr.de.es.ru.it.nl.pl.zh.pt.ar.ja.fa.nn.no.he.tr.da.uk.ca.id.hu.vi.ko.et.cs.hi.sr.bg.nn.The default language is en.

Recommended projections:robinsonmollweide

Modules

version/dataset/modules/date

Modul names are separated by pipe (|). Default is to use every available module.

Available modules are:data,info,geo,svg

data

Returns data (such as names and dates) on political entities.

Module specific parameters (get):

data_props

Data to retrieve. Will depend on the dataset, but `shapeid` (corresponding shape in the geo module), `name`, `sdate` (first date the entity should be present on a map), `edate` (last date), will always be available (use the `info` modul to find out more). Properties will be grouped by shape, and each shape will have an array of one or more political entities connected to it.

Default:: id

data_lang

Laguage to use for translatable properties, such as name. Available and default languages will depend on dataset chosen (use the `info` modul to find out more).

language

Deprecated. Use data_lang.

data_variant

Chose a particular variant of a border, or set of borders. E.g. `somalia=1` or `somalia=2`. Multiple variants can be semicolon separated.

info

Returns metadata on a dataset.

geo

Returns geodata, as geojson or topojson.

Module specific parameters (get):

geo_type

Format. Topojson is significantly smaller, but will take slightly longer for the API to produce.

Default:: geojson
Allowed:: geojson,topojson

geo_crs

Coordinate reference system. Anything other that wgs84 will be reprojected, and therefore slower.

Default:: wgs84
Allowed:: sweref99,wgs84,rt90,tm35fin,kkj,etrs89

geo_variant

Chose a particular variant of a border, or set of borders. E.g. `somalia=1` or `somalia=2`. Multiple variants can be semicolon separated.

geo_scale

Scale. Use a larger scale for very large or zoomable maps.

Default:: s
Allowed:: s,m,l

geo_props

Data from the data module, to include in shape properties

Default:: empty

geo_lang

Laguage to use for translatable properties, such as name. Available and default languages will depend on dataset chosen (use the `info` modul to find out more).

geo_flatten_props

Create a flat entity/property structure, rather than a two or three dimensional? There will not always be a one-to-one relation between geoshapes and data entities, but if you are fetching geo data from only one specific date, it might be useful to flatten the properties. Set this to `true` if you want to use the geodata in e.g. CartoDB. This will flatten not only entities, but also their properties.

Default:: false
Allowed:: true,false

svg

Returns an SVG representation of the borders from a dataset at a certain time.

Module specific parameters (get):

svg_proj

Defaults to the first recommended projection for this dataset. Use the info module to see all recommended projections.

projection

Deprecated. Use svg_proj.

width

Deprecated. Use svg_width.

height

Deprecated. Use svg_height.

svg_width

Used for viewport size, and svg width attribute. (px)

Default:: 600

svg_height

Used for viewport size, and svg height attribute. (px)

Default:: 600

svg_variant

Chose a particular variant of a border, or set of borders. E.g. `somalia=1` or `somalia=2`. Multiple variants can be semicolon separated.

svg_props

Data from the data module, to include as data attributes

Default:: empty

svg_lang

Laguage to use for translatable properties, such as name. Available and default languages will depend on dataset chosen (use the `info` modul to find out more).

Date

version/dataset/modules/date

Can be on the form YYYY-MM-DD, YYYY-MM, or YYYY. Will include only areas that existed at that that date. To get current areas, use a far future date, or simply 9.

Languages

Some properties of the datasets, such as names of political entities, are automatically translated using WikiData. When a translation is missing, the following fallback rules are applied, before falling back to the default language of the dataset, and lastly, to English:

fit → fi

fkv → fi

nn → nn

no → nb

sr → sr-ec

uk → ru

zh → zh-hans

kl → da

li → nl

wa → fr

als → de

frp → fr

lmo → it

nds → de

If nothing else is stated, these rules apply to all modules that use the language parameter.

Dataset versioning

Datasets may contain different versions of borders. For instance, it might in some cases be useful to show Somaliland as a nation, given its de facto indepence, where as in other cases you might want to show its de jure status as part of Somalia. Let us know if you have any specific need for versioning!

Examples

SVG image of the world 2015: /v1/world/svg/2015
All national borders as topojson, and their start and end date: /v1/world/geo|data/?data_props=sdate|edate&geo_type=topojson
All Swedish municipalities and their areas and names, in 1974, in Sami language: /v1/se-7/data/1974?data_props=area|name&data_lang=se
Swedish municipalities, using the RT90 coordinate system: /v1/se-7/geo?geo_crs=RT90
Metadata on the Swedish municipalities dataset: /v1/se-7/info
Borders of the world on May 4th, 1994, using a specific variant of a subset of the world-2 dataset: /v1/world/geo/1945-05-04?geo_variant=somalia=2