Universal Catalog Client API Reference

UniversalCatalogClient

class open_geodata_api.catalog.UniversalCatalogClient(api_url, auth_token=None, headers=None, timeout=30, verify_ssl=True)

A universal client for connecting to any STAC API endpoint with flexible authentication.

Parameters:

• api_url (str) – Base URL of the STAC API endpoint (required)

• auth_token (str) – Authentication token if required by the API (optional)

• headers (dict) – Additional headers to include in requests (optional)

• timeout (int) – Request timeout in seconds (default: 30)

• verify_ssl (bool) – Whether to verify SSL certificates (default: True)

Example:

import open_geodata_api as ogapi

# Without authentication
client = ogapi.catalog("https://earth-search.aws.element84.com/v1")

# With authentication
client = ogapi.catalog(
    "https://your-stac-api.com",
    auth_token="your-token-here",
    headers={"X-Custom-Header": "value"}
)

Methods

search()

open_geodata_api.catalog.search(collections=None, bbox=None, datetime=None, query=None, limit=100, **kwargs)

Search for STAC items matching the specified criteria.

Parameters:

• collections (list) – List of collection IDs to search (optional)

• bbox (list) – Bounding box [west, south, east, north] (optional)

• datetime (str) – Datetime range in RFC3339 or YYYY-MM-DD format (optional)

• query (dict) – Additional query parameters (optional)

• limit (int) – Maximum number of items to return (default: 100)

• kwargs – Additional search parameters

Returns:

STACSearch object containing results

Return type:

STACSearch

Example:

results = client.search(
    collections=["sentinel-2-l2a"],
    bbox=[-122.5, 47.5, -122.0, 48.0],
    datetime="2024-01-01/2024-03-31",
    query={"eo:cloud_cover": {"lt": 20}},
    limit=50
)

items = results.get_all_items()

list_collections()

open_geodata_api.catalog.list_collections()

Get list of available collection IDs.

Returns:

List of collection ID strings

Return type:

list

Example:

collections = client.list_collections()
print(f"Available collections: {collections}")

get_collections()

open_geodata_api.catalog.get_collections()

Get detailed information about all available collections.

Returns:

List of collection metadata dictionaries

Return type:

list

Example:

collections = client.get_collections()
for col in collections:
    print(f"{col['id']}: {col['title']}")

get_collection_info()

open_geodata_api.catalog.get_collection_info(collection_id)

Get detailed information about a specific collection.

Parameters:

collection_id (str) – Collection ID

Returns:

Collection metadata dictionary

Return type:

dict

Example:

info = client.get_collection_info("sentinel-2-l2a")
print(f"Title: {info['title']}")
print(f"Description: {info['description']}")

get_asset_url()

open_geodata_api.catalog.get_asset_url(item, asset_key, prefer_jp2=True)

Get asset URL for a specific asset key with automatic band name mapping.

Parameters:

• item (STACItem) – STAC item object

• asset_key (str) – Asset key (e.g., ‘B02’, ‘blue’, ‘red’)

• prefer_jp2 (bool) – Prefer JP2 format assets if available (default: True)

Returns:

Asset URL if found, None otherwise

Return type:

str or None

Example:

item = items[0]
blue_url = client.get_asset_url(item, 'B02')  # or 'blue'
print(f"Blue band URL: {blue_url}")

get_info()

open_geodata_api.catalog.get_info()

Get client and endpoint information.

Returns:

Dictionary containing client information

Return type:

dict

Example:

info = client.get_info()
print(f"API URL: {info['api_url']}")
print(f"STAC Version: {info['stac_version']}")
print(f"Authenticated: {info['authenticated']}")

Factory Function

open_geodata_api.catalog.catalog(api_url, **kwargs)

Factory function to create a UniversalCatalogClient instance.

Parameters:

• api_url (str) – STAC API endpoint URL

• kwargs – Additional client parameters

Returns:

Configured client instance

Return type:

UniversalCatalogClient

Example:

import open_geodata_api as ogapi

client = ogapi.catalog(
    "https://your-stac-api.com",
    auth_token="token",
    timeout=60
)

Parameters Reference

Parameter	Description	Type	Default
api_url	Base URL of the STAC API endpoint	str	Required
auth_token	Authentication token (Bearer token)	str	None
headers	Additional HTTP headers	dict	None
timeout	Request timeout in seconds	int	30
verify_ssl	Verify SSL certificates	bool	True