Geocoding
cdse.geocoding
Geocoding utilities for city-based searches.
This module provides functions to convert city names to bounding boxes for use in satellite imagery searches.
Optional dependency: geopy Install with: pip install cdse-client[geo] or pip install geopy
get_city_bbox(city_name: str, buffer_km: float = 15.0, user_agent: str = 'cdse-client', timeout: float = 10.0) -> BBox
Get a bounding box for a city using OpenStreetMap/Nominatim geocoding.
This function geocodes a city name and creates a bounding box with a configurable buffer around the city center.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
city_name
|
str
|
Name of the city, preferably with country (e.g., "Milan, Italy", "Paris, France") |
required |
buffer_km
|
float
|
Buffer around city center in kilometers. Default 15km provides good coverage for typical cities. |
15.0
|
user_agent
|
str
|
User agent string for Nominatim API. |
'cdse-client'
|
timeout
|
float
|
Network timeout in seconds for geocoding requests. |
10.0
|
Returns:
| Type | Description |
|---|---|
BBox
|
Tuple of (min_lon, min_lat, max_lon, max_lat) in WGS84. |
Raises:
| Type | Description |
|---|---|
ImportError
|
If geopy is not installed. |
ValueError
|
If city is not found. |
Example
bbox = get_city_bbox("Milano, Italia", buffer_km=20) print(bbox) (8.9, 45.3, 9.4, 45.6)
get_city_center(city_name: str, user_agent: str = 'cdse-client', timeout: float = 10.0) -> tuple[float, float]
Get the center coordinates for a city.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
city_name
|
str
|
Name of the city (e.g., "Milan, Italy") |
required |
user_agent
|
str
|
User agent string for Nominatim API. |
'cdse-client'
|
Returns:
| Type | Description |
|---|---|
tuple[float, float]
|
Tuple of (longitude, latitude) in WGS84. |
Raises:
| Type | Description |
|---|---|
ImportError
|
If geopy is not installed. |
ValueError
|
If city is not found. |
Example
lon, lat = get_city_center("Roma, Italia") print(f"Rome is at {lat:.2f}°N, {lon:.2f}°E")
get_location_info(city_name: str, user_agent: str = 'cdse-client', timeout: float = 10.0) -> dict
Get detailed location information for a city.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
city_name
|
str
|
Name of the city (e.g., "Milan, Italy") |
required |
user_agent
|
str
|
User agent string for Nominatim API. |
'cdse-client'
|
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary with location details: - address: Full formatted address - latitude: Latitude coordinate - longitude: Longitude coordinate - raw: Raw response from Nominatim (if available) |
Raises:
| Type | Description |
|---|---|
ImportError
|
If geopy is not installed. |
ValueError
|
If city is not found. |
get_predefined_bbox(city_name: str) -> Optional[BBox]
Get a pre-defined bounding box for a city (no geocoding required).
This is useful as a fallback when geopy is not installed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
city_name
|
str
|
Name of the city (case-insensitive) |
required |
Returns:
| Type | Description |
|---|---|
Optional[BBox]
|
Bounding box tuple or None if city not in database. |
Example
bbox = get_predefined_bbox("milano") if bbox: ... print(f"Milan bbox: {bbox}")