Selecting Features

Overview

OpenStreetMap is a planet-scale database of tagged geographic features. There are three types of OpenStreetMap entities:

  • Nodes, which represent a point on the surface of the earth.
  • Ways, which are sets of nodes that can form lines or polygons.
  • Relations, which are sets of nodes, ways or other relations.
Each of these three types of entities can have any number of key/value tags. For example, a post office may be represented by a way with tags building=yes and amenity=post_office.

When we want to select part of OSM to use in our own projects, we must select:

  • A geographic query area.
  • a Tag Filter, or a subset of OSM features we are interested in. For example, when mapping buildings we want to limit our exports to only ways and relations that are tagged building=true.
  • a Key Selection, or a subset of OSM keys we are interested in. At the present, there are tens of thousands of different OSM keys in use, so we only want the relevant ones. Additionally, many useful GIS formats require a fixed tabular schema where each feature has a known set of columns. For example, when mapping buildings we may also want to select the keys name and amenity, as these contain useful information.

The Export Tool provides two facilities for defining Tag Filters and Key Selections.

  • The Tag Tree is for common use cases, presenting a curated set of filters and selections.
  • The YAML format provides complete control over filters and selections, using a SQL-like filter definition.

Tag Tree

The tag tree is the simplest way to get started selecting features.

Each Parent Checkbox filters the data to a category of features, also including relevant tags.

Each parent checkbox can expanded, and individual Child Checkboxes can be selected to further filter down the data.

The Infobox on the right shows detailed information about the tags and filters specified by the hovered checkbox.

The Tag Tree generates YAML, so you can preview the YAML document created by switching tabs.

If you have suggestions for categories to add to the Tag Tree, please comment on this Google Spreadsheet. The HOT Team will update the Tag Tree periodically based on user requests.

Defining YAML when Creating an Export

YAML can be defined via the "Select Features" tab when creating an export. This can be edited inline or copy-pasted from a local file on your computer. Please note that YAML is whitespace-sensitive. For more information on the YAML format, see the documentation: YAML Specification.

Saving YAML as a Configuration

YAML can be defined and saved for future re-use via the Configurations page. It's useful to create one Configuration for a project which is then used on all exports related to that project. Give your Configuration a name and description that will make it discoverable by other mappers. Unchecking the "Public" checkbox will make your Configuration only visible to yourself. Notably, Configurations can be edited, so this is useful for evolving a feature selection during the course of a project, e.g. adding additional key selections.

Re-using a Configuration when Creating an Export

Saved Configurations can be selected via the "Stored Configuration" option on the Select Features tab when Creating an Export. Use the Search bar to find configurations related to your project.

Examples

Example YAML configurations are available in the osm-export-tool-python repository.

  • default.yml is a very broad selection of features, organized into themes, based on the imposm3 example_mapping.yml. This is a good choice for cartography if you don't know in advance which features you need to select.