Overpass

https://pypi.org/project/overpass/
Admin
Overpass is a Python library that provides a simple interface to query OpenStreetMap data through...
Tokens:5,224
Snippets:74
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install overpass Library

Source: https://pypi.org/project/overpass

Install the overpass library using pip. This command fetches the latest stable version.

```bash
pip install overpass
```

--------------------------------

### Install Overpass Library

Source: https://pypi.org/project/overpass/0.8.1

Install the overpass library using pip. Specify a version for exact version control.

```bash
pip install overpass==0.8.1
```

--------------------------------

### Enable Development Dependencies

Source: https://pypi.org/project/overpass

Synchronize development dependencies using uv and run a check script. This is part of the local development setup.

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

--------------------------------

### CSV Response Example

Source: https://pypi.org/project/overpass/0.8.1

Provides an example of the structure of a CSV response from an Overpass query, showing the header row and subsequent data rows.

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

--------------------------------

### Getting Data with `get()`

Source: https://pypi.org/project/overpass

Fetches data from the Overpass API using a query string. The response is a dictionary representing the JSON output.

```APIDOC
## get(query)

### Description
Executes an Overpass query and returns the result.

### Parameters
#### `query` (string, required)
The Overpass query string. Do not include `out` or other meta statements.

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

### Response
Returns a dictionary representing the JSON output from the Overpass API.

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

--------------------------------

### Fetch Data Using Overpass API get() Method

Source: https://pypi.org/project/overpass

Retrieve data from the Overpass API using a simple query string. The query should not include 'out' or meta statements.

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

--------------------------------

### Process Overpass API Response

Source: https://pypi.org/project/overpass/0.8.1

The 'get()' method returns a dictionary representing the JSON output from the Overpass API. This example shows how to extract names and IDs from the 'features' in the response.

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

--------------------------------

### API Constructor

Source: https://pypi.org/project/overpass/0.8.1

Demonstrates how to create an instance of the Overpass API client, with options for specifying the endpoint and timeout.

```APIDOC
## 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.
```

--------------------------------

### Initialize Overpass API Client

Source: https://pypi.org/project/overpass

Create an instance of the Overpass API client. The default endpoint and timeout are used.

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

--------------------------------

### Initialize Overpass API Client with Custom Endpoint

Source: https://pypi.org/project/overpass

Create an Overpass API client instance, specifying a custom endpoint URL.

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

--------------------------------

### WayQuery Constructor

Source: https://pypi.org/project/overpass

Offers a shortcut for retrieving ways and their child nodes that meet specific criteria. Pass the Overpass QL stub directly to the `WayQuery` constructor.

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

--------------------------------

### API Constructor

Source: https://pypi.org/project/overpass

Instantiate the Overpass API client. Optional parameters include endpoint, timeout, and debug mode.

```APIDOC
## API()

### Description
Initializes the Overpass API client.

### Parameters
#### `endpoint` (string, optional)
Specifies the Overpass API endpoint. Defaults to `https://overpass-api.de/api/interpreter`.

#### `timeout` (integer, optional)
Sets the request timeout in seconds. Defaults to 25.

#### `debug` (boolean, optional)
Enables debug output if set to `True`.

### Example
```python
import overpass

# Default constructor
api = overpass.API()

# With custom endpoint and timeout
api = overpass.API(endpoint="https://overpass.myserver/interpreter", timeout=600)

# With debug enabled
api = overpass.API(debug=True)
```
```

--------------------------------

### Initialize Overpass API Client with Custom Timeout

Source: https://pypi.org/project/overpass

Create an Overpass API client instance, setting a custom timeout value in seconds.

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

--------------------------------

### MapQuery Constructor

Source: https://pypi.org/project/overpass

Provides a shorthand for complete ways and relations queries within a bounding box. Instantiate `MapQuery` with latitude and longitude coordinates for the bounding box.

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

--------------------------------

### Run Pytest with Live API Coverage

Source: https://pypi.org/project/overpass/0.8.1

Command to run the pytest suite with live API coverage enabled. This requires setting the `USE_LIVE_API` environment variable and is marked with the `live_api` pytest marker.

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

--------------------------------

### Run Pytest with Live API Coverage

Source: https://pypi.org/project/overpass

Enables live API coverage for `pytest` by setting the `USE_LIVE_API` environment variable. This is an opt-in feature and not part of the required validation.

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

```

--------------------------------

### WayQuery Shortcut

Source: https://pypi.org/project/overpass/0.8.1

A shorthand for retrieving a set of ways and their child nodes that meet specific criteria. Pass the criteria as an Overpass QL stub to the constructor.

```APIDOC
#### 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
way_query = overpass.WayQuery('["name"="Highway 51"]')
response = api.get(way_query)
```
```

--------------------------------

### Run Default Pytest Suite

Source: https://pypi.org/project/overpass

Executes the default hermetic test suite for the project using `uv` and `pytest`. This command is used for local validation.

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

```

--------------------------------

