Feature Objects

A Feature represents a geographic element. This can be a point of interest like a mailbox or a restaurant, a park, a lake, a segment of a road, or an abstract concept like a bus route.

OpenStreetMap uses three types of features:

Node – a simple point feature
Way – an ordered sequence of nodes, used to represent line strings and simple polygons
Relation – an object composed of multiple features, such as a polygon with holes, a route or a river system. A relation may contain nodes, ways or other relations as members.

Each feature has a geometric shape (Point, LineString, Polygon or a collection type), as well as one or more tags (key-value pairs) that describe its details. To access a feature’s tags, use feature["key"]. If the tag key is a valid attribute name (letters and digits only, must start with a letter) and doesn’t collide with a property, you can simply use feature.key.

>>> city["name"]
'Praha'
>>> city.name
'Praha'
>>> city["name:en"]     # must use [] because key contains :
'Prague'

Tag values can be strings or numbers, or None if the feature doesn’t have a tag with the given key. To coerce the value to string or numeric, use str() (returns an empty string if tag doesn’t exist) or num() (returns 0 if tag doesn’t exist or is non-numeric).

>>> city.population
1275406
>>> city.str("population")
'1275406'
>>> city.num("no_such_tag")
0

Use tags to get all tags. A Tags object offers additional options to convert and filter tags.

>>> street.tags
'{"highway": "residential", "name": "Rue des Poulets", "maxspeed": 30}'
>>> street.tags.html
'highway=residential<br>name=Rue des Poulets<br>maxpeed=30'

OSM-specific properties

Feature.osm_type

"node", "way" or "relation"

Feature.id

The feature’s numeric OSM identifier. IDs are unique only within the feature type (which means a node and a way may have the same ID). Always 0 if this feature is an anonymous node, otherwise non-zero.

Feature.tags

The feature’s Tags (key/value pairs that describe its properties).

Feature.is_node

True if this feature is a node, otherwise False.

Feature.is_way

True if this feature is a way (linear or area), otherwise False.

Feature.is_relation

True if this feature is a relation (area or non-area), otherwise False.

Feature.is_area

True if this feature is a way or relation that represents an area, otherwise False.

Feature.nodes

The nodes of a way, or an empty set if this feature is a node or relation.

Feature.members

The members of a relation, or an empty set if this feature is a node or way. Features returned from this set (or a subset) have a role property with a value other than None.

Feature.parents

The relations that have this feature as a member, as well as the ways to which a node feature belongs (Use node.parents.relations to obtain just the relations to which a node belongs).

Feature.role

The role of this feature if it was returned via a member set (an empty string if this feature has no explicit role within its parent relation), or None for a Feature that was not returned via a member set.

Geometric properties

Feature.bounds

The bounding Box of this feature.

Feature.x

The x-coordinate of a node, or the horizontal midpoint of the bounds of a way or relation (GeoDesk Mercator projection)

Feature.y

The y-coordinate of a node, or the vertical midpoint of the bounds of a way or relation (GeoDesk Mercator projection)

Feature.lon

x in degrees longitude (WGS-84)

Feature.lat

y in degrees latitude (WGS-84)

Feature.centroid

The feature’s calculated centroid (Coordinate)

Feature.shape

The Shapely Geometry of this feature:

Point for a node
LineString or Polygon for a way
Polygon, GeometryCollection, MultiPoint, MultiLineString or MultiPolygon for a relation

Coordinates are in Mercator projection.

Feature.area

The calculated area (in square meters) if this feature is polygonal, otherwise 0.

Feature.length

The calculated length (in meters) if this feature is lineal, or its circumference if it is polygonal, otherwise 0.

Formatting

To aid import into GIS applications, features can be converted into different representations. You can also visualize a feature on a map. See Formats and Maps to learn how output can be customized.

Feature.geojson

The GeoJSON representation of this feature (Formatter)

Feature.wkt

The feature’s geometry as Well-Known Text (Formatter)

Feature.map

A Map displaying this feature.

You can add() more features, save() it or show() it in a browser.

# Mark a route on a map, highlight bike paths in green
route_map = route.map
route_map.add(route.members("w[highway=cycleway]", color="green")
route_map.show()

Tag methods

Feature.str(key)

Returns the value of the given tag key as a string, or an empty string if this feature doesn’t have the requested tag.

Feature.num(key)

Returns the value of the given tag as an int or float, or 0 if this feature doesn’t have the requested tag.

`Tags` objects

Iterating a Tags object yields key-value tuples:

>>> for key, value in street.tags:
...     print (f'{key}={value}')
('highway', 'residential')
('name', 'Rue des Poulets')
('maxspeed', 30)

Anonymous nodes

An anonymous node has no tags and does not belong to any relations — it merely serves to define the geometry of a way. By default, feature libraries omit the IDs of such nodes to save space, in which case id is 0.

Anonymous nodes can only be obtained by nodes; they are not part of any other feature sets. The parents property of an anonymous node contains the ways to which this node belongs (always at least one).

Every anonymous node in a GOL has a unique location. If two or more nodes share the exact latitude and longitude, the untagged ones are tagged geodesk:duplicate=yes and retain their ID.