Metadata-Version: 2.4
Name: overpass
Version: 0.8.0
Summary: A Python interface to the OpenStreetMap Overpass API
Author-email: Martijn van Exel <m@rtijn.org>
License-Expression: Apache-2.0
Project-URL: Homepage, https://codeberg.org/mvexel/overpass-api-python-wrapper
Keywords: openstreetmap,overpass,wrapper
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Utilities
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: osm2geojson<0.4.0,>=0.3.2
Requires-Dist: requests>=2.32.3
Provides-Extra: test
Requires-Dist: deepdiff>=7.0.1; extra == "test"
Requires-Dist: geojson>=3.1.0; extra == "test"
Requires-Dist: pytest>=7.4.0; extra == "test"
Requires-Dist: pytest-cov>=5.0.0; extra == "test"
Requires-Dist: requests-mock>=1.12.1; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: deepdiff>=7.0.1; extra == "dev"
Requires-Dist: geojson>=3.1.0; extra == "dev"
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: requests-mock>=1.12.1; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: ty>=0.0.34; extra == "dev"
Dynamic: license-file

Overpass API python wrapper
===========================

[Overpass
API](http://wiki.openstreetmap.org/wiki/Overpass_API) for Python.

![shell recording](assets/overpass-demo.gif)

Install it
==========

`pip install overpass`

## Supported Python Versions

This project is tested and supported on Python 3.10 through 3.14.

## Development

Use `uv` for local development:

```bash
uv sync --extra dev
scripts/check
```

[DEVELOPMENT.md](DEVELOPMENT.md) contains the full contributor command reference, including live API test instructions. [RELEASE.md](RELEASE.md) contains the release checklist.

## Usage

### `API()` constructor

First, create an API object.

```python
import overpass
api = overpass.API()
```

The API constructor takes several parameters, all optional:

#### `endpoint`

The default endpoint is `https://overpass-api.de/api/interpreter` but
you can pass in another instance:

```python
api = overpass.API(endpoint="https://overpass.myserver/interpreter")
```

#### `timeout`

The default timeout is 25 seconds, but you can set it to whatever you
want.

```python
api = overpass.API(timeout=600)
```

#### `debug`

Setting this to `True` will get you debug output.

### Getting data from Overpass: `get()`

Most users will only ever need to use the `get()` method. There are some convenience query methods for common queries as well, see below.

```python
response = api.get('node["name"="Salt Lake City"]')
```

`response` will be a dictionary representing the
JSON output you would get [from the Overpass API
directly](https://overpass-api.de/output_formats.html#json).

**Note that the Overpass query passed to `get()` should not contain any `out` or other meta statements.** See `verbosity` below for how to control the output.

Another example:

```python
>>> [(feature["properties"]["name"], feature["id"]) for feature in response["features"]]
[("Salt Lake City", 150935219), ("Salt Lake City", 585370637)]
```

You can find more examples in the `examples/` directory of this repository.

The `get()` method takes a few parameters, all optional having sensible defaults.

#### `verbosity`

You can set the verbosity of the [Overpass query `out` directive](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#out) using the same keywords Overpass does. In order of increased verbosity: `ids`, `skel`, `body`, `tags`, `meta`. As is the case with the Overpass API itself, `body` is the default.

```python
>>> import overpass
>>> api = overpass.API()
>>> data = api.get('way(42.819,-73.881,42.820,-73.880);(._;>;)', verbosity='geom')
>>> [f for f in data.features  if f.geometry['type'] == "LineString"]
```

(from [a question on GIS Stackexchange](https://gis.stackexchange.com/questions/294152/getting-all-information-about-ways-from-python-overpass-library/294358#294358))

#### `responseformat`

You can set the response type of your query using `get()`'s `responseformat` parameter to GeoJSON (`geojson`, the default), plain JSON (`json`), CSV (`csv`), and OSM XML (`xml`).

```python
response = api.get('node["name"="Salt Lake City"]', responseformat="xml")
```

If you choose `csv`, you will need to specify which fields you want, as described [here](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#CSV_output_mode) in the Overpass QL documentation. An example:

```python
response = api.get('node["name"="Springfield"]["place"]', responseformat="csv(name,::lon,::lat)")
```

The response will be a list of lists:

```python
[
    ['name', '@lon', '@lat'],
    ['Springfield', '-3.0645656', '56.2952787'],
    ['Springfield', '0.4937446', '51.7487585'],
    ['Springfield', '-2.4194716', '53.5732892'],
    ['Springfield', '25.5454526', '-33.9814866'],
    ....
]
```

#### `build`

We will construct a valid Overpass QL query from the parameters you set by default. This means you don't have to include 'meta' statements like `[out:json]`, `[timeout:60]`, `[out body]`, etcetera. You just supply the meat of the query, the part that actually tells Overpass what to query for. If for whatever reason you want to override this and supply a full, valid Overpass QL query, you can set `build` to `False` to make the API not do any pre-processing.

#### `date`

You can query the data as it was on a given date. You can give either a standard ISO date alone (YYYY-MM-DD) or a full overpass date and time (YYYY-MM-DDTHH:MM:SSZ, i.e. 2020-04-28T00:00:00Z).
You can also directly pass a `date` or `datetime` object from the `datetime` library.

### Pre-cooked Queries: `MapQuery`, `WayQuery`

In addition to just sending your query and parse the result, `overpass`
provides shortcuts for often used map queries. To use them, just pass
them like to normal query to the API.

#### MapQuery

This is a shorthand for a [complete ways and
relations](https://wiki.openstreetmap.org/wiki/Overpass_API/Language_Guide#Recursing_up_and_down:_Completed_ways_and_relations)
query in a bounding box (the 'map call'). You just pass the bounding box
to the constructor:

```python
MapQuery = overpass.MapQuery(50.746,7.154,50.748,7.157)
response = api.get(MapQuery)
```

#### WayQuery

This is shorthand for getting a set of ways and their child nodes that
satisfy certain criteria. Pass the criteria as a Overpass QL stub to the
constructor:

```python
WayQuery = overpass.WayQuery('[name="Highway 51"]')
response = api.get(WayQuery)
```

## Testing

Run the default hermetic test suite with:

```bash
uv run python -W default -m pytest
```

Run all required local validation, matching hosted Forgejo/Codeberg CI, with:

```bash
scripts/check
```

Live API coverage is opt-in only and is not part of required validation:

```bash
USE_LIVE_API=true uv run python -m pytest -m live_api
```

## FAQ

### I need help or have an idea for a feature

Create a [new
issue](https://codeberg.org/mvexel/overpass-api-python-wrapper/issues).

### Where did the CLI tool go?

The command line tool was deprecated in version 0.4.0.

## See also

There are other python modules that do similar things.

* https://github.com/mocnik-science/osm-python-tools
* https://github.com/DinoTools/python-overpy
