API Reference¶
Overpass API¶
-
class
overpy.
Overpass
(read_chunk_size=None, url=None, xml_parser=2, max_retry_count=None, retry_timeout=None)[source]¶ Class to access the Overpass API
Variables: - default_max_retry_count – Global max number of retries (Default: 0)
- default_retry_timeout – Global time to wait between tries (Default: 1.0s)
-
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:
-
parse_xml
(data, encoding='utf-8', parser=None)[source]¶ Parameters: - data (String or Bytes) – Raw XML Data
- encoding (String) – Encoding to decode byte string
Returns: Result object
Return type:
-
query
(query)[source]¶ Query the Overpass API
Parameters: query (String|Bytes) – The query string in Overpass QL Returns: The parsed result 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
-
areas
¶ Alias for get_elements() but filter the result by Area
Parameters: area_id (Integer) – The Id of the area Returns: List of elements
-
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:
-
classmethod
from_xml
(data, api=None, parser=None)[source]¶ Create a new instance and load data from xml data or object.
Note
If parser is set to None, the functions tries to find the best parse. By default the SAX parser is chosen if a string is provided as data. The parser is set to DOM if an xml.etree.ElementTree.Element is provided as data value.
Parameters: - data (str | xml.etree.ElementTree.Element) – Root element
- api (Overpass) – The instance to query additional information if required.
- parser (Integer | None) – Specify the parser to use(DOM or SAX)(Default: None = autodetect, defaults to SAX)
Returns: New instance of Result object
Return type:
-
get_area
(area_id, resolve_missing=False)[source]¶ Get an area by its ID.
Parameters: - area_id (Integer) – The area ID
- resolve_missing – Query the Overpass API if the area is missing in the result set.
Returns: The area
Return type: Raises: - overpy.exception.DataIncomplete – The requested way is not available in the result cache.
- overpy.exception.DataIncomplete – If resolve_missing is True and the area can’t be resolved.
-
get_areas
(area_id=None, **kwargs)[source]¶ Alias for get_elements() but filter the result by Area
Parameters: area_id (Integer) – The Id of the area Returns: List of elements
-
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: 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: 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: 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.
Area
(area_id=None, **kwargs)[source]¶ Class to represent an element of type area
-
classmethod
from_json
(data, result=None)[source]¶ Create new Area element from JSON data
Parameters: - data (Dict) – Element data from JSON
- result (overpy.Result) – The result this element belongs to
Returns: New instance of Way
Return type: 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: 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
-
id
= None¶ The id of the way
-
classmethod
-
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: - data (Dict) – Element data from JSON
- result (overpy.Result) – The result this element belongs to
Returns: New instance of Node
Return type: 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: Raises: - overpy.exception.ElementDataWrongType – If name of the xml child node doesn’t match
- ValueError – If a tag doesn’t have a name
-
classmethod
-
class
overpy.
Relation
(rel_id=None, center_lat=None, center_lon=None, members=None, **kwargs)[source]¶ Class to represent an element of type relation
-
center_lat
= None¶ The lat/lon of the center of the way (optional depending on query)
-
classmethod
from_json
(data, result=None)[source]¶ Create new Relation element from JSON data
Parameters: - data (Dict) – Element data from JSON
- result (overpy.Result) – The result this element belongs to
Returns: New instance of Relation
Return type: 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: 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, center_lat=None, center_lon=None, node_ids=None, **kwargs)[source]¶ Class to represent an element of type way
-
center_lat
= None¶ The lat/lon of the center of the way (optional depending on query)
-
classmethod
from_json
(data, result=None)[source]¶ Create new Way element from JSON data
Parameters: - data (Dict) – Element data from JSON
- result (overpy.Result) – The result this element belongs to
Returns: New instance of Way
Return type: 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: 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
-
nodes
¶ List of nodes associated with the way.
-
Relation Members¶
-
class
overpy.
RelationMember
(attributes=None, geometry=None, 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: 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: Raises: overpy.exception.ElementDataWrongType – If name of the xml child node doesn’t match
-
classmethod
-
class
overpy.
RelationArea
(attributes=None, geometry=None, ref=None, role=None, result=None)[source]¶
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.
MaxRetriesReached
(retry_count, exceptions)[source]¶ Raised if max retries reached and the Overpass server didn’t respond with a result.
-
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.
OverpassError
(msg=None)[source]¶ Base exception to report errors if the response returns a remark tag or element.
Note
If you are not sure which of the subexceptions you should use, use this one and try to parse the message.
For more information have a look at https://github.com/DinoTools/python-overpy/issues/62
Parameters: msg (str) – The message from the remark tag or element -
msg
= None¶ The message from the remark tag or element
-
-
exception
overpy.exception.
OverpassGatewayTimeout
[source]¶ Raised if load of the Overpass API service is too high and it can’t handle the request.
-
exception
overpy.exception.
OverpassRuntimeError
(msg=None)[source]¶ Raised if the server returns a remark-tag(xml) or remark element(json) with a message starting with ‘runtime error:’.
-
exception
overpy.exception.
OverpassRuntimeRemark
(msg=None)[source]¶ Raised if the server returns a remark-tag(xml) or remark element(json) with a message starting with ‘runtime remark:’.
-
exception
overpy.exception.
OverpassTooManyRequests
[source]¶ Raised if the Overpass API service returns a 429 status code.
-
exception
overpy.exception.
OverpassUnknownContentType
(content_type)[source]¶ Raised if the reported content type isn’t handled by OverPy.
Parameters: content_type (None or String) – The reported content type
Helper¶
-
overpy.helper.
get_intersection
(street1, street2, areacode, api=None)[source]¶ Retrieve intersection of two streets in a given bounding area
Parameters: - api (overpy.Overpass) – First street of intersection
- street1 (String) – Name of first street of intersection
- street2 (String) – Name of second street of intersection
- areacode (String) – The OSM id of the bounding area
Returns: List of intersections
Raises: overpy.exception.OverPyException – If something bad happens.
-
overpy.helper.
get_street
(street, areacode, api=None)[source]¶ Retrieve streets in a given bounding area
Parameters: - api (overpy.Overpass) – First street of intersection
- street (String) – Name of street
- areacode (String) – The OSM id of the bounding area
Returns: Parsed result
Raises: overpy.exception.OverPyException – If something bad happens.