Utilities¶
Bounding Box & County Lookup¶
bbox
¶
Bounding box utilities and Kentucky county lookup.
The county lookup enables search(county="Pike", product="dem_phase3") — the domain-specific convenience that differentiates abovepy from raw pystac-client.
Bboxes are approximate (county envelope in EPSG:4326). Sufficient for STAC tile queries — not for precise boundary analysis.
get_county_bbox(county)
¶
Get the bounding box for a Kentucky county.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
county
|
str
|
County name (case-insensitive, e.g., "Pike", "franklin"). |
required |
Returns:
| Type | Description |
|---|---|
tuple
|
(xmin, ymin, xmax, ymax) in EPSG:4326. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If county name is not recognized. |
list_counties()
¶
List all Kentucky county names.
Returns:
| Type | Description |
|---|---|
list[str]
|
Sorted county names. |
validate_bbox(bbox)
¶
Validate a bounding box tuple.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bbox
|
tuple
|
(xmin, ymin, xmax, ymax). |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If bbox is malformed (xmin > xmax, ymin > ymax, or wrong length). |
CRS Conversion¶
crs
¶
CRS conversion utilities — EPSG:4326 to/from EPSG:3089.
KyFromAbove uses EPSG:3089 (Kentucky Single Zone, US Survey Feet). Users typically provide bbox in EPSG:4326 (lat/lon). This module handles the conversion transparently.
transform_bbox(bbox, src_crs, dst_crs)
¶
Transform a bounding box between CRS.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bbox
|
tuple
|
(xmin, ymin, xmax, ymax) in source CRS. |
required |
src_crs
|
str
|
Source CRS (e.g., "EPSG:4326"). |
required |
dst_crs
|
str
|
Destination CRS (e.g., "EPSG:3089"). |
required |
Returns:
| Type | Description |
|---|---|
tuple
|
Transformed (xmin, ymin, xmax, ymax). |
Response Cache¶
cache
¶
TTL-based LRU cache for STAC responses to avoid redundant API calls.
Caches search results in-memory for the session lifetime. Default TTL is 5 minutes — long enough to avoid duplicate queries in a notebook workflow, short enough to pick up catalog updates.
TTLCache
¶
Simple in-memory cache with per-entry TTL expiration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
maxsize
|
int
|
Maximum number of cached entries. Oldest evicted on overflow. |
DEFAULT_MAXSIZE
|
ttl
|
float
|
Time-to-live in seconds for each entry. |
DEFAULT_TTL
|
stats
property
¶
Return cache hit/miss statistics.
Returns:
| Type | Description |
|---|---|
dict
|
Keys: size, maxsize, hits, misses. |
get(key)
¶
Get a cached value if it exists and hasn't expired.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Cache key. |
required |
Returns:
| Type | Description |
|---|---|
Any or None
|
Cached value, or None if missing/expired. |
set(key, value)
¶
Store a value in the cache.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Cache key. |
required |
value
|
Any
|
Value to cache. |
required |
clear()
¶
Clear all cached entries and reset stats.
make_cache_key(collection_id, bbox=None, datetime=None, max_items=500, **extra)
¶
Build a deterministic cache key from search parameters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
collection_id
|
str
|
STAC collection ID. |
required |
bbox
|
tuple
|
Bounding box. |
None
|
datetime
|
str
|
Datetime filter. |
None
|
max_items
|
int
|
Max items limit. |
500
|
**extra
|
Any
|
Additional search params (intersects, filter, sortby, ids, fields). |
{}
|
Returns:
| Type | Description |
|---|---|
str
|
Hex digest cache key. |