# `osm` - Basic Datatypes

The `osm` submodule contains definitions of the basic data types used throughout the library.

## Native OSM Objects

Native OSM object classes are lightwight wrappers around the osmium OSM data classes. They are immutable and generally bound to the lifetime of the buffer they are saved in.

There are five classes representing the basic OSM entities.

class osmium.osm.OSMObject

  This is the base class for all OSM entity classes below and contains all common attributes.

  tags: TagList

    (read-only) List of tags describing the object. See `osmium.osm.TagList`.

  property id: int

    (read-only) OSM id of the object.

  property deleted: bool

    (read-only) True if the object is no longer visible.

  property visible: bool

    (read-only) True if the object is visible.

  property version: int

    (read-only) Version number of the object.

  property changeset: int

    (read-only) Id of changeset where this version of the object was created.

  property uid: int

    (read-only) Id of the user that created this version of the object. Only this ID uniquely identifies users.

  property timestamp: datetime

    (read-only) Date when this version has been created, returned as a `datetime.datetime`.

  property user: str

    (read-only) Name of the user that created this version. Be aware that user names can change, so that the same user ID may appear with different names and vice versa.

  positive_id() → int

    Get the absolute value of the id of this object.

  user_is_anonymous() → bool

    Check if the user is anonymous. If true, the uid does not uniquely identify a single user but only the group of all anonymous users in general.

class osmium.osm.Node(cnode: cosm.COSMNode)

  Represents a single OSM node. It inherits all properties from OSMObjects and adds a single extra attribute: the location.

  replace(**kwargs: Any) → Node

    Create a mutable node replacing the properties given in the named parameters. The properties may be any of the properties of OSMObject or Node.

    Note that this function only creates a shallow copy per default. It is still bound to the scope of the original object. To create a full copy use: `node.replace(tags=dict(node.tags))`

  property location: Location

    The geographic coordinates of the node. See `osmium.osm.Location`.

class osmium.osm.Way(cway: cosm.COSMWay)

  Represents an OSM way. It inherits the attributes from OSMObject and adds an ordered list of nodes that describes the way.

  replace(**kwargs: Any) → Way

    Create a mutable way replacing the properties given in the named parameters. The properties may be any of the properties of OSMObject or Way.

    Note that this function only creates a shallow copy per default. It is still bound to the scope of the original object. To create a full copy use: `way.replace(tags=dict(way.tags), nodes=list(way.nodes))`

  property nodes: WayNodeList

    (read-only) Ordered list of nodes. See `osmium.osm.WayNodeList`.

  is_closed() → bool

    True if the start and end node are the same (synonym for `ends_have_same_id`).

  ends_have_same_id() → bool

    True if the start and end node are exactly the same.

  ends_have_same_location() → bool

    True if the start and end node of the way are at the same location. Expects that the coordinates of the way nodes have been loaded (see `osmium.SimpleHandler.apply_buffer()` and `osmium.SimpleHandler.apply_file()`). If the locations are not present then the function returns always true.

class osmium.osm.Relation(crelation: cosm.COSMRelation)

  Represents a OSM relation. It inherits the attributes from OSMObject and adds an ordered list of members.

  members: RelationMemberList

    (read-only) Ordered list of relation members. See `osmium.osm.RelationMemberList`.

  replace(**kwargs: Any) → Relation

    Create a mutable relation replacing the properties given in the named parameters. The properties may be any of the properties of OSMObject or Relation.

    Note that this function only creates a shallow copy per default. It is still bound to the scope of the original object. To create a full copy use: `rel.replace(tags=dict(rel.tags), members=list(rel.members))`

class osmium.osm.Area(carea: cosm.COSMArea)

  Areas are a special kind of meta-object representing a polygon. They can either be derived from closed ways or from relations that represent multipolygons. They also inherit the attributes of OSMObjects and in addition contain polygon geometries. Areas have their own unique id space. This is computed as the OSM id times 2 and for relations 1 is added.

  from_way() → bool

    Return true if the area was created from a way, false if it was created from a relation of multipolygon type.

  orig_id() → int

    Compute the original OSM id of this object. Note that this is not necessarily unique because the object might be a way or relation which have an overlapping id space.

  is_multipolygon() → bool

    Return true if this area is a true multipolygon, i.e. it consists of multiple outer rings.

  num_rings() → Tuple[int, int]

    Return a tuple with the number of outer rings and inner rings.

    This function goes through all rings to count them.

  outer_rings() → OuterRingIterator

    Return an iterator over all outer rings of the multipolygon.

  inner_rings(oring: OuterRing) → InnerRingIterator

    Return an iterator over all inner rings of the multipolygon.

