Documentation

Index

Introduction

OpenStreetMap is an amazing source of free map data. One of the things that's great is that it offers administrative boundaries—boundaries for countries, states, counties, municipalities, and so on—for most of the world. But, it also offers other borders, like historical, and statistical borders.

This site aims to provide you with a service for viewing and extracting such data in various formats. The data can then be used as is, converted into other formats, or imported into another database. We provide all ways and relations that has the tags name and boundary set.

The data

We provide data as is. That means, exactly like it is in OpenStreetMap. We do not modify it, neither do we correct anything in OpenStreetMap's end. Our scope is only to provide an interface to easily view and extract the boundaries.

The data in OpenStreetMap is user contributed, for free. It means that data sometimes is temporarily broken, or just wrong. To counter this we provide multiple versions of the data. Generally we have data that is less than a month old available, but also several years old data. This should help both again temporary errors, and to view historical versions in general.

Browsing the data

On 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 you want to view. At a later stage you may choose to download it.

The tree is a calculated hierarchy based on the boundary polygons found in OpenStreetMap. A boundary fitting within another boundary is placed as a child of the outer one. If they both have the admin_level tag set, it is also required that the child has a higher number than the parent. That is basically how the tree is built. Each level in the tree is sorted on the administrative level and then on the name. All boundaries has a small icon in front of their name. If an admin_level is set it will show that number, otherwise an X is shown. The icons are also color-coded. If the boundary has the tag boundary=administrative they are colored green, while others are colored red.

The tree supports right clicking on items for additional functionality. For example you can select all direct children, all children with a specific admin_level, or view all tags from OpenStreetMap.

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 map's polygons. The map automatically centers on the first selected polygon; after that you have to pan and zoom the map yourself.

Multiple databases

There is a database selector above the hierarchy tree. This shows the different datasets (planet.osm) we have imported. By changing the selector you change which database the interface fetches its information from. The Download form will respect this selector as well.

The first item in the selector is called Latest and will always point to the latest, enabled, and fully imported database.

If the database says that it's Partially ready it means that all data has been imported, but all the postprocessing isn't complete yet. This might mean longer download times and also that the land-only polygons (read more further down) aren't available yet.

Each database import takes several weeks; we cannot speed things up for you.

Map settings

Boundary

Use this setting to filter the tree to either show all boundaries or only those where boundary=administrative is set.

Name field

The default name field in OpenStreetMap generally uses local names, including local character sets. We also provide you the option to use the name:en tag when it exists. The site will fallback to the standard name tag when a boundary doesn't have the name:en tag set.

Polygon field

Boundaries in OpenStreetMap normally extends into the sea (water). While this is not always the case, it's the most common. Remember that OpenStreetMap is a project based on user contributions and that standards may differ geographically.

OpenStreetMap also aims to provide coastlines in the world. We use this data to calculate land-only polygons that cuts off water. This will make the polygons look beautiful when creating static map images for example.

With this setting you can toggle between the default polygons (water) or the ones we have intersected with the coastline (landonly).

Console

There is a console available on the map page, which collapsed at the bottom by default. The console has two purposes. It is both a window for log output and it also provides a command line interface (with auto-complete and tab support).

When collapsed it will show you how many unread log entries you have of different log levels with colored indicators. When expanded you can also filter the log levels you would like to see with the icon in the top right corner.

Supported commands:
  • /clear - Clears the console.
  • /coverage boundaryId - Returns a table showing the coverage per admin_level for a certain boundary.
  • /query-all-dbs osmId - Searches all our databases for a certain ID from OpenStreetMap.
  • /parents boundaryId - Shows a tree of parents for given boundary.

What's imported?

Since 2021-03-15 we import all polygons that has the tags name and the tag boundary set, regardless of what they are set to. The imports are based on the planet.osm dumps released by OpenStreetMap. They generally release one per week, while we generally only import one such dump per month.

Invalid polygons aren't imported. This means that all relations that results in self-intersects or non-closed polygons will be ignored by OSM-Boundaries. A fairly common issue. This is one of the reasons why we provide data from old databases as well.

