API Reference¶
Overpass API¶
-
class
overpy.
Overpass
(read_chunk_size=None, url=None, xml_parser=2)[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
-
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
-
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
-
property
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=2)[source]¶ Create a new instance and load data from xml object.
-
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
-
property
nodes
¶ Alias for get_elements() but filter the result by Node()
- Parameters
node_id (Integer) – The Id of the node
- Returns
List of elements
-
property
relations
¶ Alias for get_elements() but filter the result by Relation
- Parameters
rel_id (Integer) – Id of the relation
- Returns
List of elements
-
property
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
-
property
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.
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 too high and it can’t handle the request.
-
exception
overpy.exception.
OverpassTooManyRequests
[source]¶ Raised if the Overpass API service returns a 429 status code.
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.