Skip to content
Back to search

phidown

Manage, search, and download Earth Observation data with Φ-down from Copernicus missions with ease and efficiency.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ESA-PhiLab/phidown with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ESA-PhiLab/phidown'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/esa-philab--phidown/badge.svg)](/listings/esa-philab--phidown)

HTML

<a href="/listings/esa-philab--phidown"><img src="/api/listings/esa-philab--phidown/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

From PyPI

pip install phidown

Optional dependency groups

# Visualization and mapping tools
pip install "phidown[viz]"

# AIS-related utilities
pip install "phidown[ais]"

# Jupyter environment helpers
pip install "phidown[jupyter_env]"

# Development and docs
pip install "phidown[dev,docs]"

From source (uv)

git clone https://github.com/ESA-PhiLab/phidown.git
cd phidown
uv sync

Requirements: - Python 3.10+ - `s5cmd` available on your `PATH` for S3 downloads

As a Codex plugin

This repository now ships a repo-local Codex plugin and marketplace:

- `plugins/phidown/` - `.agents/plugins/marketplace.json`

To install it from this repository:

1. Clone the repository and open the repo root in Codex. 2. Restart Codex if the plugin directory was already open before these files existed, so Codex reloads the repo marketplace. 3. Open the Codex plugin directory and select the `Phidown Plugins` marketplace. 4. Install the `Phidown Downloader` plugin. 5. Start a prompt such as:

Use $phidown to search Copernicus products and download data via phidown CLI or Python.

If you manage marketplaces from the Codex CLI, you can also add this repository as a local marketplace root:

codex plugin marketplace add /absolute/path/to/phidown

Local agent skills

Install the bundled phidown guidance for local agentic tools:

phidown skill add                 # Codex: $CODEX_HOME/skills/phidown
phidown skill add --engine claude # Claude Code: ~/.claude/skills/phidown
phidown skill add --engine cursor # Cursor project rule: .cursor/rules/phidown.mdc
phidown skill add --engine all

Remove the local files with the matching command:

phidown skill remove --engine all

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

