0
# Geocoding Services
1

2
Geopy provides access to 31 geocoding services through a unified interface. Each geocoder implements common methods for forward and reverse geocoding while supporting service-specific parameters and options.
3

4
## Capabilities
5

6
### Common Geocoder Interface
7

8
All geocoders implement these standard methods with consistent parameter patterns and return types.
9

10
```python { .api }
11
def geocode(query, exactly_one=True, timeout=None, **kwargs):
12
    """
13
    Forward geocoding - convert address to coordinates.
14
    
15
    Parameters:
16
    - query (str): Address or location to geocode
17
    - exactly_one (bool): Return single result (True) or list (False)
18
    - timeout (float): Request timeout in seconds
19
    - **kwargs: Service-specific parameters
20
    
21
    Returns:
22
    Location or List[Location] or None
23
    """
24

25
def reverse(query, exactly_one=True, timeout=None, **kwargs):
26
    """
27
    Reverse geocoding - convert coordinates to address.
28
    
29
    Parameters:
30
    - query (str or Point): Coordinates as "lat,lon" string or Point object
31
    - exactly_one (bool): Return single result (True) or list (False) 
32
    - timeout (float): Request timeout in seconds
33
    - **kwargs: Service-specific parameters
34
    
35
    Returns:
36
    Location or List[Location] or None
37
    """
38
```
39

40
### Major Commercial Services
41

42
#### Google Geocoding API
43

44
Google's comprehensive geocoding service with global coverage and detailed results.
45

46
```python { .api }
47
from geopy.geocoders import GoogleV3
48

49
class GoogleV3:
50
    def __init__(self, api_key=None, domain='maps.googleapis.com', 
51
                 scheme='https', client_id=None, secret_key=None,
52
                 user_agent=None, format_string=None, ssl_context=None,
53
                 adapter_factory=None, proxies=None):
54
        """
55
        Initialize Google Geocoding API client.
56
        
57
        Parameters:
58
        - api_key (str): Google API key
59
        - domain (str): API domain 
60
        - client_id (str): Google for Work client ID
61
        - secret_key (str): Google for Work secret key
62
        """
63
    
64
    def geocode(self, query, bounds=None, region=None, components=None, 
65
                place_id=None, language=None, sensor=False, **kwargs):
66
        """Google-specific geocoding parameters"""
67
    
68
    def reverse(self, query, result_type=None, location_type=None, 
69
                language=None, **kwargs):
70
        """Google-specific reverse geocoding parameters"""
71
```
72

73
#### Microsoft Bing Maps
74

75
Microsoft's geocoding service with strong coverage in North America and Europe.
76

77
```python { .api }
78
from geopy.geocoders import Bing
79

80
class Bing:
81
    def __init__(self, api_key, format_string=None, scheme='https',
82
                 user_agent=None, ssl_context=None, adapter_factory=None,
83
                 proxies=None):
84
        """
85
        Initialize Bing Maps Geocoding API client.
86
        
87
        Parameters:
88
        - api_key (str): Bing Maps API key (required)
89
        """
90
    
91
    def geocode(self, query, include_neighborhood=None, include_country_code=False,
92
                user_location=None, culture=None, **kwargs):
93
        """Bing-specific geocoding parameters"""
94
    
95
    def reverse(self, query, include_neighborhood=None, 
96
                include_country_code=False, culture=None, **kwargs):
97
        """Bing-specific reverse geocoding parameters"""
98
```
99

100
#### Here Geocoding API
101

102
HERE Technologies geocoding service with automotive-focused features.
103

104
```python { .api }
105
from geopy.geocoders import Here, HereV7
106

107
class Here:
108
    def __init__(self, app_id=None, app_code=None, format_string=None,
109
                 scheme='https', user_agent=None, ssl_context=None,
110
                 adapter_factory=None, proxies=None):
111
        """Legacy HERE API (deprecated)"""
112

113
class HereV7:
114
    def __init__(self, apikey, format_string=None, scheme='https',
115
                 user_agent=None, ssl_context=None, adapter_factory=None,
116
                 proxies=None):
117
        """
118
        Initialize HERE v7 Geocoding API client.
119
        
120
        Parameters:
121
        - apikey (str): HERE API key (required)
122
        """
123
```
124

125
### Open Source / Free Services
126

127
#### OpenStreetMap Nominatim
128

129
Free geocoding service based on OpenStreetMap data with global coverage.
130

131
```python { .api }
132
from geopy.geocoders import Nominatim
133

134
class Nominatim:
135
    def __init__(self, domain='nominatim.openstreetmap.org', scheme='https',
136
                 user_agent=None, format_string=None, view_box=None,
137
                 bounded=None, country_bias=None, ssl_context=None,
138
                 adapter_factory=None, proxies=None):
139
        """
140
        Initialize Nominatim geocoder.
141
        
142
        Parameters:
143
        - domain (str): Nominatim server domain
144
        - user_agent (str): Required user agent string
145
        - view_box (list): Preferred search bounding box
146
        - bounded (bool): Restrict search to view_box
147
        - country_bias (str): Country code for result biasing
148
        """
149
    
150
    def geocode(self, query, addressdetails=False, language=False,
151
                geometry=None, extratags=False, country_codes=None,
152
                viewbox=None, bounded=None, featuretype=None,
153
                namedetails=False, **kwargs):
154
        """Nominatim-specific geocoding parameters"""
155
    
156
    def reverse(self, query, addressdetails=True, language=False,
157
                zoom=18, **kwargs):
158
        """Nominatim-specific reverse geocoding parameters"""
159
```
160

