We have redesigned the API for Thenmap, our repository for historical administrative borders, to make it easier to use, and more reliable. Here are the Finnish municipalities in 2011 as an SVG image, with the new API: api.thenmap.net/v2/fi-8/svg/2011.

The most important difference between the new version 2 and the old version 1 is that the new version made for human use. The old version used a json structure to return all data in a consistent format. While json is a great format for machines, it turned out that most of our users where in fact humans. From now on, when e.g. calling the SVG endpoint, you will, to little surprise, get an SVG image in return. Like in the Finnish example above. The old API remains in place, and will not go anywhere for the foreseeable future, but there are differences in how images are rendered behind the scenes that will make things look a bit different even when using the old API, so keep reading if such details matter to you.

The structure of embedded properties (things like, names, capitals, and flags), are also much simplified. Before, we used a structure that would support fetching data from multiple points in time at once. It turned out literally nobody used the API like that. Rather it was used for fetching borders at a specific point in time. The new API is built with that as the default use case. This also makes the API more compatible with other services like CartoDB.

Below is a list of things that have changed:

• Modules are called once at a time. In v1, you can fetch, image and data in one API call with something like /v1/se-7/svg|data/1989. That was a neat feature that no-one had asked for and literally no-one was ever using. Removing that for less complex output, and slightly a faster API.

• Date is mandatory. You can no longer omit the date (and get data from all times). If you really want to see everything in a dataset at once, you can use the wildcard * instead, like this: /v2/gl-7/data/*/?data_props=name|capital (to get names an capital cities on all Greenlandic municipalities, both current former ones)

• SVG's are now returned as SVG images, which makes sense. Like the world in 1949: /v2/world-2/svg/1949/?svg_width=1000

• Geojson and topojson results from the geo endpoint are now return as — you guessed it &mdasg; geojson and topojson! Here's the geodata used to produce the SVG above: (/v2/world-2/geo/1949/)[http://www.thenmap.net/v2/world-2/geo/1949/]

• The parameter geo_size is deprecated, and will be removed. This parameter, used for fetching maps/geodata of higher or lower resolution (l, m, or s sizes), was very inconsistently implemented across datasets. It will eventually be replaced by something more stable. Let us know if this is a priority to you!

• Properties in geodata and SVG's are now “flat”. In other words, when asking for the capital of Tanzania or Bolivia, the replay will look something like this: {capital: "Dodoma"} or {capital: ["Sucre", "La Paz"]} (roughly equivalent to setting geo_flatten_props to true in the former version). This makes much more sense when fetching data for one single point in time. If you need to fetch this kind of data for multiple timepoints, e.g. for creating animated maps, you might want to stick to the old API, that better caters for this need.

• Every single data unit now represents an administrative entity, e.g. a nation, rather than the shape of a an administrative entity. This means for instance that when using a wild-card (*) for date, British Hong Kong and independent Hong Kong will show up as to separate entries, despite sharing the same geographic area. This is a much more straightforward way to organize data when accessing it one date at a time. And don't worry; There will be duplicated shapes in geodata output. British Hong Kong and independent Hong Kong still share the same geodata feature / SVG element.

• Dataset aliases are deprecated (they added confusion for users and complexity for the computer, but really no value for either). Use the proper dataset id's, as documented on api.thenmap.net, e.g. se-4 for Swedish counties.

• Some projections no longer available from the SVG endpoint, and some will look slightly different. We now do all re-projection with the Proj4js library, so if you want to contribute to new a projection, the fastest way is to add it there! Most notably missing one is probably the Robinson, that used to be the default for world maps. It seems to be added to the upcoming version of Proj4js, so we hope to have it included again soon.

Known issues:

• Robinson projections is missing, see above!

• US projections needs love, and a compound view for showing Alaska and Hawaii. The API has seen exactly zero requests for projected US maps, so not a priority at the moment.

• The API is still slow, and not made for real-time queries. Our target audience is journalists and other newsroom people who usually want to download their data to keep working on it.

Found another issue? Report it on the Trello board: (trello.com/b/aqFu3s1d/thenmap)[https://trello.com/b/aqFu3s1d/thenmap]