OpenStreetMap (OSM) XML Reader/Writer

The OpenStreetMap (OSM) is a collaborative mapping project for creating a free and editable map of the whole world.

This section assumes familiarity with the OSM format. Further information on OSM can be found at


OpenStreetMap data can be downloaded in a topologically structured XML format. The data primitives in an OSM data file are nodes, ways, and relations.

  • A node is a lat/lon pair.
  • A way is a list of at least two node references describing a linear feature. Ways can be closed, in which case the first and the last node are identical. Areas are not explicitly represented in OSM, but are identified via community-approved tags.
  • Relations are a group of zero or more primitives with an associated role. All data in OSM are in the WGS-84 datum.

OSM has no explicit schema (feature type) definitions. Each node, way, and relation can have an arbitrary number of attributes (called tags in OSM). A tag is composed of a key and a value. The OpenStreetMap wiki does define a set of recommend tags that can be used to classify the nodes and ways into higher-level groupings (feature types).

The FME OSM reader provides some user settings to help influence the classification of the OSM data being read. This is needed for most GIS formats that have explicit schema definitions. The community-defined feature types can be found at

Reader Overview

The OSM reader can interpret OSM XML files in several different ways. The reader may output un-categorized nodes, ways and relations, or it may categorize these data primitives according to the recommended interpretations found in

The OSM reader provides a tree-view interface when directed to interpret the OSM data with the OSM community-approved feature types. The data can be interpreted using both broad and specific features.

For example, users can choose all broad features by selecting the top-level elements in the tree view (for example, highway, aerialway, etc.); and choose all specific features by expanding the broad features and selecting the specific features (such as highway_motorway, highway_primary, etc.). Users can also select combinations of broad and specific features.

The OSM reader also allows users to provide their own user configuration file. This user configuration file enables users to define their own feature types and also add any attributes or geometry types to them. In addition, the user file can be used to remove existing feature types, attributes, and geometry types. The user file can also be used to determine whether feature geometries should be interpreted as lines or areas when the feature is a closed way.

Note that the reader provides an option to perform a schema scan on top of the selected features in the tree view. In this case, the reader will scan the entire data file and any features found that are also selected in the tree view will be constructed. A schema scan on a large file can be a slow process: in these cases, it may be more desirable to simply select feature types manually.

With three exceptions, the OSM relations are not interpreted. The interpreted relations are the ones that are tagged with a key of type and values of either multipolygon, route, or restriction. Both route and restriction are output as non-geometrical features, and their feature types are set to relation_route and relation_restriction, respectively. The multipolygon relation is output as an area or multi-area geometry; this includes donuts, or an aggregate of polygons and donuts. The multipolygon relation may be output as a line or a non-geometrical feature. In the case of bad geometrical information, the multipolygon relation feature type will be set to relation_multipolygon.


The OSM reader supports points, lines, and area geometries. Points are constructed from OSM nodes, linear features from OSM ways, and area features are constructed from either appropriately tagged closed OSM ways, or from OSM multipolygon relations.

Coordinate Systems

The features output by the OSM reader are always in LL84.

FME Feature Attributes

All OSM tags are loaded from the OSM data primitives are loaded as FME feature attributes. Relation feature types will have their members mapped as an FME list attribute in the FME feature. The list attribute will have 3 components:




Relation feature types will also have an attribute named as osm_relation_type to describe the type of relation.

You can use this member list attribute to further process the relations within FME Workbench.

In OSM way features are constructed by reference to node IDs. These node IDs are mapped into the nd{}.ref list attribute in FME way features.

Writer Overview

The OSM writer will write out features as nodes, ways, and relations into an OSM file. Lines and areas that have more than 2000 points will be split into multiple ways, each having at most 2000 nodes. Duplicated nodes are also handled to make sure no duplicate OSM nodes are written out. Conversion of coordinates into WGS84/LL84 is done automatically into the writer.

© OpenStreetMap contributors