Welcome to Python Overpass API’s documentation!

Contents:

Introduction

Requirements

Supported Python versions:

  • Python 3.6+

  • PyPy3

Installation

As a Python egg

You can install the most recent version using pip

$ pip install overpy

From a tarball release

Download the most recent tarball from github, unpack it and run the following command on the command-line.

$ python setup.py install

Install the development version

Install git and run the following commands on the command-line.

$ git clone https://github.com/DinoTools/python-overpy.git
$ cd python-overpy
$ python setup.py install

Usage

It is recommended to have a look at the documentation of the Overpass API before using OverPy. For more examples have a look at the examples page or in the examples directory.

import overpy

api = overpy.Overpass()

# fetch all ways and nodes
result = api.query("""
    way(50.746,7.154,50.748,7.157) ["highway"];
    (._;>;);
    out body;
    """)

for way in result.ways:
    print("Name: %s" % way.tags.get("name", "n/a"))
    print("  Highway: %s" % way.tags.get("highway", "n/a"))
    print("  Nodes:")
    for node in way.nodes:
        print("    Lat: %f, Lon: %f" % (node.lat, node.lon))

Examples

Basic example

Lets start with an example from the Overpass API documentation.

Query String:

1node(50.745,7.17,50.75,7.18);
2out;

Use OverPy:

 1>>> import overpy
 2>>> api = overpy.Overpass()
 3>>> result = api.query("node(50.745,7.17,50.75,7.18);out;")
 4>>> len(result.nodes)
 51984
 6>>> len(result.ways)
 70
 8>>> len(result.relations)
 90
10>>> node = result.nodes[2]
11>>> node.id
12100792806
13>>> node.tags
14{}
Line 1:

Import the required Python module

Line 2:

Create a new instance of the Overpass() class. This instance is used to query the Overpass API.

Line 3:

Use the Query-String from above to query the Overpass API service.

Line 4,5:

Get the number of nodes in the result set.

Line 6-9:

Get the number of ways and relations available in the result set.

Line 10-14:

Get the third node from the list. Display the ID and the tags of this node.

Use Overpass QL or Overpass XML

Queries are passed directly to the Overpass API service without any modification. So it is possible to use Overpass QL and Overpass XML.

Overpass QL

Query:

1node["name"="Gielgen"];
2out body;

Use OverPy:

1>>> import overpy
2>>> api = overpy.Overpass()
3>>> result = api.query("""node["name"="Gielgen"];out body;""")
4>>> len(result.nodes)
56
6>>> len(result.ways)
70
8>>> len(result.relations)
90

Overpass XML

Query:

1<osm-script>
2  <query type="node">
3    <has-kv k="name" v="Gielgen"/>
4  </query>
5  <print/>
6</osm-script>

Use OverPy:

 1>>> import overpy
 2>>> api = overpy.Overpass()
 3>>> result = api.query("""<osm-script>
 4...   <query type="node">
 5...     <has-kv k="name" v="Gielgen"/>
 6...   </query>
 7...   <print/>
 8... </osm-script>""")
 9>>> len(result.nodes)
106
11>>> len(result.ways)
120
13>>> len(result.relations)
140

Parse JSON or XML responses

On a request OverPy detects the content type from the response.

JSON response

Query String:

1[out:json];
2node(50.745,7.17,50.75,7.18);
3out;

Use OverPy:

1>>> import overpy
2>>> api = overpy.Overpass()
3>>> result = api.query("[out:json];node(50.745,7.17,50.75,7.18);out;")
4>>> len(result.nodes)
51984
6>>> len(result.ways)
70
8>>> len(result.relations)
90

XML response

Query String:

1[out:xml];
2node(50.745,7.17,50.75,7.18);
3out;

Use OverPy:

1>>> import overpy
2>>> api = overpy.Overpass()
3>>> result = api.query("[out:xml];node(50.745,7.17,50.75,7.18);out;")
4>>> len(result.nodes)
51984
6>>> len(result.ways)
70
8>>> len(result.relations)
90

Ways

Get all nodes of a way

In this example the Overpass API will only return the Way elements with the name “Gielgenstraße”. But there will be no Node elements in the result set.

OverPy provides a way to resolve missing nodes.

Query String:

1way
2["name"="Gielgenstraße"]
3(50.7,7.1,50.8,7.25);
4out;

