diff --git a/Repo-README.-.md b/Repo-README.-.md new file mode 100644 index 0000000..466fbf5 --- /dev/null +++ b/Repo-README.-.md @@ -0,0 +1,96 @@ + + +> Mirrored from `/mnt/DATA/git/emission-api-lib/README.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# emission-api-lib + +`emission-api-lib` is the authoritative draft specification for provider-neutral emission calculation connectors. + +The project defines a shared domain model, provider configuration format, provider capability vocabulary and validation artifacts for integrating multiple emission calculation providers through a stable connector layer. + +## Status + +Draft specification. + +The specification is not stable yet. Breaking changes are expected until the first stable version is released. + +## Purpose + +Direct integrations between specialist applications and individual emission calculation APIs create long-term dependencies on provider-specific request formats, response formats and feature assumptions. + +`emission-api-lib` defines a provider-neutral integration boundary. Applications should be able to express an emission calculation request in a stable domain format, while provider-specific mappings, capabilities and limitations are handled by connector implementations. + +## Repository role + +This repository is authoritative. + +Language-specific repositories implement this specification, but do not define it. + +- `emission-api-lib-java` is the Java reference implementation. +- `emission-api-lib-python` is the Python implementation. +- `emission-api-lib-php` is the PHP implementation. + +All implementation repositories should link back to this repository. + +## Provider scope + +The specification is designed for multiple providers from the beginning. + +A provider is described through XML configuration and machine-readable capability metadata. Implementations may use this information to validate requests, select providers, explain unsupported features and normalize responses. + +## Specification artifacts + +This repository may contain: + +- `schema.json` for the shared domain model +- XSD files for provider XML validation +- provider XML examples +- normalized request and response examples +- provider capability definitions +- compatibility notes for language-specific implementations + +## Initial domain + +The first target domain is flight emission calculation. + +The specification is expected to support provider capability discovery instead of assuming that every provider supports the same request structure, response structure or calculation options. + +## Design principles + +- Provider neutrality +- Multiple providers from the beginning +- Stable domain-level request and response concepts +- Explicit provider capabilities +- Configuration over hardcoded provider logic +- Replayability and auditability where supported +- Language implementations that follow the shared specification + +## Supported providers + +| Provider | XML | API key requested | API key received | API tested | Supported | +| :------------------------------------------------ | :------: | :---------------: | :--------------: | :--------: | :-------: | +| Atmosfair Webservice 5 | ✅ | ❌ | ❌ | ❌ | ❌ | +| Google Travel Impact Model (various versions) | ✅ | ❌ | ❌ | ❌ | ❌ | +| myclimate Flight Calculator V1 & V2 | ✅ | ❌ | ❌ | ❌ | ❌ | +| myclimate Bulk Flight Calculator | ✅ | ❌ | ❌ | ❌ | ❌ | +| C-Level Carbon Balance API | ✅ | ❌ | ❌ | ❌ | ❌ | +| KlimaLink API | ✅ | ❌ | ❌ | ❌ | ❌ | +| KlimAPI Calculation & Compensation API (v1 & v2) | ✅ | ✅ | ✅ | ❌ | ❌ | +| calco2la.to | ✅ | ✅ | ✅ | ✅ | ✅ | +| GoClimate Flight Footprint | ✅ | ✅ | ✅ | ✅ | ❌ | +| Climatiq | ✅ | ✅ | ✅ | ❌ | ❌ | +| Carbon Interface | ✅ | ❌ | ❌ | ❌ | ❌ | +| TravelCO2 | ✅ | ❌ | ❌ | ❌ | ❌ | +| Sustainable Travel International (STI) | ✅ | ❌ | ❌ | ❌ | ❌ | +| CarbonTracer (Uni Graz) | ✅ | ❌ | ❌ | ❌ | ❌ | +| IBM Environmental Intelligence Suite (EIS) | ✅ | ❌ | ❌ | ❌ | ❌ | + + +## License + +The general specification repository is licensed under the GNU Affero General Public License, Version 3 or later. + +Individual implementation repositories may use a different license if this improves integration and adoption. Each implementation repository must state its license clearly.