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 Data
encoding (str) – Encoding to decode byte string

Return type

Result

Returns

Result object

parse_xml(data, encoding='utf-8', parser=None)[source]¶

Parameters

data (Union[bytes, str]) – Raw XML Data
encoding (str) – Encoding to decode byte string
parser (Optional[int]) – The XML parser to use

Returns

Result object

query(query)[source]¶

Query the Overpass API

Parameters: query (Union[bytes, str]) – The query string in Overpass QL
Return type: Result
Returns: The parsed result

Result¶

class overpy.Result(elements=None, api=None)[source]¶

Class to handle the result.

Parameters

elements (Optional[List[Union[Area, Node, Relation, Way]]]) –
api (Optional[Overpass]) –

append(element)[source]¶

Append a new element to the result.

Parameters: element (Union[Area, Node, Relation, Way]) – The element to append

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.

Parameters

data (dict) – JSON data returned by the Overpass API
api (Optional[Overpass]) –

Return type

Result

Returns

New instance of Result 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 element
api (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

Result

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 ID
resolve_missing (bool) – Query the Overpass API if the area is missing in the result set.

Return type

Area

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_ids(filter_cls)[source]¶

Get all Element IDs

Parameters: filter_cls (Type[Union[Area, Node, Relation, Way]]) – Only IDs of elements with this type
Return type: List[int]
Returns: List of IDs

get_node(node_id, resolve_missing=False)[source]¶

Get a node by its ID.

Parameters

node_id (int) – The node ID
resolve_missing (bool) – Query the Overpass API if the node is missing in the result set.

Return type

Node

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 ID
resolve_missing (bool) – Query the Overpass API if the relation is missing in the result set.

Return type

Relation

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 ID
resolve_missing (bool) – Query the Overpass API if the way is missing in the result set.

Return type

Way

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

property relations: List[Relation]¶

Alias for get_elements() but filter the result by Relation

Parameters: rel_id (Optional[int]) – Id of the relation
Returns: List of elements

property ways: List[Way]¶

Alias for get_elements() but filter the result by Way

Parameters: way_id (Optional[int]) – The Id of the way
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:

classmethod from_xml(child, result=None)[source]¶

Create new Element() element from XML data

Parameters

child (Element) –
result (Optional[Result]) –

Return type

TypeVar(ElementTypeVar, bound= Element)

classmethod get_center_from_json(data)[source]¶

Get center information from json data

Parameters: data (dict) – json data
Return type: Tuple[Decimal, Decimal]
Returns: tuple with two elements: lat and lon

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 JSON
result (Optional[Result]) – The result this element belongs to

Return type

Area

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 parsed
result (Optional[Result]) – The result this node belongs to

Return type

Area

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 JSON
result (Optional[Result]) – The result this element belongs to

Return type

Node

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 parsed
result (Optional[Result]) – The result this node belongs to

Return type

Node

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 JSON
result (Optional[Result]) – The result this element belongs to

Return type

Relation

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 parsed
result (Optional[Result]) – The result this node belongs to

Return type

Relation

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 JSON
result (Optional[Result]) – The result this element belongs to

Return type

Way

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 parsed
result (Optional[Result]) – The result this node belongs to

Return type

Way

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

property nodes: List[Node]¶: 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.

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 JSON
result (Optional[Result]) – The result this element belongs to

Return type

RelationMember

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 parsed
result (Optional[Result]) – The result this element belongs to

Return type

RelationMember

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]) –

class overpy.RelationNode(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]) –

class overpy.RelationWay(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.OverPyException[source]¶: OverPy base exception

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

exception overpy.exception.OverpassUnknownError(msg=None)[source]¶: Raised if the server returns a remark-tag(xml) or remark element(json) and we are unable to find any reason.

exception overpy.exception.OverpassUnknownHTTPStatusCode(code)[source]¶

Raised if the returned HTTP status code isn’t handled by OverPy.

Parameters: code (Integer) – The HTTP status code

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 intersection
street2 (str) – Name of second street of intersection
areacode (str) – The OSM id of the bounding area
api (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 street
areacode (str) – The OSM id of the bounding area
api (Optional[Overpass]) – API object to fetch missing elements

Return type

Result

Returns

Parsed result

Raises

overpy.exception.OverPyException – If something bad happens.