API Reference¶
Overpass API¶
- class overpy.Overpass(read_chunk_size=None)[source]¶
Class to access the Overpass API
- parse_json(data, encoding='utf-8')[source]¶
Parse raw response from Overpass service.
Parameters: - data (String or Bytes) – Raw JSON Data
- encoding (String) – Encoding to decode byte string
Returns: Result object
Return type: overpy.Result
Result¶
- class overpy.Result(elements=None, api=None)[source]¶
Class to handle the result.
- append(element)[source]¶
Append a new element to the result.
Parameters: element (overpy.Element) – The element to append
- expand(other)[source]¶
Add all elements from an other result to the list of elements of this result object.
It is used by the auto resolve feature.
Parameters: other (overpy.Result) – Expand the result with the elements from this result. Raises ValueError: If provided parameter is not instance of overpy.Result
- classmethod from_json(data, api=None)[source]¶
Create a new instance and load data from json object.
Parameters: - data (Dict) – JSON data returned by the Overpass API
- api (overpy.Overpass) –
Returns: New instance of Result object
Return type: overpy.Result
- classmethod from_xml(root, api=None)[source]¶
Create a new instance and load data from xml object.
Parameters: - data (xml.etree.ElementTree.Element) – Root element
- api (Overpass) –
Returns: New instance of Result object
Return type: Result
- get_elements(filter_cls, elem_id=None)[source]¶
Get a list of elements from the result and filter the element type by a class.
Parameters: - filter_cls –
- elem_id (Integer) – ID of the object
Returns: List of available elements
Return type: List
- get_node(node_id, resolve_missing=False)[source]¶
Get a node by its ID.
Parameters: - node_id (Integer) – The node ID
- resolve_missing – Query the Overpass API if the node is missing in the result set.
Returns: The node
Return type: overpy.Node
Raises: - overpy.exception.DataIncomplete – At least one referenced node is not available in the result cache.
- overpy.exception.DataIncomplete – If resolve_missing is True and at least one node can’t be resolved.
- get_nodes(node_id=None, **kwargs)[source]¶
Alias for get_elements() but filter the result by Node()
Parameters: node_id (Integer) – The Id of the node Returns: List of elements
- get_relation(rel_id, resolve_missing=False)[source]¶
Get a relation by its ID.
Parameters: - rel_id (Integer) – The relation ID
- resolve_missing – Query the Overpass API if the relation is missing in the result set.
Returns: The relation
Return type: overpy.Relation
Raises: - overpy.exception.DataIncomplete – The requested relation is not available in the result cache.
- overpy.exception.DataIncomplete – If resolve_missing is True and the relation can’t be resolved.
- get_relations(rel_id=None, **kwargs)[source]¶
Alias for get_elements() but filter the result by Relation
Parameters: rel_id (Integer) – Id of the relation Returns: List of elements
- get_way(way_id, resolve_missing=False)[source]¶
Get a way by its ID.
Parameters: - way_id (Integer) – The way ID
- resolve_missing – Query the Overpass API if the way is missing in the result set.
Returns: The way
Return type: overpy.Way
Raises: - overpy.exception.DataIncomplete – The requested way is not available in the result cache.
- overpy.exception.DataIncomplete – If resolve_missing is True and the way can’t be resolved.
- get_ways(way_id=None, **kwargs)[source]¶
Alias for get_elements() but filter the result by Way
Parameters: way_id (Integer) – The Id of the way Returns: List of elements
- nodes¶
Alias for get_elements() but filter the result by Node()
Parameters: node_id (Integer) – The Id of the node Returns: List of elements
- relations¶
Alias for get_elements() but filter the result by Relation
Parameters: rel_id (Integer) – Id of the relation Returns: List of elements
- ways¶
Alias for get_elements() but filter the result by Way
Parameters: way_id (Integer) – The Id of the way Returns: List of elements
Elements¶
- class overpy.Node(node_id=None, lat=None, lon=None, **kwargs)[source]¶
Class to represent an element of type node
- classmethod from_json(data, result=None)[source]¶
Create new Node element from JSON data
Parameters: - child (Dict) – Element data from JSON
- result (overpy.Result) – The result this element belongs to
Returns: New instance of Node
Return type: overpy.Node
Raises overpy.exception.ElementDataWrongType: If type value of the passed JSON data does not match.
- classmethod from_xml(child, result=None)[source]¶
Create new way element from XML data
Parameters: - child (xml.etree.ElementTree.Element) – XML node to be parsed
- result (overpy.Result) – The result this node belongs to
Returns: New Way oject
Return type: overpy.Node
Raises: - overpy.exception.ElementDataWrongType – If name of the xml child node doesn’t match
- ValueError – If a tag doesn’t have a name
- class overpy.Relation(rel_id=None, members=None, **kwargs)[source]¶
Class to represent an element of type relation
- classmethod from_json(data, result=None)[source]¶
Create new Relation element from JSON data
Parameters: - child (Dict) – Element data from JSON
- result (overpy.Result) – The result this element belongs to
Returns: New instance of Relation
Return type: overpy.Relation
Raises overpy.exception.ElementDataWrongType: If type value of the passed JSON data does not match.
- classmethod from_xml(child, result=None)[source]¶
Create new way element from XML data
Parameters: - child (xml.etree.ElementTree.Element) – XML node to be parsed
- result (overpy.Result) – The result this node belongs to
Returns: New Way oject
Return type: overpy.Relation
Raises: - overpy.exception.ElementDataWrongType – If name of the xml child node doesn’t match
- ValueError – If a tag doesn’t have a name
- class overpy.Way(way_id=None, node_ids=None, **kwargs)[source]¶
Class to represent an element of type way
- classmethod from_json(data, result=None)[source]¶
Create new Way element from JSON data
Parameters: - child (Dict) – Element data from JSON
- result (overpy.Result) – The result this element belongs to
Returns: New instance of Way
Return type: overpy.Way
Raises overpy.exception.ElementDataWrongType: If type value of the passed JSON data does not match.
- classmethod from_xml(child, result=None)[source]¶
Create new way element from XML data
Parameters: - child (xml.etree.ElementTree.Element) – XML node to be parsed
- result (overpy.Result) – The result this node belongs to
Returns: New Way oject
Return type: overpy.Way
Raises: - overpy.exception.ElementDataWrongType – If name of the xml child node doesn’t match
- ValueError – If the ref attribute of the xml node is not provided
- ValueError – If a tag doesn’t have a name
- get_nodes(resolve_missing=False)[source]¶
Get the nodes defining the geometry of the way
Parameters: resolve_missing (Boolean) – Try to resolve missing nodes.
Returns: List of nodes
Return type: List of overpy.Node
Raises: - overpy.exception.DataIncomplete – At least one referenced node is not available in the result cache.
- overpy.exception.DataIncomplete – If resolve_missing is True and at least one node can’t be resolved.
- id = None¶
The id of the way
Relation Members¶
- class overpy.RelationMember(ref=None, role=None, result=None)[source]¶
Base class to represent a member of a relation.
- classmethod from_json(data, result=None)[source]¶
Create new RelationMember element from JSON data
Parameters: - child (Dict) – Element data from JSON
- result (overpy.Result) – The result this element belongs to
Returns: New instance of RelationMember
Return type: overpy.RelationMember
Raises overpy.exception.ElementDataWrongType: If type value of the passed JSON data does not match.
- classmethod from_xml(child, result=None)[source]¶
Create new RelationMember from XML data
Parameters: - child (xml.etree.ElementTree.Element) – XML node to be parsed
- result (overpy.Result) – The result this element belongs to
Returns: New relation member oject
Return type: overpy.RelationMember
Raises overpy.exception.ElementDataWrongType: If name of the xml child node doesn’t match
Exceptions¶
- exception overpy.exception.DataIncomplete(*args, **kwargs)[source]¶
Raised if the requested data isn’t available in the result. Try to improve the query or to resolve the missing data.
- exception overpy.exception.ElementDataWrongType(type_expected, type_provided=None)[source]¶
Raised if the provided element does not match the expected type.
Parameters: - type_expected (String) – The expected element type
- type_provided (String|None) – The provided element type
- exception overpy.exception.OverpassBadRequest(query, msgs=None)[source]¶
Raised if the Overpass API service returns a syntax error.
Parameters: - query (Bytes) – The encoded query how it was send to the server
- msgs (List) – List of error messages
- exception overpy.exception.OverpassGatewayTimeout[source]¶
Raised if load of the Overpass API service is to high and it can’t handle the request.
- exception overpy.exception.OverpassTooManyRequests[source]¶
Raised if the Overpass API service returns a 429 status code.