API Reference¶
Top-level Functions¶
The easiest way to use abovepy — import the package and call these directly.
import abovepy
tiles = abovepy.search(county="Franklin", product="dem_phase3")
paths = abovepy.download(tiles, output_dir="./data")
data, profile = abovepy.read(paths[0])
abovepy
¶
abovepy — KyFromAbove LiDAR, DEM, and orthoimagery data access for Python.
All data is publicly available. No credentials required.
Quick start: import abovepy
# Find DEM tiles covering Frankfort
tiles = abovepy.search(bbox=(-84.9, 38.15, -84.8, 38.25), product="dem_phase3")
# Or search by county name
tiles = abovepy.search(county="Franklin", product="dem_phase3")
# Download
paths = abovepy.download(tiles, output_dir="./data")
# Mosaic into a single VRT
vrt = abovepy.mosaic(paths, output="frankfort.vrt")
# Stream a window without downloading
data, profile = abovepy.read(tiles.iloc[0].asset_url, bbox=(-84.85, 38.18, -84.82, 38.21))
search(bbox=None, product='dem_phase3', county=None, crs='EPSG:4326', datetime=None, max_items=500, intersects=None, filter=None, sortby=None, ids=None, fields=None, point=None, buffer_miles=None, buffer_feet=None, geometry=None)
¶
Find KyFromAbove tiles intersecting an area of interest.
Provide one of: bbox, county, point, geometry,
intersects, or ids.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bbox
|
tuple
|
Bounding box as (xmin, ymin, xmax, ymax). |
None
|
product
|
str
|
Product key (e.g., |
'dem_phase3'
|
county
|
str
|
Kentucky county name (e.g., "Pike", "Franklin"). Case-insensitive. |
None
|
crs
|
str
|
CRS of the input bbox. Default "EPSG:4326". Ignored if county is used. |
'EPSG:4326'
|
datetime
|
str
|
ISO 8601 datetime range (e.g., "2022-01/2024-01"). |
None
|
max_items
|
int
|
Maximum tiles to return. Default 500. |
500
|
intersects
|
dict or Shapely geometry
|
GeoJSON geometry or Shapely geometry for spatial intersection. |
None
|
filter
|
dict or str
|
CQL2 filter expression for advanced STAC queries. |
None
|
sortby
|
list[str] or str
|
Sort fields (e.g., |
None
|
ids
|
list[str]
|
Specific STAC item IDs to fetch. |
None
|
fields
|
list[str]
|
Fields to include/exclude from the STAC response. |
None
|
point
|
tuple
|
(longitude, latitude) point. Used with |
None
|
buffer_miles
|
float
|
Buffer radius in miles around |
None
|
buffer_feet
|
float
|
Buffer radius in US survey feet around |
None
|
geometry
|
Shapely geometry
|
Any Shapely geometry for spatial search. |
None
|
Returns:
| Type | Description |
|---|---|
SearchResult
|
Tile index wrapped in a workflow object. Access the raw
GeoDataFrame via |
download(tiles, output_dir, overwrite=False)
¶
Download tiles to a local directory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tiles
|
GeoDataFrame or SearchResult
|
Tile index from search(). |
required |
output_dir
|
str or Path
|
Directory to save downloaded files. |
required |
overwrite
|
bool
|
Overwrite existing files. Default False. |
False
|
Returns:
| Type | Description |
|---|---|
list[Path]
|
Paths to downloaded files. |
read(source, bbox=None, crs=None)
¶
Read a tile or remote source, optionally windowed to a bbox.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
str or Path
|
Local path, S3 URI, or HTTPS URL to a raster tile. |
required |
bbox
|
tuple
|
Bounding box for windowed read (xmin, ymin, xmax, ymax). |
None
|
crs
|
str
|
CRS of the bbox. Default matches source CRS. |
None
|
Returns:
| Type | Description |
|---|---|
tuple[ndarray, dict]
|
(data, profile) — raster array and rasterio profile. |
mosaic(tiles_or_paths, bbox=None, output=None, crs=None)
¶
Mosaic tiles into a single raster or VRT.
Defaults to VRT (zero-copy) unless output has a .tif extension.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tiles_or_paths
|
list[Path], GeoDataFrame, or SearchResult
|
Tile file paths, tile index, or search result. |
required |
bbox
|
tuple
|
Clip output to this bounding box. |
None
|
output
|
str or Path
|
Output path. .vrt → VRT, .tif → GeoTIFF. None → in-memory. |
None
|
crs
|
str
|
Reproject output to this CRS. |
None
|
Returns:
| Type | Description |
|---|---|
Path or tuple[ndarray, dict]
|
|
info(source=None)
¶
Inspect products or a specific remote tile.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
str
|
Product key, URL, or S3 URI. None returns all products. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame or dict
|
|
list_products(product_type=None)
¶
List available products, optionally filtered by type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product_type
|
ProductType
|
Filter to DEM, ORTHO, or POINTCLOUD. |
None
|
Returns:
| Type | Description |
|---|---|
list[Product]
|
|
clear_cache()
¶
Clear the STAC response cache.