PhiSat-2 Reference Guide

Note

New in version 0.1.27: Phi-Down supports PhiSat-2 INSULA search and download workflows through both the Python API and CLI.

Overview

PhiSat-2 support uses the INSULA platform for product discovery and HTTP downloads. CDSE products still use the Copernicus Data Space S3 workflow, while PhiSat-2 products use the phisat2 provider and the [phisat2] credential section in the shared .s5cfg file.

Supported Workflows

• Search platform files by session ID, exact filename, filename fragment, or another unique text token.

• Search catalogue products with product type, AOI, and date filters through the common CopernicusDataSearcher API.

• Download one product by exact filename, unique token, resolved product ID, or normalized download URL.

• Reuse the same credential file as CDSE without overwriting the [default] S3 section.

Credentials

Create a shared .s5cfg file with both provider sections:

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key
aws_region = eu-central-1
host_base = eodata.dataspace.copernicus.eu
host_bucket = eodata.dataspace.copernicus.eu
use_https = true
check_ssl_certificate = true

[phisat2]
username = your_email@example.com
password = your_password
base_url = https://phisat2.insula.earth
api_base = https://phisat2.insula.earth/secure/api/v2.0
authorization_endpoint = https://identity.insula.earth/realms/phisat2/protocol/openid-connect/auth
token_endpoint = https://identity.insula.earth/realms/phisat2/protocol/openid-connect/token
redirect_uri = http://localhost:9207/auth
client_id = api-client

username and password are the required PhiSat-2 values. Endpoint values normally stay at their defaults. When --reset is used with --provider phisat2, Phi-Down rewrites only the [phisat2] section.

Python API

Use PhiSat2Searcher directly for platform-file searches:

from phidown import PhiSat2Searcher

searcher = PhiSat2Searcher(config_file=".s5cfg")
results = searcher.query("SESSION_ID_12345", results_per_page=10)
print(results[["Id", "Name", "DownloadUrl"]].head())

output_path = searcher.download_by_name(
    "SESSION_ID_12345",
    output_dir="./data",
    retry_count=3,
)

Use the common searcher when you want collection-style search filters:

from phidown import CopernicusDataSearcher

searcher = CopernicusDataSearcher()
searcher.query_by_filter(
    collection_name="PHISAT-2",
    product_type="L1",
    aoi_wkt="POLYGON((-3.90 40.30, -3.50 40.30, -3.50 40.70, -3.90 40.70, -3.90 40.30))",
    start_date="2026-05-01T00:00:00Z",
    end_date="2026-05-30T23:59:59Z",
    top=10,
    config_file=".s5cfg",
)
results = searcher.execute_query()

print(results[["Id", "coverage", "Name", "ContentDate", "DownloadUrl"]].head())

CLI

List matching PhiSat-2 products:

phidown list --provider phisat2 --filter SESSION_ID_12345

Download a PhiSat-2 product by exact filename or unique search token:

phidown --provider phisat2 --name SESSION_ID_12345 -o ./data

Refresh only the PhiSat-2 credential section:

phidown --provider phisat2 --name SESSION_ID_12345 -o ./data --reset

Result Columns

PhiSat-2 result frames normalize common columns where available:

PhiSat-2 Result Columns

Column	Description
Id	INSULA platform file or catalogue feature ID
Name	Product filename or normalized title
ContentLength	Product size in bytes when provided by INSULA
ContentDate	Product acquisition date range when provided
GeoFootprint	Product footprint as GeoJSON geometry
DownloadUrl	Normalized INSULA download URL
Provider	Always phisat2 for PhiSat-2 results
coverage	AOI coverage percentage when AOI and footprint exist

Limitations

• PhiSat-2 searches do not support Sentinel-1 burst mode.

• --s3path is CDSE-only; PhiSat-2 downloads use INSULA HTTP URLs.

• phidown list --provider phisat2 requires --filter.

• PhiSat-2 authentication requires InsulaWorkflowClient.

API Objects

PhiSat-2 INSULA search and download helpers.

class phidown.phisat2.PhiSat2Config(username, password, base_url='https://phisat2.insula.earth', api_base='https://phisat2.insula.earth/secure/api/v2.0', authorization_endpoint='https://identity.insula.earth/realms/phisat2/protocol/openid-connect/auth', token_endpoint='https://identity.insula.earth/realms/phisat2/protocol/openid-connect/token', redirect_uri='http://localhost:9207/auth', client_id='api-client')

Bases: object

username: str

password: str

base_url: str = 'https://phisat2.insula.earth'

api_base: str = 'https://phisat2.insula.earth/secure/api/v2.0'

authorization_endpoint: str = 'https://identity.insula.earth/realms/phisat2/protocol/openid-connect/auth'

token_endpoint: str = 'https://identity.insula.earth/realms/phisat2/protocol/openid-connect/token'

redirect_uri: str = 'http://localhost:9207/auth'

client_id: str = 'api-client'

__init__(username, password, base_url='https://phisat2.insula.earth', api_base='https://phisat2.insula.earth/secure/api/v2.0', authorization_endpoint='https://identity.insula.earth/realms/phisat2/protocol/openid-connect/auth', token_endpoint='https://identity.insula.earth/realms/phisat2/protocol/openid-connect/token', redirect_uri='http://localhost:9207/auth', client_id='api-client')

phidown.phisat2.ensure_phisat2_config(config_file, reset=False)

Ensure the shared config file contains a PhiSat-2 credential section.

Return type:

None

class phidown.phisat2.PhiSat2Searcher(config_file='.s5cfg')

Bases: object

Search and download PhiSat-2 products from INSULA.

__init__(config_file='.s5cfg')

query(filter_text, *, results_per_page=50, reset_config=False)

Search PhiSat-2 platform files by free-text filter.

Return type:

DataFrame

query_catalogue(product_type='L1', *, aoi_wkt=None, start_date=None, end_date=None, results_per_page=50, page=0, ref_data_collection='phisat24e55ba83dd304ea9b018b65e9b17a7de', reset_config=False)

Search PhiSat-2 catalogue products with date and AOI filters.

Return type:

DataFrame

query_by_name(product_name, *, results_per_page=50, reset_config=False)

Search by filename and prefer exact filename matches.

Return type:

DataFrame

resolve_product(product_name, *, results_per_page=50, reset_config=False)

Resolve a product name or unique search token to one platform file.

Return type:

Series

download_product(product_id, output_dir, *, file_name=None, reset_config=False, show_progress=True, retry_count=1, connect_timeout=30.0, read_timeout=900.0, backoff_base=2.0, backoff_max=60.0, overwrite=False, unzip=False)

Download one PhiSat-2 platform file by ID.

Return type:

str

download_url(download_url, output_dir, *, file_name=None, reset_config=False, show_progress=True, retry_count=1, connect_timeout=30.0, read_timeout=900.0, backoff_base=2.0, backoff_max=60.0, overwrite=False, unzip=False)

Download one PhiSat-2 product from a normalized download URL.

Return type:

str

download_by_name(product_name, output_dir, *, results_per_page=50, reset_config=False, show_progress=True, retry_count=1, connect_timeout=30.0, read_timeout=900.0, backoff_base=2.0, backoff_max=60.0, overwrite=False, unzip=False)

Resolve and download one PhiSat-2 platform file by filename or unique token.

Return type:

str