Thenmap API v2

This documentation refers to version 2 of the Thenmap API. See this blog post for a list of things that have changed since version 1.

General syntax:

api-version/dataset/modules/date?language=XX

Each module has a set of specific url parameters, aside from the global language parameter, see below.

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

v2/se-7/geo/1982

API version

api-version/dataset/modules/date

Available versions are:

v1, see the v1 documentation
v2, documented on this page

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 borders 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

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.

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

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

Recommended projections:euref89no

no-4

Norwegian counties, from 1919

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

Recommended projections:euref89no

dk-7

Danish municipalities, from 1970

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)

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

Recommended projections:sweref99tm

se-4

Swedish counties, from 1968

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

Recommended projections:sweref99tm

us-4

US states

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

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.

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

Available modules are: data · info · geo · svg.

data

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

Method: get

Url parameters:

data_props

Data to retrieve foreach entity. Available properties 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 others.

Default:: id,name

data_format

Format of returned data

Default:: json
Allowed:: json,csv

info

Returns metadata on a dataset.

Method: get

geo

Returns geodata, as geojson or topojson.

Method: get

Url parameters:

geo_type

Format. Topojson is significantly smaller, but will take 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

geo_scale

¡DEPRECATED! Scale. Use a larger scale for very large or zoomable maps. Deprecation warning: This feature will be removed, and replaced with something more exact. The definitions of s, m, and l are not very clear, and varies from dataset to dataset; and the current implementation is shaky.

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

geo_props

Data from the data module, to include in shape properties

svg

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

Method: get

Url parameters:

svg_proj

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

svg_width

Width in pixels.

Default:: 600

svg_height

Height in pixels.

Default:: 600

svg_props

Data from the data module, to include as data attributes

Default:: empty

Date

version/dataset/modules/date

Can be on the form YYYY-MM-DD, YYYY-MM, or YYYY. The output will include only areas that existed at that very date. Dates in the database are local time and inclusive, meaning that 1947-03-01 will include a nation that gained independence on April 1 1947, according to the local timezone. In reality these dates are often up for debate, and different definitions of independence will be a much bigger source of ambiguity than time zones.

If you need all available areas at once (e.g. for creating an animated map), you can use the wildcard *. This is equivalent to leaving the date out in version 1 of the API.

2011-05 will be interpreted as 2001-05-01, and 2011 will be interpreted as 2001-01-01. Technically speaking all dates that the ECMAScript 2016 Date() contructor can parse could be used (e.g. May 1978 or 2017-12-20T20:11), but this is not guaranteed to work forever.

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 variants

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.

Variants are not yet implemented in version 2 of the API. If you need them, please keep using version 1 until they are in place.

Let us know if you have any specific need for versioning!

Examples

SVG image of the world 2015: /v2/world-2/svg/2015
All national borders as topojson, and their start and end date: /v2/world-2/geo/*/?data_props=sdate|edate&geo_type=topojson
All Swedish municipalities and their areas and names, in 1974, in Sami language: /v2/se-7/data/1974?data_props=area|name&language=se
Swedish municipalities in June 1978 as geojson, using the RT90 coordinate system: /v2/se-7/geo/1978-06-01?geo_crs=RT90
Metadata on the Swedish municipalities dataset: /v2/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-2/geo/1994-05-04?geo_variant=somalia=2