0
# Utilities
1

2
Helper utilities for working with OpenStreetMap data, including functions for converting between different ID formats used in the OpenStreetMap ecosystem.
3

4
## Capabilities
5

6
### ID Conversion Utilities
7

8
Convert OpenStreetMap IDs to Overpass API format for use in queries.
9

10
```python { .api }
11
class Utils:
12
    @staticmethod
13
    def to_overpass_id(osmid: int, area: bool = False) -> int:
14
        """
15
        Convert OSM ID to Overpass ID format.
16
        
17
        The Overpass API uses different ID ranges for different object types.
18
        This function converts standard OSM relation/area IDs to the format
19
        expected by Overpass queries.
20

21
        Args:
22
            osmid: OpenStreetMap ID (integer)
23
            area: If True, convert to area ID format; if False, convert to relation ID format
24

25
        Returns:
26
            Overpass ID in the appropriate format:
27
            - For areas: osmid + 2400000000
28
            - For relations: osmid + 3600000000
29
        """
30
```
31

32
#### Usage Examples
33

34
```python
35
import overpass
36

37
# Convert relation ID to Overpass format
38
osm_relation_id = 123456
39
overpass_relation_id = overpass.Utils.to_overpass_id(osm_relation_id)
40
print(f"OSM relation {osm_relation_id} -> Overpass ID {overpass_relation_id}")
41
# Output: OSM relation 123456 -> Overpass ID 3600123456
42

43
# Convert area ID to Overpass format  
44
osm_area_id = 789012
45
overpass_area_id = overpass.Utils.to_overpass_id(osm_area_id, area=True)
46
print(f"OSM area {osm_area_id} -> Overpass ID {overpass_area_id}")
47
# Output: OSM area 789012 -> Overpass ID 2400789012
48

49
# Use in queries
50
api = overpass.API()
51

52
# Query using converted relation ID
53
relation_query = f'relation({overpass_relation_id});'
54
response = api.get(relation_query)
55

56
# Query using converted area ID
57
area_query = f'node(area:{overpass_area_id})[amenity=restaurant];'
58
response = api.get(area_query)
59
```
60

61
#### Practical Application
62

63
```python
64
def query_restaurants_in_city(api, city_relation_id):
65
    """
66
    Query restaurants in a city using its OSM relation ID.
67
    
68
    Args:
69
        api: Overpass API instance
70
        city_relation_id: OpenStreetMap relation ID for the city
71
    
72
    Returns:
73
        GeoJSON response with restaurant data
74
    """
75
    # Convert OSM relation ID to Overpass area ID
76
    area_id = overpass.Utils.to_overpass_id(city_relation_id, area=True)
77
    
78
    # Query restaurants in the area
79
    query = f'node(area:{area_id})[amenity=restaurant];'
80
    
81
    return api.get(query)
82

83
# Example usage
84
api = overpass.API()
85

86
# Salt Lake City relation ID from OpenStreetMap
87
salt_lake_city_id = 161645  # This is the actual OSM relation ID
88

89
restaurants = query_restaurants_in_city(api, salt_lake_city_id)
90
print(f"Found {len(restaurants['features'])} restaurants")
91

92
for restaurant in restaurants['features']:
93
    name = restaurant['properties'].get('name', 'Unnamed')
94
    cuisine = restaurant['properties'].get('cuisine', 'Unknown')
95
    print(f"- {name} ({cuisine})")
96
```
97

98
## ID Format Reference
99

100
### OpenStreetMap ID Ranges
101

102
OpenStreetMap uses different ID spaces for different object types:
103

104
- **Nodes**: Positive integers starting from 1
105
- **Ways**: Positive integers starting from 1  
106
- **Relations**: Positive integers starting from 1
107

108
### Overpass API ID Ranges
109

110
The Overpass API uses offset ID ranges to distinguish object types in certain contexts:
111

112
- **Nodes**: Use original OSM node IDs (no conversion needed)
113
- **Ways**: Use original OSM way IDs (no conversion needed)
114
- **Relations**: OSM relation ID + 3,600,000,000
115
- **Areas**: OSM relation ID + 2,400,000,000
116

117
### Conversion Constants
118

119
```python
120
# Constants used in ID conversion (for reference)
121
AREA_BASE = 2400000000      # Added to OSM relation ID for area queries
122
RELATION_BASE = 3600000000  # Added to OSM relation ID for relation queries
123
```
124

125
### When to Use ID Conversion
126

127
**Area Queries**: When querying for objects within an administrative boundary:
128
```python
129
# Query amenities within a city boundary
130
area_id = overpass.Utils.to_overpass_id(city_relation_id, area=True)
131
query = f'node(area:{area_id})[amenity];'
132
```
133

134
**Relation Queries**: When specifically querying relation objects:
135
```python  
136
# Query a specific relation
137
relation_id = overpass.Utils.to_overpass_id(osm_relation_id)
138
query = f'relation({relation_id});'
139
```
140

141
**Node/Way Queries**: Use original OSM IDs (no conversion needed):
142
```python
143
# Query specific nodes or ways
144
query = f'node({osm_node_id});'
145
query = f'way({osm_way_id});'
146
```