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_read_chunk_size – Max size of each chunk read from the server response
default_retry_timeout – Global time to wait between tries (Default: 1.0s)
default_url – Default URL of the Overpass server
- Parameters
read_chunk_size (
Optional
[int
]) –url (
Optional
[str
]) –xml_parser (
int
) –max_retry_count (
Optional
[int
]) –retry_timeout (
Optional
[float
]) –
- parse_json(data, encoding='utf-8')[source]¶
Parse raw response from Overpass service.
- Parameters
data (
Union
[bytes
,str
]) – Raw JSON Dataencoding (
str
) – Encoding to decode byte string
- Return type
- Returns
Result object
Result¶
- class overpy.Result(elements=None, api=None)[source]¶
Class to handle the result.
- property areas: List[Area]¶
Alias for get_elements() but filter the result by Area
- Parameters
area_id (
Optional
[int
]) – 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 (
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.
- 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 (
Union
[str
,Element
]) – Root elementapi (
Optional
[Overpass
]) – The instance to query additional information if required.parser (
Optional
[int
]) – Specify the parser to use(DOM or SAX)(Default: None = autodetect, defaults to SAX)
- Return type
- Returns
New instance of Result object
- get_area(area_id, resolve_missing=False)[source]¶
Get an area by its ID.
- Parameters
area_id (
int
) – The area IDresolve_missing (
bool
) – Query the Overpass API if the area is missing in the result set.
- Return type
- Returns
The area
- 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)[source]¶
Alias for get_elements() but filter the result by Area
- Parameters
area_id (
Optional
[int
]) – The Id of the area- Return type
List
[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 (
Type
[TypeVar
(ElementTypeVar
, bound= Element)]) –elem_id (
Optional
[int
]) – ID of the object
- Return type
List
[TypeVar
(ElementTypeVar
, bound= Element)]- Returns
List of available elements
- get_node(node_id, resolve_missing=False)[source]¶
Get a node by its ID.
- Parameters
node_id (
int
) – The node IDresolve_missing (
bool
) – Query the Overpass API if the node is missing in the result set.
- Return type
- Returns
The 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)[source]¶
Alias for get_elements() but filter the result by Node()
- Parameters
node_id (Integer) – The Id of the node
- Return type
List
[Node
]- Returns
List of elements
- get_relation(rel_id, resolve_missing=False)[source]¶
Get a relation by its ID.
- Parameters
rel_id (
int
) – The relation IDresolve_missing (
bool
) – Query the Overpass API if the relation is missing in the result set.
- Return type
- Returns
The 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)[source]¶
Alias for get_elements() but filter the result by Relation
- Parameters
rel_id (
Optional
[int
]) – Id of the relation- Return type
List
[Relation
]- Returns
List of elements
- get_way(way_id, resolve_missing=False)[source]¶
Get a way by its ID.
- Parameters
way_id (
int
) – The way IDresolve_missing (
bool
) – Query the Overpass API if the way is missing in the result set.
- Return type
- Returns
The 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)[source]¶
Alias for get_elements() but filter the result by Way
- Parameters
way_id (
Optional
[int
]) – The Id of the way- Return type
List
[Way
]- Returns
List of elements
- property nodes: List[Node]¶
Alias for get_elements() but filter the result by Node()
- Parameters
node_id (Integer) – The Id of the node
- Returns
List of elements
Elements¶
- class overpy.Element(attributes=None, result=None, tags=None)[source]¶
Base element
- Parameters
attributes (
Optional
[dict
]) –result (
Optional
[Result
]) –tags (
Optional
[Dict
]) –
- classmethod from_json(data, result=None)[source]¶
Create new Element() from json data :type data:
dict
:param data: :type result:Optional
[Result
] :param result: :rtype:TypeVar
(ElementTypeVar
, bound= Element) :return:
- class overpy.Area(area_id=None, **kwargs)[source]¶
Class to represent an element of type area
- Parameters
area_id (
Optional
[int
]) –
- classmethod from_json(data, result=None)[source]¶
Create new Area element from JSON data
- Parameters
data (
dict
) – Element data from JSONresult (
Optional
[Result
]) – The result this element belongs to
- Return type
- Returns
New instance of 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 (
Element
) – XML node to be parsedresult (
Optional
[Result
]) – The result this node belongs to
- Return type
- Returns
New Way oject
- 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:
int
¶ The id of the way
- class overpy.Node(node_id=None, lat=None, lon=None, **kwargs)[source]¶
Class to represent an element of type node
- Parameters
node_id (
Optional
[int
]) –lat (
Union
[Decimal
,float
,None
]) –lon (
Union
[Decimal
,float
,None
]) –
- classmethod from_json(data, result=None)[source]¶
Create new Node element from JSON data
- Parameters
data (
dict
) – Element data from JSONresult (
Optional
[Result
]) – The result this element belongs to
- Return type
- Returns
New instance of 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 (
Element
) – XML node to be parsedresult (
Optional
[Result
]) – The result this node belongs to
- Return type
- Returns
New Way oject
- 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, center_lat=None, center_lon=None, members=None, **kwargs)[source]¶
Class to represent an element of type relation
- Parameters
rel_id (
Optional
[int
]) –center_lat (
Union
[Decimal
,float
,None
]) –center_lon (
Union
[Decimal
,float
,None
]) –members (
Optional
[List
[RelationMember
]]) –
- center_lat¶
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 JSONresult (
Optional
[Result
]) – The result this element belongs to
- Return type
- Returns
New instance of 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 (
Element
) – XML node to be parsedresult (
Optional
[Result
]) – The result this node belongs to
- Return type
- Returns
New Way oject
- 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
- Parameters
way_id (
Optional
[int
]) –center_lat (
Union
[Decimal
,float
,None
]) –center_lon (
Union
[Decimal
,float
,None
]) –node_ids (
Union
[List
[int
],Tuple
[int
],None
]) –
- center_lat¶
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 JSONresult (
Optional
[Result
]) – The result this element belongs to
- Return type
- Returns
New instance of 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 (
Element
) – XML node to be parsedresult (
Optional
[Result
]) – The result this node belongs to
- Return type
- Returns
New Way oject
- 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 (
bool
) – Try to resolve missing nodes.- Return type
List
[Node
]- Returns
List of nodes
- 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:
int
¶ The id of 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.
- Parameters
attributes (
Optional
[dict
]) –geometry (
Optional
[List
[RelationWayGeometryValue
]]) –ref (
Optional
[int
]) –role (
Optional
[str
]) –result (
Optional
[Result
]) –
- classmethod from_json(data, result=None)[source]¶
Create new RelationMember element from JSON data
- Parameters
data (
dict
) – Element data from JSONresult (
Optional
[Result
]) – The result this element belongs to
- Return type
- Returns
New instance of 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 (
Element
) – XML node to be parsedresult (
Optional
[Result
]) – The result this element belongs to
- Return type
- Returns
New relation member oject
- Raises
overpy.exception.ElementDataWrongType – If name of the xml child node doesn’t match
- class overpy.RelationArea(attributes=None, geometry=None, ref=None, role=None, result=None)[source]¶
- Parameters
attributes (
Optional
[dict
]) –geometry (
Optional
[List
[RelationWayGeometryValue
]]) –ref (
Optional
[int
]) –role (
Optional
[str
]) –result (
Optional
[Result
]) –
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¶
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
street1 (
str
) – Name of first street of intersectionstreet2 (
str
) – Name of second street of intersectionareacode (
str
) – The OSM id of the bounding areaapi (
Optional
[Overpass
]) – API object to fetch missing elements
- Return type
List
[Node
]- 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
street (
str
) – Name of streetareacode (
str
) – The OSM id of the bounding areaapi (
Optional
[Overpass
]) – API object to fetch missing elements
- Return type
- Returns
Parsed result
- Raises
overpy.exception.OverPyException – If something bad happens.