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_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_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. |