Overpass

A Python interface to the OpenStreetMap Overpass API for querying geographical data. This library provides a simple wrapper around the Overpass API, enabling developers to retrieve OpenStreetMap data using Overpass QL queries with results in multiple formats including GeoJSON, JSON, XML, and CSV.

Package Information

• Package Name: overpass
• Language: Python
• Installation: pip install overpass

Core Imports

import overpass

Common usage patterns:

from overpass import API, MapQuery, WayQuery
from overpass import OverpassError, TimeoutError, ServerRuntimeError

Basic Usage

import overpass

# Create API instance
api = overpass.API()

# Simple query for a specific node
response = api.get('node["name"="Salt Lake City"]')

# The response is GeoJSON by default
print([(
    feature['properties']['name'],
    feature['id']
) for feature in response["features"]])

# Query with different response format
xml_response = api.get('node["name"="Salt Lake City"]', responseformat="xml")

# Using pre-built query objects
map_query = overpass.MapQuery(50.746, 7.154, 50.748, 7.157)  # south, west, north, east
response = api.get(map_query)

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

Architecture

The overpass package is built around a simple architecture:

• API Class: Main interface for executing queries against the Overpass API
• Query Builders: Pre-built query objects (MapQuery, WayQuery) for common query patterns
• Exception Handling: Specific exceptions for different types of API errors
• Utility Functions: Helper functions for working with OSM data

Capabilities

Core API Interface

Main API class for executing Overpass queries with support for multiple response formats, timeout configuration, debugging, and server status monitoring.

class API:
    def __init__(self, endpoint=None, timeout=None, headers=None, debug=False, proxies=None): ...
    def get(self, query, responseformat="geojson", verbosity="body", build=True, date=''): ...
    
    @property
    def slots_available(self) -> int: ...
    @property
    def slots_waiting(self) -> tuple: ...
    @property
    def slots_running(self) -> tuple: ...

Core API

Query Builders

Pre-built query objects for common Overpass query patterns, including bounding box queries and way-based queries.

class MapQuery:
    def __init__(self, south: float, west: float, north: float, east: float): ...

class WayQuery:
    def __init__(self, query_parameters: str): ...

Query Builders

Exception Handling

Comprehensive exception classes for handling various types of Overpass API errors including syntax errors, timeouts, and server issues.

class OverpassError(Exception): ...
class OverpassSyntaxError(OverpassError, ValueError): ...
class TimeoutError(OverpassError): ...
class MultipleRequestsError(OverpassError): ...
class ServerLoadError(OverpassError): ...
class UnknownOverpassError(OverpassError): ...
class ServerRuntimeError(OverpassError): ...

Exception Handling

Utilities

Helper utilities for working with OpenStreetMap data, including ID conversion functions.

class Utils:
    @staticmethod
    def to_overpass_id(osmid: int, area: bool = False) -> int: ...

Utilities

Response Formats

The API supports multiple response formats:

• geojson (default): GeoJSON format dictionary suitable for mapping applications
• json: Raw JSON response from the Overpass API
• xml: XML string response in OSM XML format
• csv: List of lists format (requires CSV parameters in query)

Query Verbosity Levels

Control the amount of data returned in responses:

• ids: Only return object IDs
• skel: Return skeleton data (IDs + coordinates)
• body: Return full object data (default)
• tags: Include all tags
• meta: Include metadata (version, timestamp, user, etc.)

Additional modifiers: "geom", "bb", "center", "asc", "qt"