161
#### Photon
162

163
Open source geocoding service based on OpenStreetMap data.
164

165
```python { .api }
166
from geopy.geocoders import Photon
167

168
class Photon:
169
    def __init__(self, domain='photon.komoot.io', scheme='https',
170
                 user_agent=None, format_string=None, ssl_context=None,
171
                 adapter_factory=None, proxies=None):
172
        """
173
        Initialize Photon geocoder.
174
        
175
        Parameters:
176
        - domain (str): Photon server domain
177
        """
178
    
179
    def geocode(self, query, language=None, limit=None, osm_tag=None,
180
                lon=None, lat=None, **kwargs):
181
        """Photon-specific geocoding parameters"""
182
    
183
    def reverse(self, query, limit=None, **kwargs):
184
        """Photon-specific reverse geocoding parameters"""
185
```
186

187
### Regional Services
188

189
#### China - Baidu Maps
190

191
Baidu's geocoding service for mainland China with local data coverage.
192

193
```python { .api }
194
from geopy.geocoders import Baidu, BaiduV3
195

196
class Baidu:
197
    def __init__(self, api_key, scheme='https', user_agent=None,
198
                 format_string=None, ssl_context=None, adapter_factory=None,
199
                 proxies=None):
200
        """Legacy Baidu API"""
201

202
class BaiduV3:
203
    def __init__(self, api_key, scheme='https', user_agent=None,
204
                 format_string=None, ssl_context=None, adapter_factory=None,
205
                 proxies=None):
206
        """
207
        Initialize Baidu v3 Geocoding API client.
208
        
209
        Parameters:
210
        - api_key (str): Baidu API key (required)
211
        """
212
```
213

214
#### France - IGN and BAN
215

216
French national geocoding services for France-specific addresses.
217

218
```python { .api }
219
from geopy.geocoders import IGNFrance, BANFrance
220

221
class IGNFrance:
222
    def __init__(self, api_key, username=None, password=None, referer=None,
223
                 domain='wxs.ign.fr', scheme='https', user_agent=None,
224
                 format_string=None, ssl_context=None, adapter_factory=None,
225
                 proxies=None):
226
        """IGN France geocoding service"""
227

228
class BANFrance:
229
    def __init__(self, domain='api-adresse.data.gouv.fr', scheme='https',
230
                 user_agent=None, format_string=None, ssl_context=None,
231
                 adapter_factory=None, proxies=None):
232
        """Base Adresse Nationale (France) free geocoding service"""
233
```
234

235
#### Russia - Yandex
236

237
Yandex geocoding service with strong coverage in Russia and Eastern Europe.
238

239
```python { .api }
240
from geopy.geocoders import Yandex
241

242
class Yandex:
243
    def __init__(self, api_key=None, lang=None, scheme='https',
244
                 user_agent=None, format_string=None, ssl_context=None,
245
                 adapter_factory=None, proxies=None):
246
        """
247
        Initialize Yandex Geocoding API client.
248
        
249
        Parameters:
250
        - api_key (str): Yandex API key
251
        - lang (str): Response language
252
        """
253
```
254

255
### Specialized Services
256

257
#### What3Words
258

259
Global addressing system using three-word combinations for precise location identification.
260

261
```python { .api }
262
from geopy.geocoders import What3Words, What3WordsV3
263

264
class What3Words:
265
    def __init__(self, api_key, scheme='https', format_string=None,
266
                 user_agent=None, ssl_context=None, adapter_factory=None,
267
                 proxies=None):
268
        """Legacy What3Words API"""
269

270
class What3WordsV3:
271
    def __init__(self, api_key, scheme='https', format_string=None,
272
                 user_agent=None, ssl_context=None, adapter_factory=None,
273
                 proxies=None):
274
        """
275
        Initialize What3Words v3 API client.
276
        
277
        Parameters:
278
        - api_key (str): What3Words API key (required)
279
        """
280
    
281
    def geocode(self, query, language='en', **kwargs):
282
        """Convert 3-word address to coordinates"""
283
    
284
    def reverse(self, query, language='en', **kwargs):
285
        """Convert coordinates to 3-word address"""
286
```
287

288
#### US-focused Services
289

290
Specialized geocoders optimized for United States addresses.
291