### MapQuery Shortcut

Source: https://pypi.org/project/overpass/0.8.1

A shorthand for complete ways and relations queries within a bounding box (a 'map call'). Pass the bounding box coordinates to the constructor.

```APIDOC
#### MapQuery

This is a shorthand for a complete 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)
```
```

--------------------------------

### Run All Local Validation

Source: https://pypi.org/project/overpass/0.8.1

Command to run all required local validation checks, mirroring the CI environment on platforms like Forgejo and Codeberg.

```bash
scripts/check
```

--------------------------------

### Using `WayQuery` for specific way criteria

Source: https://pypi.org/project/overpass

Use `WayQuery` as a shorthand for retrieving ways and their child nodes that meet specific criteria. Pass the criteria as an Overpass QL stub to the constructor.

```APIDOC
#### 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
way_query = overpass.WayQuery('["name"="Highway 51"]')
response = api.get(way_query)
```
```

--------------------------------

### Set Response Format to XML

Source: https://pypi.org/project/overpass

Shows how to retrieve query results in XML format by specifying `responseformat='xml'` in the `api.get()` method. This is useful for parsing OSM data directly.

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

--------------------------------

### Run Local Validation Scripts

Source: https://pypi.org/project/overpass

Executes all required local validation scripts, mirroring the CI environment on Forgejo/Codeberg. This ensures consistency in local development.

```bash
scripts/check

```

--------------------------------

### Using `MapQuery` for bounding box queries

Source: https://pypi.org/project/overpass

Use `MapQuery` as a shorthand for complete ways and relations queries within a bounding box. Pass the bounding box coordinates to the constructor.

```APIDOC
#### MapQuery

This is a shorthand for a complete 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)
```
```

--------------------------------

### Enable Deprecation Warnings for Testing

Source: https://pypi.org/project/overpass

Run pytest with default deprecation warnings enabled to catch APIs that will be removed in future versions. This is crucial for migrating to 1.0.

```bash
python -W default::DeprecationWarning -m pytest
```

--------------------------------

### Disabling automatic query building with `build=False`

Source: https://pypi.org/project/overpass

By default, the API constructs valid Overpass QL queries. Set `build` to `False` to provide a full, pre-formatted Overpass QL query and disable this pre-processing.

```APIDOC
#### `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.
```

--------------------------------

### Set Response Format to CSV with Specific Fields

Source: https://pypi.org/project/overpass

Illustrates how to request query results in CSV format and specify the desired fields, such as name, longitude, and latitude, using a comma-separated string within the `responseformat` parameter.

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

--------------------------------

### Using the `verbosity` parameter

Source: https://pypi.org/project/overpass

Control the verbosity of the Overpass query `out` directive. Options include `ids`, `skel`, `body`, `tags`, `meta`, with `body` as the default.

```APIDOC
## `verbosity`

You can set the verbosity of the Overpass query `out` directive 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"]
```
```

--------------------------------

### Enable Overpass API Debug Output

Source: https://pypi.org/project/overpass/0.8.1

Set the 'debug' parameter to True during API client initialization to enable detailed debug output for requests and responses.

```python
api = overpass.API(debug=True)
```

--------------------------------

### Using the `responseformat` parameter

Source: https://pypi.org/project/overpass

Set the response type of your query using the `responseformat` parameter. Supported formats are `geojson` (default), `json`, `csv`, and `xml`. For CSV, specify fields using `csv(field1,field2,...)`.

```APIDOC
## `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 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:
```
[
    ['name', '@lon', '@lat'],
    ['Springfield', '-3.0645656', '56.2952787'],
    ['Springfield', '0.4937446', '51.7487585'],
    ['Springfield', '-2.4194716', '53.5732892'],
    ['Springfield', '25.5454526', '-33.9814866'],
    ....
]
```
```

--------------------------------

### Set Query Verbosity with 'geom'

Source: https://pypi.org/project/overpass

Demonstrates setting the verbosity of an Overpass query using the 'geom' keyword, which affects the level of detail in the returned geometry. The default verbosity is 'body'.

```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"]
```

--------------------------------

### Response Format Control

Source: https://pypi.org/project/overpass/0.8.1

Specify the response format for your queries. Supported formats are GeoJSON (default), JSON, CSV, and OSM XML.

```APIDOC
## `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. An example:

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

The response for CSV 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'],
    ....
]
```
```

--------------------------------

### Querying data for a specific date with `date`

Source: https://pypi.org/project/overpass

Query historical data by providing a date or datetime object to the `date` parameter. Accepts ISO dates (YYYY-MM-DD) or full Overpass dates (YYYY-MM-DDTHH:MM:SSZ).

```APIDOC
#### `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.
```

--------------------------------

### Process API Response

Source: https://pypi.org/project/overpass

Iterate through the features in the API response to extract names and IDs. This demonstrates how to access data from the response dictionary.

```python
[feature["properties"]["name"], feature["id"]] for feature in response["features"]
```
Tokens:
Raw