Boundaries Map 4.3 - English

The Boundaries Map provides a comfortable overview of the administrative boundaries in the OSM dataset. It also provides download capabilities for boundaries.

  • Overview of the administrative boundary tree for quality control purposes
  • Export of boundaries in various formats


The newest version is 4.3, from February 2018. Features that changed in 4.3 (compared to 4.2) are marked in red. And if the feature no longer exists, it is additionally crossed out.


bm overview1

There are 5 sections, with the following functionality:

  • Header
    Version of the application, timestamp of the data used, search bar, sidebar (on the right) and OAuth functionality.
  • Footer
    Options for export-format, buffer, union, export layout, export areas, CLI switch and the export button.
  • Left panel
    The treeview of the hierarchy of the administrative boundaries
  • Right panel
    The right sidebar can be toggled. It contains some short information, a link to a TODO page (in german), one donation button and the imprint.
  • Center
    The map :-). You can switch the basemap with the "+" in the top right corner; black/white looks best. Also a PayPal donation and flattr button - keeping the server running 24/7/365 consumes quite some energy. Please consider a donation.


The boundaries map was built as a tool for quality control to visualize the nesting of administrative boundaries. The boundaries to display are selected on the left side. This way you can spot inconsistencies quite easy.

bm overview1
Here L√ľbeck was not yet entirely accurate. The district Moisling(9) was not mapped correctly. Of course, it's corrected now.

Context menu:

bm contect menu

In Context menu (place cursor on the desired name, then right-click) you can trigger certain actions:

  • Select children (S):

    Selects all borders the next level.

  • Deselect children (D):

    Deselects all borders the next level.

  • Deselect all children (A):

    Deselects all children of all sublevels.

  • Select next admin level (N):

    Selects all children of the next deeper admin level. This is sometimes useful if there are on one level different admin levels which unfortunately happens from time to time.

  • Export full subtree (json & shp only) (X):

    This function is currently a simple export of an entire country or a part of the country - in a server-friendly way. Here the export is still started directly without further options.

  • Edit (JOSM & Merkaartor only) (E):

    It is using the remote edit functionality of these two editors. The relation of the border appears in the editor.


In the search field borders can be searched for. Small and large letters are not relevant. The percent sign "%" is used as a wildcard. This is standard with PostgreSQL.

You can search borders by relation and by country too. For relations enter the OSM ID numerically, for countries three digit ISO-code in upper case. (For example, DEU for Germany or ALB for Albania)

Note:A search using a search pattern that starts with "%", is compared to the other search slowest since the search index can not be used.

The first 20 hits are displayed. However, there is pending a solution to the case that the result does not appear in it, because it is not in the first 20 hits. Here you have to make the search for time stop detail.

bm contect menu

In the search field you can enter an OSM ID of the Border directly. A search with wildcard seems not useful here. Or? We will see.

bm contect menu


The important export parameters are configured in the footer.

bm footer menu

and for Bpoly (Buffered Poly Files):

bm footer menu

  • Select the desired export format.
    • shp - shapefile format
    • json - GeoJSON format
    • poly - OSM Polygon File
    • svg - SVG graphics
    • bpoly - OSM polygon file with an enlarged margin (buffer). This is sometimes advantageous during clipping.
      if bpoly is selected, the size of the buffer can be entered in kilometres.
    • Is Union activated, all borders will be merged to a single polygon with the perimeter (PostGIS: ST_Union ()) of all borders.

  • Select the desired export layout to match the planned processing.
    • single - all polygons in a single block
    • split - each polygon a separate data file
    • levels - all polygons of one admin level summarized in one data file

  • Select the desired export area.
    • water - The borders including oceanic areas (the 12-mile zone iir.) will be exported.
    • land - The borders will be clipped to the coastlines and the larger lakes.

  • Activation or deactivation of the Command Line Interface CLI functionality.
    • off: Export will be done as before.
    • on: A popup will display the command-line, which is necessary to do the export without using the GUI.


Since the use of the term API has repeatedly led to misunderstandings, I renamed this functionality CLI. It is not a classic "Application Programming Interface", which is used by programs, but a "Command Line Interface", which is usually used by humans.

However, the apiVersion and apiKey options are still supported.

See also

Currently authentication via OAuth is mandatory. This is due to the fact that many external "customers" don't use Boundaries Map for QA - this is what it was intended for - but as a source for downloading boundaries. Unfortunately they also download hundreds of boundaries simultaneously, which kept crashing my server. The mandatory authentication relaxed the situation a bit, as I now can see who is the culprit and can contact them directly via OSM mail, e.g. making them aware of the "Export full tree" feature or the CLI functionality.

For similar reasons, I limited the number of simultaneously selectable boundaries using the GUI. The current limit is 50, but this needs further fine tuning.

If you use clipped land boundaries, you will experience a considerably lower performance. These are much more complex than the sea boundaries, as they include the ragged coastline.


The CLI is ultimately an extended URL which is used together with a command-line program of choice (I recommend curl).

