0
# Geocoding Services
1

2
Convert between addresses and geographic coordinates using Google's geocoding and reverse geocoding APIs with support for component filtering, bounds restriction, and localization.
3

4
## Capabilities
5

6
### Address Geocoding
7

8
Convert addresses to geographic coordinates (latitude/longitude) with support for various address formats and filtering options.
9

10
```python { .api }
11
def geocode(client, address=None, place_id=None, components=None, 
12
           bounds=None, region=None, language=None):
13
    """
14
    Convert address to coordinates using Google's geocoding API.
15
    
16
    Args:
17
        client (Client): Google Maps API client instance
18
        address (str): Street address to geocode (e.g., "1600 Amphitheatre Parkway")
19
        place_id (str): Place ID to geocode instead of address
20
        components (dict): Component filters to restrict results by country,
21
                         postal code, etc. Format: {"country": "US", "postal_code": "94043"}
22
        bounds (dict): Bounding box to bias results. Format with southwest/northeast
23
                      lat/lng coordinates
24
        region (str): Region code for result biasing (ISO 3166-1 Alpha-2)
25
        language (str): Language code for returned results (ISO 639-1)
26
    
27
    Returns:
28
        list: List of geocoding result dictionaries containing geometry,
29
              formatted address, address components, and place information
30
    
31
    Raises:
32
        googlemaps.exceptions.ApiError: When API returns an error
33
        googlemaps.exceptions.TransportError: When HTTP request fails
34
        googlemaps.exceptions.Timeout: When request times out
35
    """
36
```
37

38
### Reverse Geocoding
39

40
Convert geographic coordinates to human-readable addresses with filtering options for result types and location precision.
41

42
```python { .api }
43
def reverse_geocode(client, latlng, result_type=None, location_type=None, 
44
                   language=None):
45
    """
46
    Convert coordinates to address using Google's reverse geocoding API.
47
    
48
    Args:
49
        client (Client): Google Maps API client instance
50
        latlng (tuple): Latitude/longitude coordinates as (lat, lng) tuple
51
                       or {"lat": latitude, "lng": longitude} dict
52
        result_type (list): Filter results by address type (e.g., ["street_address"])
53
        location_type (list): Filter by location type precision
54
                             (e.g., ["APPROXIMATE", "GEOMETRIC_CENTER"])
55
        language (str): Language code for returned results (ISO 639-1)
56
    
57
    Returns:
58
        list: List of reverse geocoding result dictionaries containing
59
              formatted addresses, address components, and geometry
60
    
61
    Raises:
62
        googlemaps.exceptions.ApiError: When API returns an error
63
        googlemaps.exceptions.TransportError: When HTTP request fails
64
        googlemaps.exceptions.Timeout: When request times out
65
    """
66
```
67

68
## Usage Examples
69

70
### Basic Address Geocoding
71

72
```python
73
import googlemaps
74

75
gmaps = googlemaps.Client(key='YOUR_API_KEY')
76

77
# Geocode a simple address
78
geocode_result = gmaps.geocode('1600 Amphitheatre Parkway, Mountain View, CA')
79

80
# Extract coordinates
81
location = geocode_result[0]['geometry']['location']
82
lat = location['lat']
83
lng = location['lng']
84
print(f"Coordinates: {lat}, {lng}")
85

86
# Get formatted address
87
formatted_address = geocode_result[0]['formatted_address']
88
print(f"Formatted: {formatted_address}")
89
```
90

91
### Component Filtering
92

93
```python
94
import googlemaps
95

96
gmaps = googlemaps.Client(key='YOUR_API_KEY')
97

98
# Geocode with component restrictions
99
geocode_result = gmaps.geocode(
100
    address='Main Street',
101
    components={
102
        'country': 'US',
103
        'administrative_area': 'CA',
104
        'locality': 'Mountain View'
105
    }
106
)
107

108
for result in geocode_result:
109
    print(f"Address: {result['formatted_address']}")
110
    print(f"Location: {result['geometry']['location']}")
111
```
112

