OSM-Boundaries
Documentation
Index
- Introduction
- Data
- Browsing the Data
- Downloading the Data
- Plans and Pricing
- License
- FAQ
- Support and Feedback
Introduction
OpenStreetMap is an incredible source of public mapping data. In particular, it offers administrative boundaries—boundaries for countries, states, counties, municipalities—for most of the world. It also provides other classes of boundaries, such as historical and statistical boundaries.
This website strives to provide an interface through which one can view and process data related to these boundaries. In particular, we provide all way and boundary elements with both the name and boundary tags set.
Data
We provide data as-is. This means that the data is served without modification directly from OpenStreetMap's dumps. We do not modify it; nor do we correct issues or errors. Our goal is to provide an interface through which one can work with boundary data.
OpenStreetMap is powered by user-contributed data. Consequently, it is possible that the data is inaccurate or temporarily broken. For this reason, we offer views multiple versions of the data: from less than a month old to multiple years old. This should mitigate issues arising from temporary errors in OpenStreetMap data.
What's Imported?
As of 2021-03-15, all polygons with both the name and boundary tags set (regardless of value) are imported from OpenStreetMap's Planet.OSM dumps. While they generally export once per week, we typically import at most one database per month.
Previously, we imported data following much narrower rules. Note that we have not retroactively re-imported older databases under our newer rules.
boundary=administrativeand neithernameoradmin_levelis nullboundary=regionandnameorname:enisAntarcticboundary=disputeboundary=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)
The database of 2021-03-08 was imported using these rules.
boundary,name, andadmin_levelare set; orboundary=regionandnameisAntarctica(in various variants); orboundary=traditionalorcensus, even ifadmin_levelis not; or- Relation 2185386 (United States Minor Outlying Islands)
Note that invalid polygons are not imported. This means that relations definining polygons with self-intersections or non-closed polygons will not be available.
Projections and Spatial Reference Systems
Because the earth is neither flat nor perfectly spherical, projections and spatial reference systems are needed to faithfully and consistently represent fundamentally spherical data. There are thousands of systems used around the world: some are tailed to smaller areas (having high accuracy in the specific area) whereas other are globally applicable. SRID 4326 (WGS84), SRID 3857 (Spherical Mercator), and SRID 54003 (Miller Cylindrical) are common such systems.
OpenStreetMap uses SRID 4326 (WGS84) to store its data. For more reliable imports, we also use this spatial reference system internally. However, our Downloads interface gives the option to convert the SRID whilst exporting data.
Land-only Polygons Paid plan required
While standards may differ by region, usually, boundaries defined in OpenStreetMap include water (oceans and large lakes). However, OpenStreetMap also defines coastlines for landmasses. Using this data, we calculate land-only polygons for each boundary which removes area extending into the water. Using these, one can for instance produce beautiful static map images. The following table depicts the water and landonly polygons for Chile. Click images to enlarge.
| Water | Landonly |
|---|---|
|
|
Map © OpenStreetMap
Browsing the Data
The primary interface through which you can access OSM-Boundaries is the Map page. On the left is a tree for browsing boundaries, and on the right is a map. Using these tools, you can preview the data.
The tree displays a structured hierarchy of boundaries. It is computed dynamically based on the data: a boundary that fits entirely within a larger boundary is placed as a child of the larger. If both boundaries have the admin_level tag set, we require that the child has a strictly larger value than the parent.
We render the items of the tree sorted by admin_level, and use icons to indicate admin_level. An "X" indicates a boundary with no admin_level tag. A green icon indicates a boundary with a boundary tag of administrative; all others are colored red. Using the context menu, one can easily select all children of a particular node or all descendants of a particular admin_level.
Upon selecting a boundary, the map will update to preview the appropriate polygon. For the first selection only, the map will recenter the viewport around the polygon. Each administrative level is assigned a unique color, for easier view.
Databases
Above the hierarchy tree is a selector for the "database". Using it, one can choose the dataset from which information is fetched. The first option, Latest, will always point to the most recent, enabled, and fully-imported database. Note that the Download form will respect this selection.
Occasionally, a databases may be listed as being Partially ready. This means that while the database has been imported into our systems, not all post-processing is complete. In particular, many Land-only polygons may not yet be available. Use the Status page to determine the number of boundaries which remain to be processed.
Map Settings
| Boundary | By default, this setting is set to "administrative", which causes the tree to display only those boundaries with a boundary tag of administrative. Switching this to "all" will cause all boundaries to be displayed. |
||||
|---|---|---|---|---|---|
| Name field |
OpenStreetMap generally uses the name tag to specify local names using local character sets. However, you can instruct the tree to display the name:en field (when it exists) instead by changing this setting. Note that the site will fall-back to use the standard name field when a boundary does not specify a name:en tag.
|
||||
| Polygon field | This option specifies whether the preview map will display the original or Land-only version of a boundary. | ||||
| Polygon coloring mode |
By default, polygons added to the map are coloured based on their admin_level. With this setting, one can opt to color polygons with colours maximizing contrast between nearby boundaries.
|
Custom Tile Servers Paid plan required
By default, the preview map displays OpenStreetMap tiles. Members with paid plans may add custom tile servers on their profile page.
Console
A terminal console is available on the map page; collapsed at the bottom by default. The colored indicators denote the number of unread log entries. When expanded, the filter tool in the top-right can be used to reduce or increase verbosity. In addition, paying members can use command-line interface to interact with additional data-processing tools.
/clear |
Clear the console, including all history. |
|---|---|
/coverage boundaryId
Paid plan required
|
Produces a table displaying the coverage by admin_level of all children of a particular boundary. This command can also be accessed via the context menu in the tree. |
/parents boundaryId |
List the lineage of this boundary, up to the root. |
/query-all-dbs osmId
Paid plan required
|
Searches all of our databases based on an OpenStreetMap element ID. |
Downloading the Data
In order to be able to download any data, you must be authenticated. To do this, you will need an OpenStreetMap account. The authentication is accomplished using OAuth.
Options
| Boundary selection | By default, the Download selection is equal to the selection made in the hierarchy tree. However, it is possible to instead opt to choose a particular country. Moreover, the "recursive" option can be used to expand the selection to include all of its descendants. | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Admin level filter | This option can be used to filter the download selection by admin_level. This is useful in combination with the "recursive" option if, for instance, you wish to download all states or provinces in a particular country. |
|||||||||
| Boundary filter Paid plan required | This option can be used to filter the download selection by boundary. By altering the generated URL, it is possible to set this filter to any value. |
|||||||||
| Output format | This option can be used to select an output format, such as GeoJSON or KML. | |||||||||
| SRID | This option can be used to change the coordinate reference system used by the output file. | |||||||||
| Water Paid plan required | This option can be used to select whether complete or land-only polygons will be downloaded. | |||||||||
| Tags Paid plan required | This option can be used to opt to include all tags from the associated OpenStreetMap element. | |||||||||
| Hierarchy data Paid plan required | This option can be used to opt to include hierarchical information in the exported file. | |||||||||
| Simplify Paid plan required |
This option can be used to simplify the edges of the boundaries in a topologically-aware fashion using the Visvalingam–Whyatt algorithm. The simplification factor is measured in units of degrees, and so a simplification factor of 0.001 corresponds to a precision of approximately 100 m. Various simplification levels of the water polygon for Germany and the landonly polygon for British Columbia are depicted in the following table. Click images to enlarge.
Map © OpenStreetMap |
Depending on how complex your dataset is, it may take some time for our systems to build your file. For this reason, we provide a cURL command which you can use to download the data. However, in this case, we strongly recommend that you verify the response code: anything other than 200 should be considered some kind of error.
Credits
Credits are required to download from OSM-Boundaries. Each download costs 1 credit per included boundary. Based on membership level, a fixed quota of credits are allocated each 24h period. In addition, it is possible to purchase additional credits.
Plans and Pricing
Before July 2024, OSM-Boundaries was entirely free to use with an OpenStreetMap account. While the core functionality of the site remains free, some additional features now require a paid plan. For details, please see the Plans and Pricing page.
License
All downloaded data follows the license of OpenStreetMap. In addition, if you use data built by OSM-Boundaries we would appreciate a reference citing this site as the source.
FAQ
Are continent boundaries available?
While we would love to provide continent boundaries, unfortunately this is not a well-defined concept in OpenStreetMap's data. It is not always entirely obvious where borders should be drawn.
I am looking for boundary "X", but cannot find it. Where is it?
If there is a boundary that you believe should be available in OSM-Boundaries, begin by determining if it is available in a database other than the one you currently have selected. Paying members can use the Console to query all our databases using an element ID from OpenStreetMap. It is possible that the particular boundary was corrupted (self-intersections; not closed) and therefore was not imported by our systems.
If you still cannot locate the boundary, verify on OpenStreetMap that the boundary possesses both a boundary and name fields. If it does not, it does not meet the criteria to be imported by our systems. We invite you to appropriately tag the boundary so that it may be included in our next import.
Support and Feedback
Please use the Feedback button on the right side of the page to access our UserEcho forum. We invite questions, ideas, thoughts, constructive feedback, and feature requests. However, please be aware that OSM-Boundaries is a side project with no dedicated human resources. There will be periods during which we are unable to touch it.