Quick Start Guide

Get started with the Harmonized Data Access (HDA) API in just a few minutes. This guide will walk you through the authentication process, data discovery, and accessing datasets using different methods.

Prerequisites

No. 1 Account with DESP

You need to have an account with DESP. See How to create a DestinE Platform account

No. 2 Python 3.7+ or curl

• Access to Python 3.7+, PySTAC and other libraries

• curl

Choose Your Approach

The HDA API supports multiple access methods. Choose the one that best matches your workflow:

EODAG (Recommended)

Earth Observation Data Access Gateway - The easiest way to work with DestinE data.

• Fastest setup - automatic authentication and configuration

• Unified interface - works with 40+ data providers

• Easy downloads - built-in download management

See also

Learn More: EODAG Documentation for advanced usage patterns

PySTAC Client

STAC ecosystem integration for workflows already using STAC standards.

• STAC-compliant - integrates with existing STAC workflows

• Standards-based - works with any STAC-compliant service

• Flexible - full control over STAC API features

See also

Learn More: PySTAC Client Documentation for advanced STAC operations

cURL/REST API

Direct HTTP access for any programming language or command-line usage

• Universal - works in any programming language

• Transparent - see exactly what’s happening

• Scriptable - perfect for automation and debugging

Step 1: Setup Authentication

EODAG (Recommended)

Earth Observation Data Access Gateway - The easiest way to work with DestinE data

# Install EODAG
pip install eodag

from eodag import EODataAccessGateway
import os

# Setup credentials (use environment variables)
os.environ['EODAG_DEDL_AUTH_CREDENTIALS_USERNAME'] = 'your_desp_username'
os.environ['EODAG_DEDL_AUTH_CREDENTIALS_PASSWORD'] = 'your_desp_password'

# Initialize EODAG with DestinE provider
dag = EODataAccessGateway()
dag.set_preferred_provider("dedl")

print("EODAG configured for DestinE!")

PySTAC Client

STAC-compliant access for advanced users and custom workflows.

# Install PySTAC and destine-auth
pip install pystac-client destine-auth

import pystac_client
from destine_auth import AuthHandler

# Get token automatically
auth = AuthHandler(username="your_desp_username", password="your_desp_password")
token = auth.get_token()
headers = {'Authorization': f'Bearer {token}'}         # Open STAC catalog
catalog = pystac_client.Client.open(
    "https://hda.data.destination-earth.eu/stac/v2",
    headers=headers
)

print("PySTAC catalog connected!")

cURL

Direct HTTP access for any programming language or command-line usage.

The authentication flow has been simplified here to use the destine-auth package, which handles token management for you. You can see the full flow in the Authentication & Quotas guide.

# Install destine-auth for easy token management
pip install destine-auth

# Get token using destine-auth (recommended)
TOKEN=$(python -c "from destine_auth import AuthHandler; print(AuthHandler(username='your_desp_username', password='your_desp_password').get_token())")

# Test connection
curl -H "Authorization: Bearer $TOKEN" "https://hda.data.destination-earth.eu/stac/v2/collections"

echo "HDA API connected!"

Step 2: Discover Available Datasets

Find out what datasets are available in the DestinE Data Portfolio (no authentication required).

EODAG

# List available product types (no auth needed)
product_types = dag.list_product_types(provider='dedl')

print(f"📊 Found {len(product_types)} dataset types available:")
for product_type in product_types[:5]:  # Show first 5
    print(f"  • {product_type}")

PySTAC

# List collections
collections = list(catalog.get_collections())

print(f"📊 Found {len(collections)} collections available:")
for collection in collections[:5]:  # Show first 5
    print(f"  • {collection.id}: {collection.title}")

cURL

# List collections (no auth needed)
curl "https://hda.data.destination-earth.eu/stac/v2/collections"

Step 3: Search for Specific Data

Important

Authentication Required: Starting from this step, you need authentication to search for items and download data.

Find Sentinel-2 data over Paris in July 2024:

EODAG