The goal it to separate the export of borders from Boundaries Map GUI. The GUI has significant weaknesses that result in many problems when invoking larger exports. This has sometimes even led to server crashes. In addition, the manual selection by dozens of borders is really tiresome.

  • selected
    Choose one of the following ways:
    • Specify the number of the relation you want the export data to start with.
    • Specify the 3-letter ISO-Code of the country you want to have exported.
    • Specify a list of boundary relations to export.

      ATTENTION: A maximum of 120 boundaries can currently be selected. If you need more, please use &from_AL, &to_AL and &exportLayout.

  • to_AL [default: to_AL=4]
    Specify the highest admin level to be exported.

  • from_AL [default: from_AL=2]
    Specify the highest admin level to be exported.

  • union [default: union=false]
    • true -The exported polygon will be created using the union (PostGIS ST_Union()) of all boundaries. The result will be one polygon describing the outline of all selected boundaries.
    • false - The boundaries will not be combined.

  • exportAreas [default: exportAreas=water]
    • water - The borders including the maritime water areas will be exported.
    • land - The borders will be clipped using the coastline.

  • exportLayout [default: exportLayout=levels]
    • single - export all borders in one single block.
    • split - each border goes to one separated data file.
    • levels - all borders within one admin level will go to one seperate data file.

  • exportFormat [default: exportFormat=shp]
    • shp - Shapefile format
    • json - GeoJSON-format
    • svg - SVG grafic

  • cliKey
    This is a user specific key of the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    In order to view your specific key you have to be logged in. Make sure the GUI popup option is activated, where your key will be displayed. Please copy and keep your key safely. Never forward your key to others since the next version might include a quota system based on that key.

  • cliVersion [default: cliVersion=1.0]
    Specifies which CLI version to use. Just now this is version 1.0.

  • URL
    The CLI will be called using followed by some parameters.


  • Export all administrative boundaries of germany up to admin level 8 (with relation)

    curl -f -o --url '


    • Curl is recommended and used since it provides good error handling compared to wget. Activate the error handling with the -f command line option.

    • The URL starts with https - http is not activated.

    • The usage of this URL within a browser is not supported!

    • The URL has to be enclosed in single quotation marks (') otherwise the command line processor of the operating system has parsing problems. Linux is confirmed to work, Windows needs to be tested (Windows usually uses double quotation marks).

    • In the example all options of the CLI are used, not all are necessary for simpler cases.

    • The CLI key can be discovered for the first time by starting an export in the GUI with actived CLI option. You need to be authenticated. The GUI then shows a popup will all necessary information:

    • api popup blurred

  • Export all administrative boundaries of Germany up to admin level 8 (using ISO-Code)

  • curl -f -o --url '
  • Export all states (AL=4) of the USA

  • curl -f -o --url ''

    Here a separate (exportLayout=split) JSON-File (exportFormat=json) is created per country. Coastlines are used (exportAreas=land).

  • SVG graphic of all countries of the world (only AL2 !)

  • curl -f -o --url ''

    Here a single (exportLayout=single) SVG graphic (exportFormat=svg) which includes all boundaries of the planet (selected=0) is created.

    Further admin level are are not planned since the server load would be too high.

  • The following image shows the output and further processing under Linux:

  • #curl -f -o --url ''
      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100  114M  100  114M    0     0   590k      0  0:03:18  0:03:18 --:--:-- 3951k
    #ls World_AL2.GeoJson World_AL4.GeoJson
    (C) OpenStreetMap contributors
    inflating: Germany_AL2.dbf 
    inflating: Germany_AL2.prj 
    inflating: Germany_AL2.shp 
    inflating: Germany_AL2.shx 
    inflating: Germany_AL4.dbf 
    inflating: Germany_AL4.prj 
    inflating: Germany_AL4.shp 
    inflating: Germany_AL4.shx 
    inflating: Germany_AL5.dbf 
    inflating: Germany_AL5.prj 
    inflating: Germany_AL5.shp 
    inflating: Germany_AL5.shx 
    inflating: Germany_AL6.dbf 
    inflating: Germany_AL6.prj 
    inflating: Germany_AL6.shp 
    inflating: Germany_AL6.shx 
    inflating: Germany_AL7.dbf 
    inflating: Germany_AL7.prj 
    inflating: Germany_AL7.shp 
    inflating: Germany_AL7.shx 
    inflating: Germany_AL8.dbf 
    inflating: Germany_AL8.prj 
    inflating: Germany_AL8.shp 
    inflating: Germany_AL8.shx

    The time needed for the creation of a new export can reach several minutes up to a maximum of 10 minutes. After 10 minutes the job is aborted. If there are frequent abortions, please notifiy me.

    The result is a ZIP file with all administrative boundaries of Germany, one separate shape per admin level.

  • Internal cache and impacts:

    All exports and graphics generated between update cycles are temporarily stored in a server cache. That means the results are stored on the server and answered in some cases directly from the cache. This results to significantly faster answers for frequently occurring queries. This may be seconds instead of minutes :).

    Subsequent queries with absolutely the same parameters (exportFormat, exportLayout, exportAreas, from_AL, to_AL and selected) are answered from the cache.

    Cache is reset each night by the analysis of the raw data. This usually takes place in the middle of the night, but sometimes a little bit later, depending on how long the evaluation of the raw data runs.

    I will query for the most "popular" exports and will create new ones in the early morning, so that the otherwise empty cache is already filled with something.

  • Finances:

    The server is operated privately @home by me and as such caused considerable hardware, power and communication costs. Currently, this is a 16-core computer with Intel Xeon, 64 GB memory, 4 TB HDD and 3x960 GB SSD.

    Please notice the "Donate" button on the upper right, enabling you to do donations via PayPal. I particularly appreciate donations from companies that gain considerable advantage of using the data supplied here.

    I do not want to have to go as far as charging for downloads of commercial users or even completely discontinue the service.