readme.md · README · 268 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ![Phi-Down Logo](./assets/banner.png)
  2. [![PyPI](https://img.shields.io/pypi/v/phidown.svg)](https://pypi.org/project/phidown/)
  3. [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
  4. [![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://esa-philab.github.io/phidown)
  5. [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15332053.svg)](https://doi.org/10.5281/zenodo.15332053)
  6. # phidown
  7. `phidown` is a Python package and CLI for searching and downloading Copernicus Data Space products and PhiSat-2 INSULA platform files.
  8. It supports:
  9. - Product search through the CDSE STAC API (collection, dates, AOI, orbit direction, cloud cover). Results keep the OData-style columns (`Id`, `Name`, `S3Path`, `ContentDate`, `GeoFootprint`, `Attributes`). Queries that STAC cannot answer fully use OData instead: name patterns, Sentinel-1 RAW and non-COG GRD, collections outside Sentinel-1/2/3/5P/6 and COP-DEM, large Sentinel-2 L2A pages, and most `attributes`.
  10. - Product download through S3 (`s5cmd`).
  11. - PhiSat-2 search and download through the INSULA platform.
  12. - Sentinel-1 SLC burst search and burst coverage analysis workflows.
  13. ## Installation
  14. ### From PyPI
  15. ```bash
  16. pip install phidown
  17. ```
  18. ### Optional dependency groups
  19. ```bash
  20. # Visualization and mapping tools
  21. pip install "phidown[viz]"
  22. # AIS-related utilities
  23. pip install "phidown[ais]"
  24. # Jupyter environment helpers
  25. pip install "phidown[jupyter_env]"
  26. # Development and docs
  27. pip install "phidown[dev,docs]"
  28. ```
  29. ### From source (uv)
  30. ```bash
  31. git clone https://github.com/ESA-PhiLab/phidown.git
  32. cd phidown
  33. uv sync
  34. ```
  35. Requirements:
  36. - Python 3.10+
  37. - `s5cmd` available on your `PATH` for S3 downloads
  38. ### As a Codex plugin
  39. This repository now ships a repo-local Codex plugin and marketplace:
  40. - `plugins/phidown/`
  41. - `.agents/plugins/marketplace.json`
  42. To install it from this repository:
  43. 1. Clone the repository and open the repo root in Codex.
  44. 2. Restart Codex if the plugin directory was already open before these files existed, so Codex reloads the repo marketplace.
  45. 3. Open the Codex plugin directory and select the `Phidown Plugins` marketplace.
  46. 4. Install the `Phidown Downloader` plugin.
  47. 5. Start a prompt such as:
  48. ```text
  49. Use $phidown to search Copernicus products and download data via phidown CLI or Python.
  50. ```
  51. If you manage marketplaces from the Codex CLI, you can also add this repository as a local marketplace root:
  52. ```bash
  53. codex plugin marketplace add /absolute/path/to/phidown
  54. ```
  55. ### Local agent skills
  56. Install the bundled phidown guidance for local agentic tools:
  57. ```bash
  58. phidown skill add # Codex: $CODEX_HOME/skills/phidown
  59. phidown skill add --engine claude # Claude Code: ~/.claude/skills/phidown
  60. phidown skill add --engine cursor # Cursor project rule: .cursor/rules/phidown.mdc
  61. phidown skill add --engine all
  62. ```
  63. Remove the local files with the matching command:
  64. ```bash
  65. phidown skill remove --engine all
  66. ```
  67. ## Credentials
  68. Create a shared `.s5cfg` file for both CDSE and PhiSat-2. Keep the existing
  69. `[default]` block for CDSE, then insert the `[phisat2]` block directly below
  70. it in the same file:
  71. ```ini
  72. [default]
  73. aws_access_key_id = your_access_key
  74. aws_secret_access_key = your_secret_key
  75. aws_region = eu-central-1
  76. host_base = eodata.dataspace.copernicus.eu
  77. host_bucket = eodata.dataspace.copernicus.eu
  78. use_https = true
  79. check_ssl_certificate = true
  80. [phisat2]
  81. username = your_email@example.com
  82. password = your_password
  83. base_url = https://phisat2.insula.earth
  84. api_base = https://phisat2.insula.earth/secure/api/v2.0
  85. authorization_endpoint = https://identity.insula.earth/realms/phisat2/protocol/openid-connect/auth
  86. token_endpoint = https://identity.insula.earth/realms/phisat2/protocol/openid-connect/token
  87. redirect_uri = http://localhost:9207/auth
  88. client_id = api-client
  89. ```
  90. If credentials are not removed automatically, revoke them in the CDSE S3 Credentials Manager:
  91. <https://eodata-s3keysmanager.dataspace.copernicus.eu/panel/s3-credentials>
  92. `phidown --reset` updates only the active provider section, so CDSE and
  93. PhiSat-2 credentials can coexist safely in one file.
  94. ## Quick Start (Python API)
  95. ```python
  96. from phidown.search import CopernicusDataSearcher
  97. searcher = CopernicusDataSearcher()
  98. searcher.query_by_filter(
  99. collection_name="SENTINEL-1",
  100. product_type="SLC",
  101. start_date="2024-05-01T00:00:00",
  102. end_date="2024-05-31T23:59:59",
  103. top=50,
  104. )
  105. df = searcher.execute_query()
  106. print(f"Results: {len(df)}")
  107. print(searcher.display_results(top_n=5))
  108. ```
  109. ### Sentinel-1 burst mode
  110. ```python
  111. from phidown.search import CopernicusDataSearcher
  112. searcher = CopernicusDataSearcher()
  113. searcher.query_by_filter(
  114. burst_mode=True,
  115. swath_identifier="IW2",
  116. polarisation_channels="VV",
  117. orbit_direction="DESCENDING",
  118. start_date="2024-08-02T00:00:00",
  119. end_date="2024-08-15T00:00:00",
  120. top=20,
  121. count=True,
  122. )
  123. df = searcher.execute_query()
  124. print(f"Bursts found: {len(df)}")
  125. ```
  126. ### PhiSat-2 search
  127. ```python
  128. from phidown.search import CopernicusDataSearcher
  129. searcher = CopernicusDataSearcher()
  130. searcher.query_by_filter(
  131. collection_name="PHISAT-2",
  132. product_type="L1",
  133. aoi_wkt="POLYGON((-3.90 40.30, -3.50 40.30, -3.50 40.70, -3.90 40.70, -3.90 40.30))",
  134. start_date="2026-05-01T00:00:00Z",
  135. end_date="2026-05-30T23:59:59Z",
  136. top=10,
  137. config_file=".s5cfg",
  138. )
  139. df = searcher.execute_query()
  140. print(df[["Id", "coverage", "Name", "ContentDate", "DownloadUrl"]].head())
  141. ```
  142. ## Command Line Interface
  143. Show available options:
  144. ```bash
  145. phidown --help
  146. ```
  147. Common commands:
  148. ```bash
  149. # Download by product name
  150. phidown --name S1A_IW_GRDH_1SDV_20141031T161924_20141031T161949_003076_003856_634E.SAFE -o ./data
  151. # Download by S3 path
  152. phidown --s3path /eodata/Sentinel-1/SAR/IW_GRDH_1S/2024/05/03/... -o ./data
  153. # List products for AOI/date filters
  154. phidown --list --collection SENTINEL-1 --product-type GRD --bbox -5 40 5 45 --start-date 2024-01-01T00:00:00 --end-date 2024-01-31T23:59:59
  155. # Search PhiSat-2 products
  156. phidown list --provider phisat2 --filter SESSION_ID_12345
  157. # Download one PhiSat-2 product by exact filename or unique search token
  158. phidown --provider phisat2 --name SESSION_ID_12345 -o ./data
  159. # Burst coverage analysis
  160. phidown --burst-coverage --bbox -5 40 5 45 --start-date 2024-08-02T00:00:00 --end-date 2024-08-15T23:59:59 --polarisation VV --format json
  161. ```
  162. ## Documentation
  163. Full documentation: <https://esa-philab.github.io/phidown>
  164. Useful entry points:
  165. - Getting started: <https://esa-philab.github.io/phidown/getting_started.html>
  166. - User guide: <https://esa-philab.github.io/phidown/user_guide.html>
  167. - PhiSat-2 reference: <https://esa-philab.github.io/phidown/phisat2_reference.html>
  168. - API reference: <https://esa-philab.github.io/phidown/api_reference.html>
  169. - Burst mode guide: <https://esa-philab.github.io/phidown/sentinel1_burst_mode.html>
  170. Notebook examples:
  171. - `./how_to_start.ipynb`
  172. - `./notebooks/`
  173. ## Contributing
  174. Contributions are welcome. Please:
  175. 1. Fork the repository.
  176. 2. Create a feature branch.
  177. 3. Add tests and documentation updates where relevant.
  178. 4. Open a pull request with a clear description.
  179. For bugs and questions, use:
  180. - Issues: <https://github.com/ESA-PhiLab/phidown/issues>
  181. - Discussions: <https://github.com/ESA-PhiLab/phidown/discussions>
  182. ## Citation
  183. If you use `phidown` in research, please cite:
  184. > Del Prete, R. (2025). *phidown: A Python Tool for Streamlined Data Downloading from CDSE*. Zenodo. <https://doi.org/10.5281/zenodo.15332053>
  185. BibTeX:
  186. ```bibtex
  187. @misc{delprete2025phidown,
  188. author = {Del Prete, Roberto},
  189. title = {phidown: A Python Tool for Streamlined Data Downloading from CDSE},
  190. year = {2025},
  191. publisher = {Zenodo},
  192. doi = {10.5281/zenodo.15332053},
  193. url = {https://doi.org/10.5281/zenodo.15332053}
  194. }
  195. ```
  196. ## License
  197. This project is licensed under the Apache License 2.0.
  198. See `LICENSE` for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.