Use OverPy:

 1>>> import overpy
 2>>> api = overpy.Overpass()
 3>>> result = api.query("""way["name"="Gielgenstraße"](50.7,7.1,50.8,7.25);out;""")
 4>>> len(result.nodes)
 50
 6>>> len(result.ways)
 74
 8>>> way = result.ways[0]
 9>>> way.nodes
10Traceback (most recent call last):
11  File "<stdin>", line 1, in <module>
12    [...]
13    raise exception.DataIncomplete("Resolve missing nodes is disabled")
14overpy.exception.DataIncomplete: ('Data incomplete try to improve the query to resolve the missing data', 'Resolve missing nodes is disabled')
15>>> way.get_nodes()
16Traceback (most recent call last):
17  File "<stdin>", line 1, in <module>
18    [...]
19    raise exception.DataIncomplete("Resolve missing nodes is disabled")
20overpy.exception.DataIncomplete: ('Data incomplete try to improve the query to resolve the missing data', 'Resolve missing nodes is disabled')
21>>> nodes = way.get_nodes(resolve_missing=True)
22>>> len(nodes)
2313
24>>> len(result.nodes)
2513
26>>> len(way.nodes)
2713
Line 1-3:

Send a query to the Overpass API service.

Line 4-6:

There are 4 Way elements and 0 Node elements in the result set.

Line 7:

Get the first way.

Line 8-19:

Use overpy.Way.nodes class attribute and the overpy.Way.get_nodes() function to get the nodes for the way. Both raise an exception because the nodes are not in the result set and auto resolving missing nodes is disabled.

Line 20-21:

Use the overpy.Way.get_nodes() function and let OverPy try to resolve the missing nodes. The function will return all Node elements connected with the Way element.

Line 22-25:

The resolved nodes have been added to the result set and are available to be used again later.

Frequently Asked Questions

429 Too Many Requests

If too many requests are send from the same IP address the server blocks some requests to avoid that a user uses up all resources. For more information have a look at the Overpass API documentation.

OverPy tries to fetch missing information automatically. To limit the number of requests you should try to fetch all required information/data(relations, ways, nodes, tags, …) with the initial query.

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

Contributing

First of all, thank you for your interest in contributing to OverPy!

Filing bug reports

Bug reports are very welcome. Please fill them on the GitHub issue tracker. Good bug reports come with extensive descriptions of the error and how to reproduce it.

Patches

All patches to OverPy should be submitted in the form of pull requests to the main OverPy repository, DinoTools/python-overpy. These pull requests should satisfy the following properties:

Code

  • The pull request should focus on one particular improvement to OverPy.

  • Create different pull requests for unrelated features or bugfixes.

  • Python code should follow PEP 8, especially in the “do what code around you does” sense.

Documentation

When introducing new functionality, please remember to write documentation.

Tests

It is recommended to add tests for new code you add.

Review

Finally, pull requests must be reviewed before merging. Everyone can perform reviews; this is a very valuable way to contribute, and is highly encouraged.

Changelog

0.x (master)

Note

This version is not yet released and is under development.

0.6 (2021-04-20)

  • Drop Python 2.7 support

  • Replace Travis CI with GitHub Actions

  • Change ThreadedHTTPServer to HTTPServer for tests

  • Add CodeQL CI tests

  • Add pre-commit

  • Improve build steps

0.5 (2021-04-14)

  • Add support to retry a failed request

  • Improve test handlers to fix issues with Py2.7 and PyPy

  • Improve tests

  • Add Support for Python 3.6

  • Add function to handle remark tags and elements

  • Add support to parse data from ET.Element

  • Move attribute modifiers from class to package

  • Change to use Exception instead of BaseException

0.4 (2016-12-08)

  • Add SAX parser

  • Add option to choose DOM or SAX parser

  • Fix issues with CI builds with Python 3.2

  • Add Python 3.5 to CI builds

  • Fix issues (Thanks to all contributors)

  • Add property for default API URL

  • Add examples

  • Build Fixes

  • GitHub templates

  • Parse center information

  • Parse geometry information

  • Support Areas

0.3.1 (2015-04-30)

  • Improve example

0.3.0 (2015-04-30)

  • Improve internal data handling (Dominik)

  • Add helper functions (Morris Jobke)

0.2.0 (2014-12-27)

  • Added support for xml response data

  • Added support for exceptions

  • Added tests with 100% code coverage

  • Removed Python 2.6 support

  • Added more examples to the documentation

0.1.0 (2014-12-14)

Proof of concept

  • Initial release.

Indices and tables