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

overpy.Result

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

overpy.Result

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

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

overpy.Result

classmethod from_xml(data, api=None, parser=2)[source]¶

Create a new instance and load data from xml object.

Parameters

data (xml.etree.ElementTree.Element) – Root element
api (Overpass) –
parser (Integer) – Specify the parser to use(DOM or SAX)

Returns

New instance of Result object

Return type

Result

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

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

Parameters: filter_cls –
Returns

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

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

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

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

Base element

classmethod get_center_from_json(data)[source]¶

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

overpy.Area

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

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 = None¶: 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

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

overpy.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 (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)[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

overpy.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 (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)[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

overpy.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 (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)[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

overpy.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 (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)[source]¶

class overpy.RelationNode(attributes=None, geometry=None, ref=None, role=None, result=None)[source]¶

class overpy.RelationWay(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.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.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.

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.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

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.

API Reference¶

Overpass API¶

Result¶

Elements¶

Relation Members¶

Exceptions¶

Helper¶

Table of Contents

Previous topic

Next topic

This Page