292
```python { .api }
293
from geopy.geocoders import Geocodio, LiveAddress
294

295
class Geocodio:
296
    def __init__(self, api_key, scheme='https', format_string=None,
297
                 user_agent=None, ssl_context=None, adapter_factory=None,
298
                 proxies=None):
299
        """
300
        Geocodio - US and Canada focused geocoding.
301
        
302
        Parameters:
303
        - api_key (str): Geocodio API key (required)
304
        """
305

306
class LiveAddress:
307
    def __init__(self, auth_id, auth_token, candidates=1, scheme='https',
308
                 user_agent=None, format_string=None, ssl_context=None,
309
                 adapter_factory=None, proxies=None):
310
        """
311
        SmartyStreets LiveAddress API for US addresses.
312
        
313
        Parameters:
314
        - auth_id (str): SmartyStreets Auth ID
315
        - auth_token (str): SmartyStreets Auth Token
316
        - candidates (int): Maximum number of results
317
        """
318
```
319

320
### Service Discovery
321

322
Utility function to get geocoder classes by service name.
323

324
```python { .api }
325
from geopy.geocoders import get_geocoder_for_service
326

327
def get_geocoder_for_service(service):
328
    """
329
    Get geocoder class by service name string.
330
    
331
    Parameters:
332
    - service (str): Service name (e.g., 'nominatim', 'google', 'bing')
333
    
334
    Returns:
335
    Geocoder class
336
    
337
    Raises:
338
    GeocoderNotFound: If service name is not recognized
339
    """
340
```
341

342
### Available Services
343

344
Complete list of available geocoder services:
345

346
- **ArcGIS** - ESRI ArcGIS geocoding service
347
- **AzureMaps** - Microsoft Azure Maps geocoding  
348
- **Baidu** / **BaiduV3** - Baidu Maps geocoding (China)
349
- **BANFrance** - Base Adresse Nationale (France)
350
- **Bing** - Microsoft Bing Maps geocoding
351
- **DataBC** - DataBC geocoding (British Columbia, Canada)
352
- **GeocodeEarth** - Geocode.Earth service
353
- **Geocodio** - Geocodio geocoding (US/Canada)
354
- **Geokeo** - Geokeo geocoding service
355
- **GeoNames** - GeoNames geocoding service
356
- **GoogleV3** - Google Geocoding API v3
357
- **Geolake** - Geolake geocoding service
358
- **Here** / **HereV7** - HERE geocoding API
359
- **IGNFrance** - IGN France geocoding
360
- **MapBox** - Mapbox geocoding API
361
- **MapQuest** - MapQuest geocoding API
362
- **MapTiler** - MapTiler geocoding API
363
- **Nominatim** - OpenStreetMap Nominatim
364
- **OpenCage** - OpenCage geocoding API
365
- **OpenMapQuest** - Open MapQuest geocoding
366
- **PickPoint** - PickPoint geocoding service
367
- **Pelias** - Pelias geocoding engine
368
- **Photon** - Photon geocoding API
369
- **LiveAddress** - SmartyStreets LiveAddress (US)
370
- **TomTom** - TomTom geocoding API
371
- **What3Words** / **What3WordsV3** - What3Words API
372
- **Woosmap** - Woosmap geocoding service
373
- **Yandex** - Yandex geocoding (Russia)
374

375
## Usage Examples
376

377
### Basic Service Usage
378

379
```python
380
from geopy.geocoders import Nominatim, GoogleV3, Bing
381

382
# Free service (rate limited)
383
geolocator = Nominatim(user_agent="my_app_name")
384
location = geolocator.geocode("New York City")
385

386
# Commercial services (require API keys)
387
google = GoogleV3(api_key="your_api_key")
388
bing = Bing(api_key="your_api_key")
389

390
location = google.geocode("1600 Amphitheatre Parkway, Mountain View, CA")
391
location = bing.geocode("Space Needle, Seattle, WA")
392
```
393

394
### Service Selection
395

396
```python
397
from geopy.geocoders import get_geocoder_for_service
398

399
# Dynamic service selection
400
service_name = "nominatim"  # Could come from config
401
geocoder_class = get_geocoder_for_service(service_name)
402
geolocator = geocoder_class(user_agent="my_app")
403

404
# Service comparison
405
services = ['nominatim', 'photon', 'opencage']
406
results = {}
407

408
for service in services:
409
    try:
410
        geocoder_class = get_geocoder_for_service(service)
411
        geolocator = geocoder_class(user_agent="comparison_app")
412
        results[service] = geolocator.geocode("Paris, France")
413
    except Exception as e:
414
        results[service] = str(e)
415
```
416

417
### Language and Regional Parameters
418

419
```python
420
# Language-specific results
421
nominatim = Nominatim(user_agent="my_app")
422
location_en = nominatim.geocode("London", language="en")  # English
423
location_fr = nominatim.geocode("London", language="fr")  # French
424
location_de = nominatim.geocode("London", language="de")  # German
425

426
# Regional biasing
427
google = GoogleV3(api_key="your_key")
428
location = google.geocode("Springfield", region="us")  # US bias
429
location = google.geocode("Springfield", region="uk")  # UK bias
430

431
# Country restrictions
432
nominatim.geocode("Paris", country_codes="fr")  # France only
433
nominatim.geocode("Paris", country_codes=["fr", "be"])  # France or Belgium
434
```