EarthDaily Python Client Documentation

EarthDaily Python Client

The EarthDaily Python Client is a comprehensive library for interacting with the EarthDaily Analytics platform. It provides seamless access to satellite data, STAC item management, and platform APIs through a unified interface.

🚀 Key Features

Platform API Access: Full integration with EarthDaily platform services
STAC Item Management: Complete CRUD operations for STAC items
Legacy Support: Backward compatibility with v0 datacube functionality
Modern Architecture: Streamlined client design with comprehensive error handling
Flexible Installation: Modular installation options for different use cases

📦 Installation

Supported Python Versions: 3.10, 3.11, 3.12, 3.13

Basic Installation

pip install earthdaily

Recommended Installation (Platform Features)

pip install "earthdaily[platform]"

Legacy Support (v0 Compatibility)

pip install "earthdaily[legacy]"

Full Installation (All Features)

pip install "earthdaily[platform,legacy]"

🔧 Environment Setup

Create a .env file in your project root with your credentials:

# .env
EDS_CLIENT_ID=your_client_id
EDS_SECRET=your_client_secret
EDS_AUTH_URL=https://your-auth-url.com/oauth/token
EDS_API_URL=https://api.earthdaily.com

Note: To use .env files, install python-dotenv separately:

pip install python-dotenv

🏃 Quick Start

from dotenv import load_dotenv  # pip install python-dotenv
from earthdaily import EDSClient, EDSConfig

# Load environment variables
load_dotenv(".env")

# Initialize client
config = EDSConfig()
client = EDSClient(config)

Alternative Configuration

# Direct configuration (without .env file)
config = EDSConfig(
    client_id="your_client_id",
    client_secret="your_client_secret",
    token_url="https://your-auth-url.com/oauth/token",
    api_url="https://api.earthdaily.com"
)
client = EDSClient(config)

🌍 Core Features

Platform API Integration

Search for satellite data using STAC:

# Search for Sentinel-2 data
search_result = client.platform.pystac_client.search(
    collections=["sentinel-2-l2a"],
    datetime="2024-06-01T00:00:00Z/2024-08-01T00:00:00Z",
    max_items=10
)
items = list(search_result.items())

STAC Item Management

Create and manage STAC items:

# Create a new STAC item
stac_item = {
    "type": "Feature",
    "stac_version": "1.0.0",
    "id": "example-item-123",
    "collection": "your-collection",
    "geometry": {"type": "Point", "coordinates": [-67.7, -37.8]},
    "properties": {"datetime": "2024-01-01T00:00:00Z"},
    "links": [],
    "assets": {}
}

client.platform.stac_item.create_item("your-collection", stac_item)

Legacy Datacube Support

Access v0 functionality through the legacy interface:

from earthdaily.legacy.datasets import load_pivot

# Load geometry and create datacube
geometry = load_pivot()
datacube = client.legacy.datacube(
    "sentinel-2-l2a",
    assets=["blue", "green", "red", "nir"],
    intersects=geometry,
    datetime=["2022-08-01", "2022-08-09"],
    mask_with="native"
)

🏗️ Architecture Overview

The client is organized into main modules:

client.platform: Modern platform API access
- pystac_client: STAC catalog search
- stac_item: STAC item CRUD operations
- bulk_search: Bulk search operations
- bulk_insert: Bulk data insertion
- bulk_delete: Bulk data deletion
client.legacy: v0 compatibility layer
- datacube(): Create analysis-ready datacubes
- search(): Legacy search functionality
- Access to existing v0 methods

🔧 Platform API Methods

STAC Item Management (`client.platform.stac_item`)

Create Items

# Create a new STAC item
item = client.platform.stac_item.create_item(
    collection_id="your-collection",
    item_data={
        "type": "Feature",
        "stac_version": "1.0.0",
        "id": "item-123",
        "geometry": {"type": "Point", "coordinates": [-67.7, -37.8]},
        "properties": {"datetime": "2024-01-01T00:00:00Z"}
    },
    return_format="dict"  # "dict", "json", or "pystac"
)