113
### Bounds Biasing
114

115
```python
116
import googlemaps
117

118
gmaps = googlemaps.Client(key='YOUR_API_KEY')
119

120
# Define bounds for San Francisco Bay Area
121
bounds = {
122
    'southwest': {'lat': 37.4, 'lng': -122.5},
123
    'northeast': {'lat': 37.8, 'lng': -122.0}
124
}
125

126
# Geocode with bounds biasing
127
geocode_result = gmaps.geocode(
128
    address='Main Street',
129
    bounds=bounds,
130
    region='us'
131
)
132
```
133

134
### Place ID Geocoding
135

136
```python
137
import googlemaps
138

139
gmaps = googlemaps.Client(key='YOUR_API_KEY')
140

141
# Geocode using a place ID
142
geocode_result = gmaps.geocode(
143
    place_id='ChIJVVVVVVVQwokRGjGGGGGGGG'
144
)
145

146
location = geocode_result[0]['geometry']['location']
147
print(f"Place coordinates: {location['lat']}, {location['lng']}")
148
```
149

150
### Basic Reverse Geocoding
151

152
```python
153
import googlemaps
154

155
gmaps = googlemaps.Client(key='YOUR_API_KEY')
156

157
# Convert coordinates to address
158
latlng = (37.4224764, -122.0842499)
159
reverse_result = gmaps.reverse_geocode(latlng)
160

161
# Get the most precise address
162
best_result = reverse_result[0]
163
print(f"Address: {best_result['formatted_address']}")
164

165
# Get address components
166
components = best_result['address_components']
167
for component in components:
168
    types = component['types']
169
    name = component['long_name']
170
    print(f"{types[0]}: {name}")
171
```
172

173
### Filtered Reverse Geocoding
174

175
```python
176
import googlemaps
177

178
gmaps = googlemaps.Client(key='YOUR_API_KEY')
179

180
# Get only street addresses
181
coordinates = (37.4224764, -122.0842499)
182
street_addresses = gmaps.reverse_geocode(
183
    latlng=coordinates,
184
    result_type=['street_address']
185
)
186

187
# Get only administrative areas
188
admin_areas = gmaps.reverse_geocode(
189
    latlng=coordinates,
190
    result_type=['administrative_area_level_1', 'administrative_area_level_2']
191
)
192

193
# Filter by location type precision
194
precise_results = gmaps.reverse_geocode(
195
    latlng=coordinates,
196
    location_type=['ROOFTOP', 'RANGE_INTERPOLATED']
197
)
198
```
199

200
### Localized Results
201

202
```python
203
import googlemaps
204

205
gmaps = googlemaps.Client(key='YOUR_API_KEY')
206

207
# Get results in different languages
208
coordinates = (35.6762, 139.6503)  # Tokyo coordinates
209

210
# Japanese results
211
japanese_result = gmaps.reverse_geocode(
212
    latlng=coordinates,
213
    language='ja'
214
)
215
print(f"Japanese: {japanese_result[0]['formatted_address']}")
216

217
# English results
218
english_result = gmaps.reverse_geocode(
219
    latlng=coordinates,
220
    language='en'
221
)
222
print(f"English: {english_result[0]['formatted_address']}")
223
```
224

225
## Common Address Components
226

227
Geocoding results include standardized address components that can be extracted:
228

229
```python
230
# Example of parsing address components
231
for component in result['address_components']:
232
    component_type = component['types'][0]
233
    
234
    if component_type == 'street_number':
235
        street_number = component['long_name']
236
    elif component_type == 'route':
237
        street_name = component['long_name']
238
    elif component_type == 'locality':
239
        city = component['long_name']
240
    elif component_type == 'administrative_area_level_1':
241
        state = component['short_name']
242
    elif component_type == 'country':
243
        country = component['long_name']
244
    elif component_type == 'postal_code':
245
        zip_code = component['long_name']
246
```