API Reference¶
Bases: OSMClient
An implementation of the OSMClient protocol that accesses the main OSM API for data.
Responses are cached in most cases using the SqliteCache object. A handful of functions are not (mainly searching). Refer to individual functions for more details
Attributes:
| Name | Type | Description |
|---|---|---|
app_name |
str
|
Required argument. The OSM API requires a proper user-agent. The app
name is used with the format |
base_api_url |
str
|
The base of the API (without the final slash). This can be the main OSM API (default) or a mirror with the same end-points. |
cache |
SqliteCache
|
The cache for the responses from the API. |
user_agent |
str
|
The user-agent sent to the API. Used to override the default |
fetch_changeset(id)
¶
Fetches data about a specific changeset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the changeset to fetch. |
required |
Returns:
| Type | Description |
|---|---|
Changeset
|
Data about the requested changeset. |
fetch_changeset_changes(id)
¶
Fetches the changes made by a changeset.
This is returned in the osmChamge XML format, however, it is converted to a regular type internally and returned.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the changeset to fetch the changes for. |
required |
Returns:
| Type | Description |
|---|---|
OsmChange
|
An object containing information about the elements that was changed, modified, or created by the specified changeset. |
fetch_changesets(bbox=None, user=None, display_name=None, closed_after=None, created_after=None, created_before=None, status=ChangesetStatus.ALL, changesets=None, order=None, limit=None)
¶
Searches for and fetches changesets based on various criteria.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bbox
|
BaseGeometry | None = None,
|
Uses the passed geometry to create a minimum bounding box that is used as search area. Note changesets might fall outside the actual boundaries of the geometry. |
None
|
user
|
int | None = None,
|
Filters changesets to those of the user ID provided. |
None
|
display_name
|
str | None = None,
|
Filters changesets based on the provided display name of a user. |
None
|
closed_after
|
datetime | None = None,
|
Filters |
None
|
created_after
|
datetime | None = None,
|
Filters changesets to those created at or after the specified time. |
None
|
created_before
|
datetime | None = None,
|
Filters changesets to those created before the specified time.
Has no effect unless either |
None
|
status
|
ChangesetStatus = ChangesetStatus.ALL,
|
Filters changesets so that only those with the provided status is returned. |
ALL
|
changesets
|
list[int] | None
|
Filters changesets to only those that matches the provided IDs. |
None
|
order
|
Literal['newest', 'oldest'] | None
|
The order of the returned items. The default is "newest". The order can be reversed by setting "oldest", but note that "oldest" can not be used together with time-based filtering. |
None
|
limit
|
int | None
|
Limits the number of responses returned. The default is 100 (set by the API). |
None
|
Returns:
| Type | Description |
|---|---|
list[Changeset]
|
A list of changesets matching the provided search queries. |
Notes
The API end-point for this function is quite messy, especially the time-based filtering. The parameters have different types and names to that of the end-point, but the hope is that this makes it easier to understand and use.
fetch_full_relation(id)
¶
Fetches the relation in addition to information about all the direct members.
Required for certain features such as geometry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the relation to fetch. |
required |
Returns:
| Type | Description |
|---|---|
FullRelation
|
The relation with additional information about direct members. |
fetch_full_way(id)
¶
Fetches the way in addition to information about all the nodes.
Required for certain features such as geometry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the way to fetch. |
required |
Returns:
| Type | Description |
|---|---|
FullWay
|
The way with additional information about nodes. |
fetch_node(id)
¶
Fetches a single node from the API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the node to fetch. |
required |
Returns:
| Type | Description |
|---|---|
Node
|
A Node object containing information about the requested node. |
fetch_node_history(id)
¶
Fetches a every version of a node from the API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the node to fetch the history for. |
required |
Returns:
| Type | Description |
|---|---|
list[Node]
|
A list of all the versions of the specified node. |
fetch_node_version(id, version)
¶
Fetches a single version of a node from the API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the node to fetch |
required |
version
|
int
|
The version of the node to fetch |
required |
Returns:
| Type | Description |
|---|---|
Node
|
The version of the node that was requested. |
fetch_nodes(ids)
¶
Fetches data for multiple nodes at once.
Both IDs and IDs with version specifiers are allowed.
If a node already exists in cache, the node with be read from there rather than fetched from the API. All nodes requested are cached.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids
|
list[int | str]
|
The list of the nodes to fetch. Can either be the pure integer ID
of a node, or with an additional version specifier at the end
(e.g. |
required |
Returns:
| Type | Description |
|---|---|
list[Node]
|
A list of containing the nodes that were requested. |
fetch_note(id)
¶
Fetches details about a specific note
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the note. |
required |
Returns:
| Type | Description |
|---|---|
Note
|
The requested note. |
fetch_notes(bbox, limit=None, closed=None)
¶
Fetches notes from inside side bbox.
Results from this function are never cached.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bbox
|
BaseGeometry
|
Required argument. Used to define the bounds of the elements. Note that the minimum and maximum longitude and latitude of the element is used, not its outer bounds, so notes outide the boundaries may be returned. |
required |
limit
|
int
|
Maximum number of items to return. If not provided the default for the API is used (100 notes). |
None
|
closed
|
int
|
The number of days a note can have been closed for before it is excluded from the results. Passing 0 makes the function only return open notes. If not provided the default for the API is used (7 days). |
None
|
Returns:
| Type | Description |
|---|---|
list[Note]
|
A list with all the notes found capped at the limit. |
fetch_relation(id)
¶
Fetches data about a specific relation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the relation. |
required |
Returns:
| Type | Description |
|---|---|
Relation
|
The relation requested. |
fetch_relation_history(id)
¶
Fetches all versions of a relation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The relation to request the history for. |
required |
Returns:
| Type | Description |
|---|---|
list[Relation]
|
A list containing all the versions of the relation. |
fetch_relation_version(id, version)
¶
Fetches a specific version of a relation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the relation. |
required |
version
|
int
|
The version of the relation to fetch. |
required |
Returns:
| Type | Description |
|---|---|
Relation
|
The version of the relation requested. |
fetch_relations(ids)
¶
Fetches data for multiple relations at once.
Both IDs and IDs with version specifiers are allowed.
If a relation already exists in cache, the relation with be read from there rather than fetched from the API. All relations requested are cached.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids
|
list[int | str]
|
The list of the relations to fetch. Can either be the pure integer ID
of a relation, or with an additional version specifier at the end
(e.g. |
required |
Returns:
| Type | Description |
|---|---|
list[Relation]
|
A list of containing the relations that were requested. |
fetch_relations_for_node(id)
¶
Fetches all the relations that a node is part of.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the node. |
required |
Returns:
| Type | Description |
|---|---|
list[Relation]
|
A list of the relations the node is part of, if any. |
fetch_relations_for_relation(id)
¶
Fetches relations that the relation is a member of (parent relations).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the relation to fetch the relations for. |
required |
Returns:
| Type | Description |
|---|---|
list[Relation]
|
A list with all the parent relations that the relation is a member of, if any. |
fetch_relations_for_way(id)
¶
Fetch relations that the way is a part of.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the way to fetch the relations for. |
required |
Returns:
| Type | Description |
|---|---|
list[Relation]
|
A list of all of the relations the way is a member of, if any. |
fetch_user(id)
¶
Fetches details for a specific user
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the user to fetch |
required |
Returns:
| Type | Description |
|---|---|
User
|
A user object containing information about the user |
fetch_users(ids)
¶
Fetches data for multiple users at once.
If a user already exists in cache, the user with be read from there rather than fetched from the API. All users requested are cached.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids
|
list[int | str]
|
The list of the users to fetch. |
required |
Returns:
| Type | Description |
|---|---|
list[User]
|
A list of containing the users that were requested. |
fetch_way(id)
¶
Fetches information about a way.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the way to fetch. |
required |
Returns:
| Type | Description |
|---|---|
Way
|
Object containing information about the requested way. |
fetch_way_history(id)
¶
Fetches all the version of a way.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the Way to fetch all the versions for. |
required |
Returns:
| Type | Description |
|---|---|
list[Way]
|
A list containing all the versions of the requested way. |
fetch_way_version(id, version)
¶
Fetch a specific version of a way.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
The ID of the way to fetch. |
required |
version
|
int
|
The version of the way to fetch. |
required |
Returns:
| Type | Description |
|---|---|
Way
|
The version of the way that was requested. |
fetch_ways(ids)
¶
Fetches data for multiple ways at once.
Both IDs and IDs with version specifiers are allowed.
If a way already exists in cache, the way with be read from there rather than fetched from the API. All ways requested are cached.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids
|
list[int | str]
|
The list of the ways to fetch. Can either be the pure integer ID
of a way, or with an additional version specifier at the end
(e.g. |
required |
Returns:
| Type | Description |
|---|---|
list[Way]
|
A list of containing the ways that were requested. |