Historically we have had more restrictive rules on what we imported, therefore the older databases do not have all that data. The original rule set looked like this:

  • boundary=administrative and neither name or admin_level is null
  • boundary=region and name (or name:en) matches Antarctic
  • boundary=disputed
  • boundary=historic (databases newer than 2021-01-04)
  • boundary=census (databases newer than 2021-01-04)
  • boundary=area (databases newer than 2021-01-04)
  • boundary=political (databases newer than 2021-01-04)
  • boundary=ceremonial (databases newer than 2021-02-01)
  • boundary=traditional (databases newer than 2021-02-01)
  • Relation 2185386 (United States Minor Outlying Islands)

Database 2021-03-08 was imported using these rules:

  • boundary, name and admin_level is set, or
  • boundary=region and name is Antarctica (in various variants), or
  • boundary=traditional or census, even though for example admin_level isn't set, or
  • Relation 2185386 (United States Minor Outlying Islands)

Projection

Since the earth isn't flat, projections are needed to represent the spherical data on a two dimensional plane. There are many common projections used in the world. Some are tailored to smaller areas, having high accuracy in the specific. Others are globally applicable, but are less accurate locally. Common spatial reference systems are 4326 (WGS84), 3857 (Spherical Mercator), and 54003 (Miller Cylindrical).

OpenStreetMap originally stores its data in SRID 4326 (WGS84). That's also what we use when we import the data. This means that we do not have any loss in quality and don't need to do any unnecessary transformation when that is the desired SRID.

The download interface supports exporting in other SRIDs than 4326. We'll then convert the data for your convenience.

Downloading the data

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

Downloads can either be based on the selection made in the hierarchy 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 time to build the file for you, and also reduce the size of the downloaded file.

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 coastline 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 downside is that it is less accurate. Generally, we do not advise selecting values above 1.

OpenStreetMap has a lot of different tags for each polygon in their dataset. Normally, we do not include them all in the downloaded data, since most users seek only the polygon data. However, by 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. The tags can also be viewed by clicking a polygon on the map, and then following the link provided.

Download times might be fairly long. This depends on how complex the data is that you have requested. While simpler jobs should work fine to download 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 by default in gzipped GeoJSON format, but other formats are available as well. After unzipping it you can view the data in QGIS for example, or import it into PostGIS.

We strongly suggest that you inspect the returned HTTP code. Anything but 200 should be considered some form of error.

Membership

For now this site is 100% free to use. This might change in the future.

License

Any map data downloaded follows the License of OpenStreetMap.

If you use data downloaded from us we would very much appreciate if you add a link to use as a source.

FAQ

Are continent boundaries available?

We would love to provide continent boundaries, but unfortunately that is not a concept defined in OpenStreetMap's data. It's not always obvious where the border between them would be either.

I am looking for boundary X but can't find it; where is it?

If you are missing data that you believe should exist in OSM-Boundaries you should check if it's available in another database than the one you have currently selected. The console supports searching all our databases for IDs from OpenStreetMap.

If you still cannot find it, you should verify at OpenStreetMap.org that it does have both boundary and name set. If boundary isn't set, the polygon doesn't match our import rules. If you believe it should have boundary set you should correct the data at OpenStreetMap. Likewise with the name; if the relation doesn't have a name at OpenStreetMap.org we will not import it. If you feel that it should have a name, correct the data. Once corrected, the polygon will appear alongside the next import at OSM-Boundaries.

Invalid polygons are not imported either. This includes polygons with self-intersections and polygons that aren't closed (doesn't start and end at the same point).

Support, ideas, thoughts, and feature requests?

Please use the Feedback button on the right side for questions and ideas. It helps us keep track of them, and potential answers will also be available for others. Also feel free to vote for suggestions by others that you like; this will help us prioritize tasks. But also please be aware of that this is a side-project which doesn't have any dedicated human resources. There will be periods where we pretty much do not touch it, therefore response times may be longer than wished for.