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

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

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.