# Define Paris bounding box
paris_extent = {
    'lonmin': 2.2,   # west
    'lonmax': 2.4,   # east
    'latmin': 48.8,  # south
    'latmax': 49.0   # north
}

# Search for Sentinel-2 data
search_results = dag.search(
    productType="S2_MSI_L2A",
    geom=paris_extent,
    start="2024-07-01",
    end="2024-07-31"
)

print(f"Found {len(search_results)} Sentinel-2 scenes")

product = search_results[0]
print(f"Date: {product.properties.get('startTimeFromAscendingNode')}")
print(f"Cloud cover: {product.properties.get('cloudCover')}%")

PySTAC

# Search for items
search = catalog.search(
    collections=["EO.ESA.DAT.SENTINEL-2.MSI.L2A"],
    bbox=[2.2, 48.8, 2.4, 49.0],
    datetime="2024-07-01/2024-07-31"
)

items = list(search.items())
print(f"Found {len(items)} items")

# Show details of first item
item = items[0]
print(f"Date: {item.datetime}")
print(f"Cloud cover: {item.properties.get('eo:cloud_cover')}%")

cURL

# Search for data
curl -H "Authorization: Bearer $TOKEN" \
 "https://hda.data.destination-earth.eu/stac/v2/search?collections=EO.ESA.DAT.SENTINEL-2.MSI.L2A&bbox=2.2,48.8,2.4,49.0&datetime=2024-07-01T00:00:00Z/2024-07-31T00:00:00Z&limit=5"

Step 4: Access and Download Data

Get the actual data files locally or access them directly in your analysis environment.

EODAG

# Install EODAG Cube. Required for xarray support
pip install eodag-cube

# Download first product
product = search_results[0]

# Get thumbnail for quick preview
quicklook_path = product.get_quicklook()
print(f"Preview URL: {quicklook_path}")

# Load into xarray for analysis
xarray_dict = product.to_xarray()
print("Data loaded into xarray!")

# Download to local directory
downloaded_path = product.download()
print(f"Downloaded to: {downloaded_path}")

PySTAC

import requests

item = items[0]

# Get thumbnail for quick preview
if 'thumbnail' in item.assets:
    thumbnail_url = item.assets['thumbnail'].href

    response = requests.get(thumbnail_url, headers=headers)
    with open(f"{item.id}_thumbnail.jpg", "wb") as f:
        f.write(response.content)

    print(f"Downloaded thumbnail: {item.id}_thumbnail.jpg")

🔧 cURL

# Get item details first
ITEM_ID="your-item-id"  # From search results

# Download thumbnail
curl -H "Authorization: Bearer $TOKEN" \
  "https://hda.data.destination-earth.eu/stac/v2/collections/EO.ESA.DAT.SENTINEL-2.MSI.L2A/items/$ITEM_ID" | \
  jq -r '.assets.thumbnail.href' | \
  xargs curl -H "Authorization: Bearer $TOKEN" -o thumbnail.jpg

echo "Downloaded thumbnail.jpg"

Step 5: Work with the Data

Load and visualize your downloaded data:

import xarray as xr
import matplotlib.pyplot as plt

# Example: Open and plot downloaded data
# dataset = xr.open_dataarray("downloaded_file.tif")
#
# # Quick visualization
# plt.figure(figsize=(10, 8))
# dataset.plot(cmap='viridis', robust=True)
# plt.title("Sentinel-2 Data over Paris")
# plt.show()

print("Ready to analyze your DestinE data!")

Next Steps

Having successfully connected to the HDA API and accessed DestinE data, here are the possible learning paths to choose from:

Complete Guides

• Authentication & Quotas - Advanced authentication and security

• Data Discovery - Advanced search and filtering

• Data Access - Bulk downloads and cloud-optimized access

Interactive Examples

• HDA Tutorials - Jupyter notebooks with real workflows

• GitHub Examples - Complete code repositories

Pro Tips for Success

• EODAG users: Start with dag.list_product_types() to see what’s available

• PySTAC users: Use catalog.get_collections() for discovery first

• cURL users: Check out the interactive API docs for request examples

• All users: Use small bounding boxes and short time ranges for initial testing