0
# Overpass
1

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

4
## Package Information
5

6
- **Package Name**: overpass
7
- **Language**: Python  
8
- **Installation**: `pip install overpass`
9

10
## Core Imports
11

12
```python
13
import overpass
14
```
15

16
Common usage patterns:
17

18
```python
19
from overpass import API, MapQuery, WayQuery
20
from overpass import OverpassError, TimeoutError, ServerRuntimeError
21
```
22

23
## Basic Usage
24

25
```python
26
import overpass
27

28
# Create API instance
29
api = overpass.API()
30

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

34
# The response is GeoJSON by default
35
print([(
36
    feature['properties']['name'],
37
    feature['id']
38
) for feature in response["features"]])
39

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

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

47
way_query = overpass.WayQuery('[name="Highway 51"]')
48
response = api.get(way_query)
49
```
50

51
## Architecture
52

53
The overpass package is built around a simple architecture:
54

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

60
## Capabilities
61

62
### Core API Interface
63

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

66
```python { .api }
67
class API:
68
    def __init__(self, endpoint=None, timeout=None, headers=None, debug=False, proxies=None): ...
69
    def get(self, query, responseformat="geojson", verbosity="body", build=True, date=''): ...
70
    
71
    @property
72
    def slots_available(self) -> int: ...
73
    @property
74
    def slots_waiting(self) -> tuple: ...
75
    @property
76
    def slots_running(self) -> tuple: ...
77
```
78

79
[Core API](./core-api.md)
80

81
### Query Builders
82

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

85
```python { .api }
86
class MapQuery:
87
    def __init__(self, south: float, west: float, north: float, east: float): ...
88

89
class WayQuery:
90
    def __init__(self, query_parameters: str): ...
91
```
92

93
[Query Builders](./query-builders.md)
94

95
### Exception Handling
96

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

99
```python { .api }
100
class OverpassError(Exception): ...
101
class OverpassSyntaxError(OverpassError, ValueError): ...
102
class TimeoutError(OverpassError): ...
103
class MultipleRequestsError(OverpassError): ...
104
class ServerLoadError(OverpassError): ...
105
class UnknownOverpassError(OverpassError): ...
106
class ServerRuntimeError(OverpassError): ...
107
```
108

109
[Exception Handling](./exceptions.md)
110

111
### Utilities
112

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

115
```python { .api }
116
class Utils:
117
    @staticmethod
118
    def to_overpass_id(osmid: int, area: bool = False) -> int: ...
119
```
120

121
[Utilities](./utilities.md)
122

123
## Response Formats
124

125
The API supports multiple response formats:
126

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

132
## Query Verbosity Levels
133

134
Control the amount of data returned in responses:
135

136
- **ids**: Only return object IDs
137
- **skel**: Return skeleton data (IDs + coordinates)  
138
- **body**: Return full object data (default)
139
- **tags**: Include all tags
140
- **meta**: Include metadata (version, timestamp, user, etc.)
141

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