# egms-client

> A small, typed, async Python client for the archive of EGMS, the Copernicus European Ground Motion Service: ground velocity across Europe from Sentinel-1 InSAR, in mm/year. It handles the CLMS service-key login, searches and downloads Ortho L3 tiles and L2A/L2B measurement points, and turns them into mosaics (Cloud-Optimized GeoTIFF), pandas/GeoParquet tables, xarray arrays and vertical/east-west maps.

- Install: `pip install egms-client` (extras: `raster`, `tables`, `xarray`). Python 3.12+.
- Credentials: a CLMS service key, read from `EGMS_SERVICE_KEY_FILE` or `EGMS_SERVICE_KEY`.
  Never put the key in code.
- The archive API is undocumented and fails quietly. Use `EgmsArchive.find` / `fetch` /
  `fetch_tile` instead of building URLs or file names: see "The traps we already fell into"
  in the guide and the rules in the agent skill.
- Units: mm/year; `U < 0` is the ground going down. L3 grids are in EPSG:3035.

## Docs

- [Home](https://agentengineering.it/egms-client/): the guide: what EGMS is, quick start, recipes, the traps, API at a glance
- [Notebooks](https://agentengineering.it/egms-client/notebooks/): three worked examples on real data (Campi Flegrei, Ancona, Bologna)
- [Roadmap](https://agentengineering.it/egms-client/roadmap/): planned work: foundations, time-series analysis, AI features
- [Changelog](https://agentengineering.it/egms-client/changelog/): what changed in each release
- [Contributing](https://agentengineering.it/egms-client/contributing/): how to contribute

## API reference

- [Client](https://agentengineering.it/egms-client/api/client/): An async client over `egms_client.auth` and `egms_client.archive`
- [Client without async](https://agentengineering.it/egms-client/api/sync/): The archive without `async`/`await`, for scripts and notebooks
- [Archive (pure functions)](https://agentengineering.it/egms-client/api/archive/): Searching and downloading from the EGMS archive: Ortho L3 tiles and L2 bursts
- [Authentication](https://agentengineering.it/egms-client/api/auth/): Access tokens from a CLMS service key
- [Mosaics and maps](https://agentengineering.it/egms-client/api/mosaic/): Ortho L3 tiles pasted onto one grid. Needs the `raster` extra
- [Tables and GeoParquet](https://agentengineering.it/egms-client/api/tables/): The CSVs of the archive as tables. Needs the `tables` extra
- [Maps from L2 points](https://agentengineering.it/egms-client/api/decompose/): Maps from L2 points: gridding, and ascending + descending into vertical and east-west
- [Time-series analysis](https://agentengineering.it/egms-client/api/analysis/): What the time series say beyond their mean velocity. Needs the `tables` extra
- [Command line](https://agentengineering.it/egms-client/api/cli/): `egms`: the archive from the command line
- [MCP server](https://agentengineering.it/egms-client/api/mcp/): EGMS as tools for AI agents: an MCP server. Needs the `mcp` extra
- [Errors](https://agentengineering.it/egms-client/api/errors/): EgmsError: the archive answered, but refused

## For agents

- [Full documentation as text](https://agentengineering.it/egms-client/llms-full.txt): every page above, with the API reference rendered from the docstrings
- [Agent skill](https://agentengineering.it/egms-client/skills/egms-client/SKILL.md): how to use the library and the rules the archive enforces, for coding agents

## Optional

- [Source code](https://github.com/agent-engineering-studio/egms-client): the repository
- [EGMS](https://egms.land.copernicus.eu/): the service and its Explorer