0
# Geocoding API
1

2
Direct and reverse geocoding for converting between place names and geographic coordinates. Enables location resolution for weather API calls and geographic data processing.
3

4
## Capabilities
5

6
### Direct Geocoding
7

8
```python { .api }
9
class GeocodingManager:
10
    def geocoding_api_version(self) -> tuple:
11
        """
12
        Get Geocoding API version.
13
        
14
        Returns:
15
        Tuple representing the API version
16
        """
17
    
18
    def geocode(self, toponym: str, country: str = None, state_code: str = None, limit: int = None) -> List[Location]:
19
        """
20
        Convert place names to coordinates.
21
        
22
        Parameters:
23
        - toponym: Place name to geocode
24
        - country: Two-letter country code (ISO 3166) for filtering
25
        - state_code: Two-letter state code (US only) for filtering  
26
        - limit: Maximum number of results
27
        
28
        Returns:
29
        List of Location objects matching the query
30
        """
31
```
32

33
### Reverse Geocoding
34

35
```python { .api }
36
class GeocodingManager:
37
    def reverse_geocode(self, lat: float, lon: float, limit: int = None) -> List[Location]:
38
        """
39
        Convert coordinates to place names.
40
        
41
        Parameters:
42
        - lat: Latitude (-90.0 to 90.0)
43
        - lon: Longitude (-180.0 to 180.0)
44
        - limit: Maximum number of results
45
        
46
        Returns:
47
        List of Location objects for the coordinates
48
        """
49
```
50

51
## Usage Examples
52

53
```python
54
from pyowm import OWM
55

56
owm = OWM('your-api-key')
57
geo_mgr = owm.geocoding_manager()
58

59
# Direct geocoding
60
locations = geo_mgr.geocode('London', country='GB', limit=5)
61
for loc in locations:
62
    print(f"{loc.name}, {loc.country}: {loc.lat}, {loc.lon}")
63

64
# Reverse geocoding
65
locations = geo_mgr.reverse_geocode(51.5074, -0.1278, limit=3)
66
for loc in locations:
67
    print(f"{loc.name}, {loc.country}")
68
```