Read Items

# Get a specific item
item = client.platform.stac_item.get_item(
    collection_id="your-collection",
    item_id="item-123",
    return_format="pystac"
)

Update Items

# Update an existing item
updated_item = client.platform.stac_item.update_item(
    collection_id="your-collection",
    item_id="item-123",
    item_data={"properties": {"updated": "2024-01-02T00:00:00Z"}},
    return_format="dict"
)

Delete Items

# Delete an item
client.platform.stac_item.delete_item(
    collection_id="your-collection",
    item_id="item-123"
)

Download Assets

# Download item assets
downloads = client.platform.stac_item.download_assets(
    item=item,
    asset_keys=["blue", "green", "red"],
    output_dir="./downloads",
    max_workers=3
)

Bulk Search (`client.platform.bulk_search`)

Create Bulk Search

# Create a bulk search job
search_job = client.platform.bulk_search.create(
    collections=["sentinel-2-l2a"],
    datetime="2024-01-01T00:00:00Z/2024-02-01T00:00:00Z",
    bbox=[-74.2, 40.6, -73.9, 40.9],  # NYC area
    limit=1000,
    export_format="stacjson"
)
print(f"Job ID: {search_job.job_id}")

Monitor Job Status

# Check job status
job_status = client.platform.bulk_search.fetch(search_job.job_id)
print(f"Status: {job_status.status}")
print(f"Assets: {len(job_status.assets)}")

Download Results

# Download search results when completed
if job_status.status == "COMPLETED":
    job_status.download_assets(save_location=Path("./bulk_results"))

Bulk Insert (`client.platform.bulk_insert`)

Create Bulk Insert Job

# Create bulk insert job
insert_job = client.platform.bulk_insert.create(
    collection_id="your-collection",
    error_handling_mode="CONTINUE",  # or "STOP"
    conflict_resolution_mode="SKIP"  # or "OVERRIDE"
)

Upload Data

# Prepare STAC items file and upload
items_file = Path("./stac_items.jsonl")  # JSONL format
insert_job.upload(items_file)

# Start the job
insert_job.start()

Monitor Insert Progress

# Check insert job status
job_status = client.platform.bulk_insert.fetch(insert_job.job_id)
print(f"Items written: {job_status.items_written_count}")
print(f"Errors: {job_status.items_error_count}")

Bulk Delete (`client.platform.bulk_delete`)

Create Bulk Delete Job

# Create bulk delete job
delete_job = client.platform.bulk_delete.create(
    collection_id="your-collection"
)

Upload Item IDs

# Prepare file with item IDs to delete
ids_file = Path("./items_to_delete.txt")
delete_job.upload(ids_file)

# Start the deletion
delete_job.start()

Monitor Deletion Progress

# Check delete job status
job_status = client.platform.bulk_delete.fetch(delete_job.job_id)
print(f"Items deleted: {job_status.items_deleted_count}")
print(f"Errors: {job_status.items_error_count}")

STAC Catalog Search (`client.platform.pystac_client`)

Standard STAC Search

# Search for items using STAC API
search_results = client.platform.pystac_client.search(
    collections=["sentinel-2-l2a"],
    datetime="2024-01-01T00:00:00Z/2024-02-01T00:00:00Z",
    bbox=[-74.2, 40.6, -73.9, 40.9],
    max_items=50
)

# Process results
items = list(search_results.items())
print(f"Found {len(items)} items")

Get Collections

# List available collections
collections = client.platform.pystac_client.get_collections()
for collection in collections:
    print(f"Collection: {collection.id}")

🔄 Legacy Methods (`client.legacy`)

Create Datacubes

from earthdaily.legacy.datasets import load_pivot

# Load sample geometry
geometry = load_pivot()

# Create analysis-ready datacube
datacube = client.legacy.datacube(
    collections="sentinel-2-l2a",
    assets=["blue", "green", "red", "nir"],
    intersects=geometry,
    datetime=["2022-08-01", "2022-08-09"],
    mask_with="native",  # Apply cloud masking
    clear_cover=50,      # Minimum 50% clear pixels
    groupby_date="mean"  # Aggregate by date
)

