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
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:
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:
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:
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:
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
nodes

Alias for get_elements() but filter the result by Node()

Parameters:node_id (Integer) – The Id of the node
Returns:List of elements
relations

Alias for get_elements() but filter the result by Relation

Parameters:rel_id (Integer) – Id of the relation
Returns:List of elements
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:
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:
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:
id = None

The id of the way

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.