{"id":47724123,"url":"https://github.com/vtvito/cdse-client","last_synced_at":"2026-04-02T20:03:58.789Z","repository":{"id":332125571,"uuid":"1125503121","full_name":"VTvito/cdse-client","owner":"VTvito","description":"Python client for Copernicus Data Space Ecosystem (CDSE) - Modern replacement for sentinelsat with support for Sentinel-1/2/3/5P data search, download, and processing","archived":false,"fork":false,"pushed_at":"2026-02-13T14:54:00.000Z","size":2161,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-13T23:26:04.648Z","etag":null,"topics":["cdse","copernicus","data-download","geospatial","gis","open-data","remote-sensing","satellite-data","satellite-imagery","sentinel","sentinel-2","sentinelsat"],"latest_commit_sha":null,"homepage":"https://vtvito.github.io/cdse-client/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VTvito.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T21:06:06.000Z","updated_at":"2026-02-13T14:54:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/VTvito/cdse-client","commit_stats":null,"previous_names":["vtvito/cdse-client"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/VTvito/cdse-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTvito%2Fcdse-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTvito%2Fcdse-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTvito%2Fcdse-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTvito%2Fcdse-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VTvito","download_url":"https://codeload.github.com/VTvito/cdse-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VTvito%2Fcdse-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31314833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdse","copernicus","data-download","geospatial","gis","open-data","remote-sensing","satellite-data","satellite-imagery","sentinel","sentinel-2","sentinelsat"],"created_at":"2026-04-02T20:03:55.665Z","updated_at":"2026-04-02T20:03:58.784Z","avatar_url":"https://github.com/VTvito.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cdse-client\n\n[![PyPI version](https://badge.fury.io/py/cdse-client.svg)](https://badge.fury.io/py/cdse-client)\n[![Python](https://img.shields.io/pypi/pyversions/cdse-client.svg)](https://pypi.org/project/cdse-client/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Downloads](https://img.shields.io/pypi/dm/cdse-client)](https://pypi.org/project/cdse-client/)\n[![CI](https://github.com/VTvito/cdse-client/actions/workflows/ci.yml/badge.svg)](https://github.com/VTvito/cdse-client/actions)\n\n**Python client for Copernicus Data Space Ecosystem (CDSE)** — a modern replacement for workflows previously built around `sentinelsat`.\n\n`sentinelsat` was built for DHuS/SciHub (now closed) and is archived; it does not support CDSE downloads. `cdse-client` targets CDSE's APIs (STAC for search, OData/Zipper for downloads).\n\nHighlights:\n\n- Search products via STAC\n- Download products via OData/Zipper (with progress bars)\n- Optional extras for geocoding/GeoPandas, async downloads, and raster processing\n- Type hints (PEP 561 / `py.typed`)\n- **NEW**: Auto-refresh Bearer tokens, resilient retries, production logging\n- **NEW**: Explicit timeouts on all HTTP requests\n\nCompatibility: Python \u003e= 3.9\n\n### Why cdse-client?\n\n| Feature | sentinelsat | cdse-client |\n|---------|------------|-------------|\n| Works with CDSE downloads | No | Yes |\n| Async downloads | No | Optional (`cdse-client[async]`) |\n| Built-in processing helpers | No | Optional (`cdse-client[processing]`) |\n| City name search | No | Optional (`cdse-client[geo]`) |\n| Type hints | Partial | Yes |\n| Maintenance status | Archived | Active |\n\n## Installation\n\n```bash\npip install cdse-client              # Core\npip install cdse-client[geo]         # + shapely, geopandas, geopy\npip install cdse-client[dataframe]   # + pandas\npip install cdse-client[processing]  # + rasterio, numpy, pillow, matplotlib, shapely\npip install cdse-client[async]       # + aiohttp, aiofiles\npip install cdse-client[all]         # Everything\n```\n\n## Setup\n\n1. Register at [Copernicus Data Space](https://dataspace.copernicus.eu/)\n2. Create OAuth2 credentials in [Account Settings](https://dataspace.copernicus.eu/profile)\n3. Configure credentials using **one** of the methods below:\n\n### Option A: Environment variables (recommended for production)\n\n**macOS/Linux (bash/zsh)**\n```bash\nexport CDSE_CLIENT_ID=\"your-client-id\"\nexport CDSE_CLIENT_SECRET=\"your-client-secret\"\n```\n\n**Windows (PowerShell)**\n```powershell\n$env:CDSE_CLIENT_ID = \"your-client-id\"\n$env:CDSE_CLIENT_SECRET = \"your-client-secret\"\n```\n\n### Option B: `.env` file (recommended for development)\n\nCopy the example file and fill in your credentials:\n```bash\ncp .env.example .env\n# Edit .env with your credentials\n```\n\nThe `.env` file format:\n```\nCDSE_CLIENT_ID=your-client-id\nCDSE_CLIENT_SECRET=your-client-secret\n```\n\n\u003e **Note**: The `.env` file is automatically ignored by git. Never commit credentials.\n\n## Features\n\n- Smart search: STAC API with time range, bbox/geometry, cloud cover\n- Downloads: OData/Zipper with progress bars, checksums, quicklooks\n- Export: DataFrame / GeoJSON / GeoDataFrame\n- Optional extras: geocoding, async downloads, raster processing utilities\n- CLI: search/download/collections\n\n## Quick start\n\n### Basic Search \u0026 Download\n\n```python\nfrom cdse import CDSEClient\n\nclient = CDSEClient(output_dir=\"./downloads\")  # Uses CDSE_CLIENT_ID and CDSE_CLIENT_SECRET\n\n# Search Sentinel-2 products over Milan\nproducts = client.search(\n    bbox=[9.0, 45.0, 9.5, 45.5],\n    start_date=\"2024-01-01\",\n    end_date=\"2024-01-31\",\n    collection=\"sentinel-2-l2a\",\n    cloud_cover_max=20,\n    limit=5\n)\n\n# Download all results\nfor product in products:\n    client.download(product)\n```\n\n### Search by City Name\n\n```python\nfrom cdse import CDSEClient, get_city_bbox\n\nclient = CDSEClient()\n\n# Get bounding box for any city\nbbox = get_city_bbox(\"Paris, France\")\n\nproducts = client.search(\n    bbox=bbox,\n    start_date=\"2024-06-01\",\n    end_date=\"2024-06-30\",\n    collection=\"sentinel-2-l2a\"\n)\n```\n\n### Async Downloads\n\n```python\nimport asyncio\nfrom cdse import CDSEClientAsync\n\n\nasync def main():\n    async with CDSEClientAsync(output_dir=\"./downloads\", max_concurrent=3) as client:\n        products = await client.search(\n            bbox=[9.0, 45.0, 9.5, 45.5],\n            start_date=\"2024-01-01\",\n            end_date=\"2024-01-31\",\n            collection=\"sentinel-2-l2a\",\n            limit=10,\n        )\n        await client.download_all(products)\n\n\nasyncio.run(main())\n```\n\nFor raster processing examples (NDVI, band extraction, previews), see the Processing section below.\n\n## Search methods\n\n```python\n# By bounding box\nproducts = client.search(bbox=[lon_min, lat_min, lon_max, lat_max], ...)\n\n# By geographic point\nproducts = client.search_by_point(lon=9.19, lat=45.46, buffer_km=10, ...)\n\n# By city name (requires [geo])\nproducts = client.search_by_city(city_name=\"Milano, Italia\", ...)\n\n# By product name (OData catalogue)\nproducts = client.search_by_name(\"S2A_MSIL2A_20240115T102351...\", exact=True)\n\n# By UUID (OData catalogue)\nproduct = client.search_by_id(\"a1b2c3d4-e5f6...\")\n```\n\nNote: `search()` returns STAC results; product identifiers there are not guaranteed to be OData UUIDs. If you need a UUID, use `search_by_name(..., exact=True)`.\n\n**Collections**: `sentinel-1-grd`, `sentinel-2-l1c`, `sentinel-2-l2a`, `sentinel-3-olci`, `sentinel-3-slstr`, `sentinel-5p-l2`\n\n## Download methods\n\n```python\n# Single product\nclient.download(product, output_dir=\"./downloads\")\n\n# Multiple products (parallel)\nclient.download_all(products, parallel=True, max_workers=4)\n\n# With checksum verification\nclient.download_with_checksum(product)\n\n# Quicklook preview only\nclient.download_quicklook(product)\nclient.download_all_quicklooks(products)\n```\n\n## Data export (sentinelsat compatible)\n\n```python\n# DataFrame for sorting/filtering\ndf = client.to_dataframe(products)\ndf.sort_values('cloud_cover').to_csv(\"products.csv\")\n\n# GeoJSON footprints\ngeojson = client.to_geojson(products)\n\n# GeoDataFrame for spatial analysis (requires [geo])\ngdf = client.to_geodataframe(products)\ngdf.plot()\n\n# Total size\nsize_gb = client.get_products_size(products)\n```\n\n## Geometry utilities\n\n```python\nfrom cdse import read_geojson, geojson_to_wkt, bbox_to_geojson\n\ngeojson = read_geojson(\"area.geojson\")\nwkt = geojson_to_wkt(geojson)\ngeojson = bbox_to_geojson([9.0, 45.0, 9.5, 45.5])\n```\n\n## Processing (optional)\n\nInstall:\n\n```bash\npip install cdse-client[processing]\n```\n\nExample:\n\n```python\nfrom cdse.processing import calculate_ndvi, crop_and_stack, preview_product\n\n# Extract bands, crop to AOI, stack into a GeoTIFF\nstack_path = crop_and_stack(\n    safe_path=\"S2A_MSIL2A_20240115.zip\",\n    bbox=[9.15, 45.45, 9.25, 45.55],\n    bands=[\"B04\", \"B03\", \"B02\", \"B08\"],\n    resolution=10,\n)\n\n# NDVI from band files\nndvi = calculate_ndvi(nir_path=\"B08.tif\", red_path=\"B04.tif\")\n\n# Quick preview (writes a PNG)\npreview_product(safe_path=\"S2A_MSIL2A_20240115.zip\", output_path=\"preview.png\")\n```\n\n## Async (optional)\n\nInstall:\n\n```bash\npip install cdse-client[async]\n```\n\nExample:\n\n```python\nimport asyncio\n\nfrom cdse import CDSEClientAsync\n\n\nasync def main() -\u003e None:\n    async with CDSEClientAsync(output_dir=\"./downloads\", max_concurrent=3) as client:\n        products = await client.search(\n            bbox=[9.0, 45.0, 9.5, 45.5],\n            start_date=\"2024-01-01\",\n            end_date=\"2024-01-31\",\n            collection=\"sentinel-2-l2a\",\n            cloud_cover_max=20,\n            limit=3,\n        )\n        # WARNING: downloads can be large\n        # paths = await client.download_all(products)\n\n\nasyncio.run(main())\n```\n\n## CLI\n\n```bash\ncdse --help\ncdse collections\n\n# Search\ncdse search --bbox 9.0,45.0,9.5,45.5 -s 2024-01-01 -e 2024-01-31 -c 20 -l 5\n\n# Download by name/UUID\ncdse download --name S2A_MSIL2A_20240115T102351...\ncdse download --uuid a1b2c3d4-e5f6-... --checksum\ncdse download --uuid a1b2c3d4-e5f6-... --quicklook\n```\n\n## Documentation\n\n- Site: https://vtvito.github.io/cdse-client/\n- Migration guide: https://vtvito.github.io/cdse-client/migration/\n- Examples: examples/\n\n## Migration from sentinelsat\n\n| sentinelsat | cdse-client |\n|-------------|-------------|\n| `SentinelAPI(user, password)` | `CDSEClient(client_id, client_secret)` (OAuth2) |\n| `api.query(...)` | `client.search(...)` |\n| `api.download(...)` | `client.download(product)` |\n| `api.download_all(...)` | `client.download_all(products)` |\n| `api.to_dataframe(...)` | `client.to_dataframe(products)` |\n| `api.to_geojson(...)` | `client.to_geojson(products)` |\n| `api.to_geodataframe(...)` | `client.to_geodataframe(products)` |\n\n## Contributing\n\nContributions welcome. See:\n\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n- Issues: https://github.com/VTvito/cdse-client/issues\n- Discussions: https://github.com/VTvito/cdse-client/discussions\n\n## Support \u0026 Community\n\n- Bug reports: https://github.com/VTvito/cdse-client/issues\n- Questions/ideas: https://github.com/VTvito/cdse-client/discussions\n- Documentation: https://vtvito.github.io/cdse-client/\n\n## Resources\n\n- Copernicus Data Space Ecosystem: https://dataspace.copernicus.eu/\n- CDSE API documentation: https://documentation.dataspace.copernicus.eu/\n- STAC browser: https://dataspace.copernicus.eu/browser/\n\n## Disclaimer\n\nThis is an **unofficial** client library and is not affiliated with, endorsed by, or connected to ESA, the European Commission, or the Copernicus Programme.\n\nCopernicus Data Space Ecosystem and Sentinel data are provided by ESA and the European Commission. Users must:\n\n1. Register at [dataspace.copernicus.eu](https://dataspace.copernicus.eu/)\n2. Comply with the [Terms and Conditions](https://dataspace.copernicus.eu/terms-and-conditions)\n3. Respect [API quotas and fair usage policies](https://documentation.dataspace.copernicus.eu/Quotas.html)\n\nSentinel data is available under a **free, full, and open** data policy for any use, including commercial. See the [Sentinel Data Legal Notice](https://sentinels.copernicus.eu/documents/247904/690755/Sentinel_Data_Legal_Notice).\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtvito%2Fcdse-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvtvito%2Fcdse-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtvito%2Fcdse-client/lists"}