tessl/pypi-overpass

A Python interface to the OpenStreetMap Overpass API for querying geographical data

—

Pending

Overview

Eval results

Files

Query Builders

Name: tessl/pypi-overpass
Author: tessl

Pre-built query objects that generate common Overpass QL query patterns. These provide convenient shortcuts for frequently used query types without requiring manual Overpass QL construction.

Capabilities

Map Query (Bounding Box)

Query for complete ways and relations within a specified bounding box. This is equivalent to the Overpass API "map call" that retrieves all OpenStreetMap data in a geographic area.

class MapQuery:
    def __init__(self, south: float, west: float, north: float, east: float):
        """
        Initialize bounding box query for complete ways and relations.

        Args:
            south: Southern latitude boundary (decimal degrees)
            west: Western longitude boundary (decimal degrees)  
            north: Northern latitude boundary (decimal degrees)
            east: Eastern longitude boundary (decimal degrees)
        """

    def __str__(self) -> str:
        """
        Generate Overpass QL query string.
        
        Returns:
            Formatted query: "(node({south},{west},{north},{east});<;>;);"
        """

Usage Example

import overpass

api = overpass.API()

# Query data in a bounding box around a city area
# Coordinates: south, west, north, east
map_query = overpass.MapQuery(50.746, 7.154, 50.748, 7.157)

# Execute the query
response = api.get(map_query)

# The response contains all nodes, ways, and relations in the area
print(f"Retrieved {len(response['features'])} features")

# Process the GeoJSON response
for feature in response['features']:
    if 'name' in feature['properties']:
        print(f"Found: {feature['properties']['name']}")

Way Query

Query for a set of ways and their dependent nodes that satisfy specific criteria. This is useful for retrieving road networks, building outlines, or other way-based features.

class WayQuery:
    def __init__(self, query_parameters: str):
        """
        Initialize query for ways matching specified parameters.

        Args:
            query_parameters: Overpass QL parameters for way selection
                             (e.g., '[name="Highway 51"]', '[highway=motorway]')
        """

    def __str__(self) -> str:
        """
        Generate Overpass QL query string.
        
        Returns:
            Formatted query: "(way{query_parameters});(._;>;);"
        """

Usage Examples

import overpass

api = overpass.API()

# Query ways by name
highway_query = overpass.WayQuery('[name="Highway 51"]')
response = api.get(highway_query)

# Query ways by highway type
motorway_query = overpass.WayQuery('[highway=motorway]')
response = api.get(motorway_query)

# Query ways with multiple criteria
complex_query = overpass.WayQuery('[highway=primary][maxspeed=50]')
response = api.get(complex_query)

# Query ways in a specific area (using area ID)
area_query = overpass.WayQuery('(area:3602758138)[highway]')
response = api.get(area_query)

# Process results
for feature in response['features']:
    if feature['geometry']['type'] == 'LineString':
        props = feature['properties']
        print(f"Way: {props.get('name', 'unnamed')} ({props.get('highway', 'unknown type')})")

Query Templates

The query builders use predefined templates to generate valid Overpass QL:

MapQuery Template

(node({south},{west},{north},{east});<;>;);

This template:

Selects all nodes in the bounding box
Recurses up (<) to get ways containing those nodes
Recurses down (>) to get all nodes of those ways
Returns complete way geometries with all dependent nodes

WayQuery Template

(way{query_parameters});(._;>;);

This template:

Selects ways matching the parameters
Uses ._ to reference the selected ways
Recurses down (>) to get all nodes of those ways
Returns ways with complete node geometry

Integration with API

Both query builders integrate seamlessly with the API class:

# All these are equivalent ways to use query builders
api.get(overpass.MapQuery(50.746, 7.154, 50.748, 7.157))
api.get(str(overpass.MapQuery(50.746, 7.154, 50.748, 7.157)))

# Query builders support all API options
response = api.get(
    overpass.WayQuery('[highway=motorway]'),
    responseformat="json",
    verbosity="meta"
)

Install with Tessl CLI