class osmium.osm.Changeset(carea: cosm.COSMChangeset)

  A changeset description.

  tags: TagList
  property id: int

    (read-only) Unique ID of the changeset.

  property uid: int

    (read-only) User ID of the changeset creator.

  property created_at: datetime

    (read-only) Timestamp when the changeset was first opened.

  property closed_at: datetime

    (read-only) Timestamp when the changeset was finalized. May be `None` when the changeset is still open.

  property open: bool

    (read-only) True when the changeset is still open.

  property num_changes: int

    (read-only) The total number of objects changed in this Changeset.

  property user: str

    (read-only) Name of the user that created the changeset. Be aware that user names can change, so that the same user ID may appear with different names and vice versa.

  property bounds: Box

    (read-only) The bounding box of the area that was edited.

  user_is_anonymous() → bool

    Check if the user anonymous. If true, the uid does not uniquely identify a single user but only the group of all anonymous users in general.

## Mutable OSM Objects

The objects in `osmium.osm.mutable` are Python versions of the native OSM objects that can be modified. You can use these classes as a base class for your own objects or to modify objects read from a file.

class osmium.osm.mutable.OSMObject(base: OSMObjectLike | None = None, id: int | None = None, version: int | None = None, visible: bool | None = None, changeset: int | None = None, timestamp: datetime | None = None, uid: int | None = None, tags: TagSequence | None = None, user: str | None = None)

  Mutable version of `osmium.osm.OSMObject`. It exposes the following attributes `id`, `version`, `visible`, `changeset`, `timestamp`, `uid` and `tags`. Timestamps may be strings or datetime objects. Tags can be an osmium.osm.TagList, a dict-like object or a list of tuples, where each tuple contains a (key value) string pair.

  If the `base` parameter is given in the constructor, then the object will be initialised first from the attributes of this base object.

class osmium.osm.mutable.Node(base: NodeLike | None = None, location: LocationLike | None = None, **attrs: Any)

  The mutable version of `osmium.osm.Node`. It inherits all attributes from osmium.osm.mutable.OSMObject and adds a location attribute. This may either be an osmium.osm.Location or a tuple of lon/lat coordinates.

class osmium.osm.mutable.Way(base: WayLike | None = None, nodes: NodeSequence | None = None, **attrs: Any)

  The mutable version of `osmium.osm.Way`. It inherits all attributes from osmium.osm.mutable.OSMObject and adds a nodes attribute. This may either be and `osmium.osm.NodeList` or a list consisting of `osmium.osm.NodeRef` or simple node ids.

class osmium.osm.mutable.Relation(base: RelationLike | None = None, members: MemberSequence | None = None, **attrs: Any)

  The mutable version of `osmium.osm.Relation`. It inherits all attributes from osmium.osm.mutable.OSMObject and adds a members attribute. This may either be an `osmium.osm.RelationMemberList` or a list consisting of `osmium.osm.RelationMember` or tuples of (type, id, role). The member type should be a single character ‘n’, ‘w’ or ‘r’.

## Node Reference Lists

Line geometries in OSM are simply a sequence of nodes. To simplify processing osmium returns such node sequences using a special datatype that contains a reference to the node id and also the location geometry. The latter is only valid if the node locations have been cached by a location handler.

class osmium.osm.NodeRef(location: Location, ref: int)

  A reference to a OSM node that also caches the nodes location.

  property x: int

    (read-only) X coordinate (longitude) as a fixed-point integer.

  property y: int

    (read-only) Y coordinate (latitude) as a fixed-point integer.

  property lat: float

    (read-only) Latitude (y coordinate) as floating point number.

  property lon: float

    (read-only) Longitude (x coordinate) as floating point number.

