API Reference

Overpass API

class overpy.Overpass(read_chunk_size=None, url=None, xml_parser=2, max_retry_count=None, retry_timeout=None)

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')

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

parse_xml(data, encoding='utf-8', parser=None)

Parameters:

• data (String or Bytes) – Raw XML Data

• encoding (String) – Encoding to decode byte string

Returns:

Result object

Return type:

overpy.Result

query(query)

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)

Class to handle the result.

append(element)

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)

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)

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(data, api=None, parser=None)

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:

Result

get_area(area_id, resolve_missing=False)

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:

overpy.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, **kwargs)

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)

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_ids(filter_cls)

Parameters:

filter_cls –

Returns:

get_node(node_id, resolve_missing=False)

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)

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)

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)

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)

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)

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.Element(attributes=None, result=None, tags=None)

Base element

classmethod get_center_from_json(data)

Get center information from json data

Parameters:

data – json data

Returns:

tuple with two elements: lat and lon

Return type:

tuple

class overpy.Area(area_id=None, **kwargs)

Class to represent an element of type area

classmethod from_json(data, result=None)

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:

overpy.Area

Raises:

overpy.exception.ElementDataWrongType – If type value of the passed JSON data does not match.

classmethod from_xml(child, result=None)

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

id

The id of the way

class overpy.Node(node_id=None, lat=None, lon=None, **kwargs)

Class to represent an element of type node

classmethod from_json(data, result=None)

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:

overpy.Node

Raises:

overpy.exception.ElementDataWrongType – If type value of the passed JSON data does not match.

classmethod from_xml(child, result=None)

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, center_lat=None, center_lon=None, members=None, **kwargs)

Class to represent an element of type relation

center_lat

The lat/lon of the center of the way (optional depending on query)

classmethod from_json(data, result=None)

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:

overpy.Relation

Raises:

overpy.exception.ElementDataWrongType – If type value of the passed JSON data does not match.

classmethod from_xml(child, result=None)

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, center_lat=None, center_lon=None, node_ids=None, **kwargs)

Class to represent an element of type way

center_lat

The lat/lon of the center of the way (optional depending on query)

classmethod from_json(data, result=None)

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:

overpy.Way

Raises:

overpy.exception.ElementDataWrongType – If type value of the passed JSON data does not match.

classmethod from_xml(child, result=None)

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)

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

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)

Base class to represent a member of a relation.

classmethod from_json(data, result=None)

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)

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

class overpy.RelationArea(attributes=None, geometry=None, ref=None, role=None, result=None)

class overpy.RelationNode(attributes=None, geometry=None, ref=None, role=None, result=None)

class overpy.RelationWay(attributes=None, geometry=None, ref=None, role=None, result=None)

Exceptions

exception overpy.exception.DataIncomplete(*args, **kwargs)

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)

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)

Raised if max retries reached and the Overpass server didn’t respond with a result.

exception overpy.exception.OverPyException

OverPy base exception

exception overpy.exception.OverpassBadRequest(query, msgs=None)

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)

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

Raised if load of the Overpass API service is too high and it can’t handle the request.

exception overpy.exception.OverpassRuntimeError(msg=None)

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)

Raised if the server returns a remark-tag(xml) or remark element(json) with a message starting with ‘runtime remark:’.

exception overpy.exception.OverpassTooManyRequests

Raised if the Overpass API service returns a 429 status code.

exception overpy.exception.OverpassUnknownContentType(content_type)

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)

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)

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)

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)

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.