0
# Query Builders
1

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

4
## Capabilities
5

6
### Map Query (Bounding Box)
7

8
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.
9

10
```python { .api }
11
class MapQuery:
12
    def __init__(self, south: float, west: float, north: float, east: float):
13
        """
14
        Initialize bounding box query for complete ways and relations.
15

16
        Args:
17
            south: Southern latitude boundary (decimal degrees)
18
            west: Western longitude boundary (decimal degrees)  
19
            north: Northern latitude boundary (decimal degrees)
20
            east: Eastern longitude boundary (decimal degrees)
21
        """
22

23
    def __str__(self) -> str:
24
        """
25
        Generate Overpass QL query string.
26
        
27
        Returns:
28
            Formatted query: "(node({south},{west},{north},{east});<;>;);"
29
        """
30
```
31

32
#### Usage Example
33

34
```python
35
import overpass
36

37
api = overpass.API()
38

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

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

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

49
# Process the GeoJSON response
50
for feature in response['features']:
51
    if 'name' in feature['properties']:
52
        print(f"Found: {feature['properties']['name']}")
53
```
54

55
### Way Query
56

57
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.
58

59
```python { .api }
60
class WayQuery:
61
    def __init__(self, query_parameters: str):
62
        """
63
        Initialize query for ways matching specified parameters.
64

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

70
    def __str__(self) -> str:
71
        """
72
        Generate Overpass QL query string.
73
        
74
        Returns:
75
            Formatted query: "(way{query_parameters});(._;>;);"
76
        """
77
```
78

79
#### Usage Examples
80

81
```python
82
import overpass
83

84
api = overpass.API()
85

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

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

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

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

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

109
## Query Templates
110

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

113
### MapQuery Template
114
```
115
(node({south},{west},{north},{east});<;>;);
116
```
117

118
This template:
119
1. Selects all nodes in the bounding box
120
2. Recurses up (`<`) to get ways containing those nodes  
121
3. Recurses down (`>`) to get all nodes of those ways
122
4. Returns complete way geometries with all dependent nodes
123

124
### WayQuery Template  
125
```
126
(way{query_parameters});(._;>;);
127
```
128

129
This template:
130
1. Selects ways matching the parameters
131
2. Uses `._` to reference the selected ways
132
3. Recurses down (`>`) to get all nodes of those ways
133
4. Returns ways with complete node geometry
134

135
## Integration with API
136

137
Both query builders integrate seamlessly with the API class:
138

139
```python
140
# All these are equivalent ways to use query builders
141
api.get(overpass.MapQuery(50.746, 7.154, 50.748, 7.157))
142
api.get(str(overpass.MapQuery(50.746, 7.154, 50.748, 7.157)))
143

144
# Query builders support all API options
145
response = api.get(
146
    overpass.WayQuery('[highway=motorway]'),
147
    responseformat="json",
148
    verbosity="meta"
149
)
150
```