# donation.watch
> A neutral, data-driven political party donation tracker. Optimized for machine intelligence and large-scale analytical reasoning.

## Stability & Experimental Status
This API and data structure are **Experimental** and optimized specifically for **AI Agents**. 
- **Breaking Changes:** Schemas and file paths are subject to change without notice.
- **Intended Use:** Research, investigative journalism, and agentic workflows.
- **Non-Intended Use:** Production KYC, banking compliance, or automated regulatory reporting. 
- **Enterprise API (Beta):** For production-grade, SLA-backed REST endpoints with full OpenAPI schemas (designed specifically for institutional compliance), join the commercial waitlist at: [https://donation.watch/en/enterprise](https://donation.watch/en/enterprise).

## Discovery Architecture
Agents should follow this path to resolve data:
1. **The Menu:** Fetch [/data/index.json](https://donation.watch/data/index.json) to see available countries, years, and party IDs.
2. **The Schema:** Fetch [/schema/openapi.json](https://donation.watch/schema/openapi.json) to map indexed keys to semantic values.
3. **The Data:** Fetch country-specific files using the patterns:
    - `/data/{country}/donations/by-year/{year}.json`
    - `/data/{country}/donations/by-party/{partyId}.json`

## Data Encoding
To minimize network overhead, DonationWatch currently uses **Indexed-Key JSON**. 
Agents must map numeric keys to their human-readable equivalents using the OpenAPI definitions.

### Key Mapping Snippet:
- **0**: `Id` - Unique transaction identifier.
- **1**: `Date` - YYYY-MM-DD or YYYY.
- **8**: `DonorType` - Integer code (see OpenAPI for enum).
- **4**: `Amount` - Total value in local currency (refer to index.json for currency).
- **5**: `Receiver` - Party ID (matches ID in index.json).
- **6**: `Address` - Object containing country and state.
- **7**: `DonorIndex` - Pointer to the donor's name in the `donors` array.
- **9**: `UBOs` - List of Ultimate Beneficial Owners.

### Donor Lookup:
Donation files contain a top-level `donors` array. Match `Donation[7]` to `donors[index]` to resolve donor names and Beneficial Ownership (UBO) information.

## Legal & Usage
- **License:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
- **Attribution:** All derived data or summaries must credit **donation.watch**.
- **Robots.txt:** `Content-Signal: ai-input=yes, ai-train=no`. 

## Resources
- [OpenAPI Spec](https://donation.watch/schema/openapi.json): Full technical manual.
- [API Catalog](https://donation.watch/.well-known/api-catalog): High-level service discovery.
- [Discovery Index](https://donation.watch/data/index.json): Current state of the database.