0
# Geopy
1

2
A comprehensive Python client library for several popular geocoding web services that makes it easy for Python developers to locate coordinates of addresses, cities, countries, and landmarks across the globe using third-party geocoders and other data sources. Geopy provides both forward geocoding (address to coordinates) and reverse geocoding (coordinates to address) with a unified interface across multiple services, plus powerful geodesic distance calculation capabilities.
3

4
## Package Information
5

6
- **Package Name**: geopy
7
- **Language**: Python
8
- **Installation**: `pip install geopy`
9
- **Optional Dependencies**: 
10
  - `pip install "geopy[aiohttp]"` for async support
11
  - `pip install "geopy[requests]"` for requests adapter
12
  - `pip install "geopy[timezone]"` for timezone support
13

14
## Core Imports
15

16
```python
17
import geopy
18
from geopy.geocoders import Nominatim
19
from geopy import distance
20
from geopy.location import Location
21
from geopy.point import Point
22
```
23

24
Specific geocoder imports:
25

26
```python
27
from geopy.geocoders import GoogleV3, Bing, ArcGIS, Here, MapBox
28
from geopy.geocoders import get_geocoder_for_service
29
```
30

31
## Basic Usage
32

33
```python
34
from geopy.geocoders import Nominatim
35
from geopy.distance import geodesic
36

37
# Initialize a geocoder
38
geolocator = Nominatim(user_agent="specify_your_app_name_here")
39

40
# Forward geocoding - address to coordinates
41
location = geolocator.geocode("175 5th Avenue NYC")
42
print(location.address)
43
print((location.latitude, location.longitude))
44

45
# Reverse geocoding - coordinates to address
46
location = geolocator.reverse("52.509669, 13.376294")
47
print(location.address)
48

49
# Distance calculation
50
newport_ri = (41.49008, -71.312796)
51
cleveland_oh = (41.499498, -81.695391)
52
distance = geodesic(newport_ri, cleveland_oh).miles
53
print(f"Distance: {distance} miles")
54
```
55

56
## Architecture
57

58
Geopy's architecture is built around three core concepts:
59

60
- **Geocoders**: Service-specific classes that abstract geocoding APIs with unified interfaces
61
- **Data Classes**: Location, Point, and Timezone objects that represent geographical data
62
- **Distance Calculations**: Geodesic and great-circle algorithms for precise distance measurements
63
- **Adapters**: HTTP client abstraction supporting both synchronous and asynchronous operations
64

65
This design enables consistent geocoding across 31 different services while providing flexible configuration, comprehensive error handling, and support for both sync and async operations.
66

67
## Capabilities
68

69
### Geocoding Services
70

71
Access to 31 geocoding services including Google, Bing, OpenStreetMap Nominatim, Here, and many others. Each geocoder provides forward and reverse geocoding with service-specific options and configurations.
72

73
```python { .api }
74
# Common geocoder interface
75
def geocode(query, exactly_one=True, timeout=None, **kwargs):
76
    """Forward geocoding - address to coordinates"""
77

78
def reverse(query, exactly_one=True, timeout=None, **kwargs):
79
    """Reverse geocoding - coordinates to address"""
80
```
81

82
[Geocoding Services](./geocoding-services.md)
83

84
### Core Data Types
85

86
Essential data structures for representing locations, coordinates, and geographical points with comprehensive parsing and formatting capabilities.
87

88
```python { .api }
89
class Location:
90
    """Parsed geocoder response with address and coordinates"""
91
    address: str
92
    latitude: float
93
    longitude: float
94
    point: Point
95
    raw: dict
96

97
class Point:
98
    """Geodetic point with latitude, longitude, and altitude"""
99
    def __init__(self, latitude, longitude, altitude=None): ...
100
    latitude: float
101
    longitude: float
102
    altitude: float
103
```
104

105
[Core Data Types](./core-data-types.md)
106

107
### Distance Calculations
108

109
Precise distance calculations using geodesic (ellipsoidal earth model) and great-circle (spherical earth model) algorithms with automatic unit conversions and destination point calculations.
110

111
```python { .api }
112
class geodesic:
113
    """Geodesic distance using ellipsoidal earth model"""
114
    def __init__(point1, point2, ellipsoid='WGS-84'): ...
115
    kilometers: float
116
    miles: float
117
    meters: float
118
    
119
def destination(point, bearing, distance=None):
120
    """Calculate destination point from bearing and distance"""
121
```
122

123
[Distance Calculations](./distance-calculations.md)
124

125
### Error Handling
126

127
Comprehensive exception hierarchy covering authentication failures, quota exceeded, rate limiting, service unavailability, and parsing errors with detailed error information.
128

129
```python { .api }
130
class GeopyError(Exception):
131
    """Base exception for all geopy errors"""
132

133
class GeocoderServiceError(GeopyError):
134
    """Generic geocoding service error"""
135

136
class GeocoderRateLimited(GeocoderServiceError):
137
    """Rate limiting error with retry_after attribute"""
138
    retry_after: int
139
```
140

141
[Error Handling](./error-handling.md)
142

143
### Async Support
144

145
Asynchronous geocoding operations using aiohttp adapter for high-performance applications requiring concurrent geocoding requests.
146

147
```python { .api }
148
from geopy.adapters import AioHTTPAdapter
149

150
async with Nominatim(
151
    user_agent="specify_your_app_name_here",
152
    adapter_factory=AioHTTPAdapter,
153
) as geolocator:
154
    location = await geolocator.geocode("175 5th Avenue NYC")
155
```
156

157
[Async Support](./async-support.md)
158

159
### Rate Limiting
160

161
Built-in rate limiting functionality to manage API quotas and prevent service abuse with configurable delays, retry logic, and error handling.
162

163
```python { .api }
164
from geopy.extra.rate_limiter import RateLimiter
165

166
geocoder = RateLimiter(
167
    geolocator.geocode, 
168
    min_delay_seconds=1.0,
169
    max_retries=2
170
)
171
```
172

173
[Rate Limiting](./rate-limiting.md)
174

175
## Types
176

177
```python { .api }
178
from typing import Union, Optional, List, Dict, Any, Tuple
179

180
# Common type aliases used throughout geopy
181
LocationType = Union[Location, None]
182
LocationListType = Union[List[Location], LocationType]
183
PointType = Union[Point, str, Tuple[float, float], Tuple[float, float, float]]
184
CoordinatePair = Tuple[float, float]
185
```