Documentation

Introduction

OpenStreetMap is an amazing source getting free map data from. One of the things that's great is that it has administrative boundaries for most of the world. Borders for countries, states, counties, municipalities and so forth that is.

This site aims to provide you a service for extracting such data as GeoJson, which can then either be used as is, converted into other formats, or imported into another database. The data we provide is data based on OpenStreetMap.org's Tag:boundary=administrative.

Browsing the data

At the Map page you will find a browsing tree to the left and a map to the right. With these you can preview and select the data, and then later on download it.

The tree is based on the administrative levels of the boundaries. Boundaries fitting inside another boundaries is placed as a child to the outer one, and that's how the tree is built. Each level in the tree is sorted on the administrative level and then on the name.

You can either select a whole country, or expand it and look for specific areas in the world. Any select or de-select in the tree will update the map, showing the data that you just selected. Each administrative level has its own color on the polygons shown. The map automatically centers on the first selected polygon, after that you have to pan and zoom the map yourself.

The data tree supports right clicking by the mouse. From there you get access to additional smooth functions, for example selecting all children, or a specific administrative level.

Multiple databases

There is also a database selector below the map. This shows the different data-sets we have imported. By changing the selector you changes which database the web fetches its information from. The Download form will respect this selector as well. Note that changing the selector will clear all selections in the tree, and the map.

What's imported?

The import from OpenStreetMap is currently based on these rules:

  • boundary=administrative and neither name or admin_level is null
  • boundary=region and name (or name:en) matches Antarctic
  • boundary=disputed
  • Relation 2185386 (United States Minor Outlying Islands)

We are open to suggestions for importing other data as well. Please provide us with links to the relations at OpenStreetMap.org and some description to what it is. For example we know that there are ~12,500 polygons which have boundary=administrative but a null value for either admin level or the name. We have not looked into these, but our guess is that it will mostly create chaos if importing them all. We are guessing that most is trash data.

In some cases, including the above actually used rules, it might be better to fix the OpenStreetMap data though.

An import of a new database requires 1-2 days for processing the data. It varies quite a lot between the different versions of Planet.osm. We haven't investigated why, but it's likely that there at times are invalid data that's causing a lot of issues for PostgreSQL/PostGIS.

Downloading the data

To be able to download any data you must authenticate. You need an OpenStreetMap account for this. The authentication is done using oAuth.

Downloads can either be based upon the selection made in the tree, or a single selected country in the Download form. Added to this there are multiple filters and options available to help you streamline the data you download. For example you can specify the minimum and maximum administrative levels that you are interested in. This can significantly reduce the size of the downloaded file.

Adminstrative boundaries in the OpenStreetMap data often extends into the sea, far beyond the coast line. By selecting the option Land only you will download polygons we have prepared to follow the coast line instead, these are often a lot more complex and might use a lot of resources.

If you wish you can select one of the Simplify levels in the select box with the same name. If so, the data downloaded will use less vertices and therefore be less complex. The down-side is that it's also less accurate. Generally it's not recommended to use values above 1.

OpenStreetMap has a lot of different tags for each polygon in their data-set. Normally we don't include them all in the downloaded data since most just wants the polygon data itself, buy checking the Include All tags option you can change this behaviour. The most common tags are names with different translations. You can preview a polygons tags by right clicking it in the tree, selecting Info and then Show all tags.

Download times might be fairly long, depending on how complex the data is that you have requested. While it should work fine to download it via your web browser we generally suggest that you use the CLI tool Curl to download it. The Download form provides a download url, a full Curl command line, and a Download button.

Downloaded data is in gzipped GeoJson format. After unzipping it you can view the data in QGIS for example, or import it into PostGIS.

Continents

We would love to have support for Continents but that's not something that exists (as boundaries) in OpenStreetMap data. It's not always obvious where the border between them would be either.


Created as a substitute for the most useful https://wambachers-osm.website/boundaries/ since it was shut down early 2020.

Copyright © 2020 Ground Zero Communications AB. All Rights Reserved.