Search Items

# Search for items (legacy interface)
items = client.legacy.search(
    collections="sentinel-2-l2a",
    intersects=geometry,
    datetime=["2022-08-01", "2022-08-09"],
    limit=100
)
print(f"Found {len(items)} items")

Multi-Collection Datacubes

# Create datacube from multiple collections
datacube = client.legacy.datacube(
    collections=["sentinel-2-l2a", "landsat-c2l2-sr"],
    assets=["red", "green", "blue"],
    intersects=geometry,
    datetime="2022-08",
    cross_calibration_collection="landsat-c2l2-sr"
)

🔍 Usage Examples

Data Discovery

# Find available collections
collections = client.platform.pystac_client.get_collections()
print([c.id for c in collections])

Download Data

# Download assets from search results
for item in items:
    client.platform.stac_item.download_assets(
        item,
        asset_keys=["blue", "green", "red"],
        output_dir="./downloads",
        max_workers=3
    )

📚 Documentation & Examples

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

Development setup
Code style guidelines
Testing procedures
Pull request process

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Need help? Here’s how to get support:

📖 Check the documentation
🐛 Open an issue for bugs
💬 Ask questions in GitHub Discussions

Ready to get started? Check out our Quick Start Example or explore the API Documentation! 🚀

EarthDaily Python Client Documentation

Contributing to EarthDaily Python Client

This document will guide you through the steps required to set up your development environment, develop, test, and contribute to the project.

Prerequisites

Ensure you have the following installed on your machine:

Python 3.10+
Poetry (for dependency management)
Tox (for running tests in multiple environments)
Pre-commit (for managing pre-commit hooks)

Setting Up the Development Environment

Clone the repository:

git clone git@github.com:earthdaily/earthdaily-python-client.git
cd earthdaily-python-client

Install dependencies using Poetry:
```
poetry install --all-extras
```
Set up pre-commit hooks:
```
pre-commit install
```

Development Workflow

Create a new branch for your feature or bugfix:
```
git checkout -b feature/your-feature-name
```

Make your changes and commit them:

git add .
git commit -m "your commit message"

Run tests locally:
```
poetry run tox
```
Push your changes and create a merge request:
```
git push origin feature/your-feature-name
```
Then, go to the GitHub repository and create a new pull request.

Running Tests

We use tox to run tests across multiple Python versions. To run all tests:

poetry run tox

To run tests for a specific Python version:

poetry run tox -e py310  # for Python 3.10
poetry run tox -e py311  # for Python 3.11
poetry run tox -e py312  # for Python 3.12

To run specific test environments:

poetry run tox -e lint     # Run linting
poetry run tox -e format   # Check formatting
poetry run tox -e mypy     # Run type checking

Code Style and Linting

We use ruff for code linting and formatting. Pre-commit hooks are configured to run automatically.

To check your code manually:

poetry run tox -e lint

To check formatting:

poetry run tox -e format

To run type checking:

poetry run tox -e mypy

Building the Package

To build the package, run:

poetry build

This will create both wheel and source distributions in the dist/ directory.

Publishing the Package

Package publishing is handled by our CI/CD pipeline. Manual publishing should only be done if absolutely necessary and after consulting with the team.

Continuous Integration

Our project uses GitHub Actions for continuous integration. The configuration can be found in .github/workflows/ at the root of the repository. It automatically runs tests, linting, and builds for each pull request.

Documentation

When adding new features or making significant changes, please update the documentation accordingly. This includes updating the README.md file and any relevant docstrings in the code.

Reporting Issues

If you encounter any bugs or have feature requests, please create an issue in our GitHub repository. Provide as much detail as possible, including steps to reproduce for bugs, and clear descriptions for feature requests.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Thank you for contributing to EarthDaily Python Client!

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

earthdaily

EarthDaily Python Client Documentation