class osmium.osm.NodeRefList(parent: cosm.BufferProxyProtocol, ref_list: cosm.NodeRefList)

  A list of node references, implemented as an immutable sequence of `osmium.osm.NodeRef`. This class is normally not used directly, use one of its subclasses instead.

  is_closed() → bool

    True if the start and end node are the same (synonym for `ends_have_same_id`).

  ends_have_same_id() → bool

    True if the start and end node are exactly the same.

  ends_have_same_location() → bool

    True if the start and end node of the way are at the same location. ” Expects that the coordinates of the way nodes have been loaded (see `osmium.SimpleHandler.apply_buffer()` and `osmium.SimpleHandler.apply_file()`). If the locations are not present then the function returns always true.

class osmium.osm.WayNodeList(parent: cosm.BufferProxyProtocol, ref_list: cosm.NodeRefList)

  List of nodes in a way. For its members see `osmium.osm.NodeRefList`.

class osmium.osm.OuterRing(parent: cosm.BufferProxyProtocol, ref_list: cosm.NodeRefList)

  List of nodes in an outer ring. For its members see `osmium.osm.NodeRefList`.

class osmium.osm.InnerRing(parent: cosm.BufferProxyProtocol, ref_list: cosm.NodeRefList)

  List of nodes in an inner ring. ” For its members see `osmium.osm.NodeRefList`.

## Relation member lists

class osmium.osm.RelationMember(ref: int, mtype: str, role: str)

  Single member of a relation.

  ref: int

    OSM ID of the object. Only unique within the type.

  type: str

    Type of object referenced, a node, way or relation.

  role: str

    The role of the member within the relation, a free-text string. If no role is set then the string is empty.

class osmium.osm.RelationMemberList(parent: cosm.COSMRelation)

  An immutable sequence of relation members “`osmium.osm.RelationMember`.

## Tag lists

class osmium.osm.Tag(k: str, v: str)

  A single OSM tag.

  k: str

    Tag key

  v: str

    Tag value

class osmium.osm.TagList(parent: cosm.TagContainerProtocol)

  A fixed list of tags. The list is exported as an unmutable, dictionary-like object where the keys are tag strings and the items are `osmium.osm.Tag`.

  get(key: str, default: str | None = None) → str | None

    Return the value for the given key. or ‘value’ if the key does not exist in the list.

## Geometry Attributes

class osmium.osm.Box

  A bounding box around a geographic area. It is defined by an `osmium.osm.Location` for the bottem-left corner and an `osmium.osm.Location` for the top-right corner. Those locations may be invalid in which case the box is considered invalid, too.

  property bottom_left

    (read-only) Bottom-left corner of the bounding box.

  contains(self: osmium.osm._osm.Box, location: osmium::Location) → bool

    Check if the given location is inside the box.

  extend(*args, **kwargs)

    Overloaded function.

    1. extend(self: osmium.osm._osm.Box, location: osmium::Location) -> osmium.osm._osm.Box

    Extend the box to include the given location. If the location is invalid the box remains unchanged. If the box is invalid, it will contain only the location after the operation. Returns a reference to itself.

    2. extend(self: osmium.osm._osm.Box, box: osmium.osm._osm.Box) -> osmium.osm._osm.Box

    Extend the box to include the given box. If the box to be added is invalid the input box remains unchanged. If the input box is invalid, it will become equal to the box that was added. Returns a reference to itself.

  size(self: osmium.osm._osm.Box) → float

    Return the size in square degrees.

  property top_right

    (read-only) Top-right corner of the bounding box.

  valid(self: osmium.osm._osm.Box) → bool

    Check if the box coordinates are defined and with the usual bounds.

class osmium.osm.Location

  A geographic coordinate in WGS84 projection. A location doesn’t necessarily have to be valid.

  property lat

    (read-only) Latitude (y coordinate) as floating point number.Raises an `osmium.InvalidLocationError` when the location is invalid.

  lat_without_check(self: osmium.osm._osm.Location) → float

    Return latitude (y coordinate) without checking if the location is valid.

  property lon

    (read-only) Longitude (x coordinate) as floating point number.Raises an `osmium.InvalidLocationError` when the location is invalid.

  lon_without_check(self: osmium.osm._osm.Location) → float

    Return longitude (x coordinate) without checking if the location is valid.

  valid(self: osmium.osm._osm.Location) → bool

    Check that the location is a valid WGS84 coordinate, i.e. that it is within the usual bounds.

  property x

    (read-only) X coordinate (longitude) as a fixed-point integer.

  property y

    (read-only) Y coordinate (latitude) as a fixed-point integer.