canonical: https://jentic.com/apis/ducky.eco/ducky

# Ducky Eco Ducky Data V3 - climate data APIs

Ducky Data is a climate footprint API that calculates, compares, converts, and translates CO2-equivalent emissions for individuals, products, and administrative areas. The API exposes 22 endpoints grouped by function: Calculate (annual or category footprint), Change (sustainability tips), Compare (area averages), Convert (energy, finance, food, goods, transport to kgCO2e), Reporting (GHG Scope 1 and 2), Track (area indicators), and Translate (kgCO2e to relatable units like flights or trees). Authentication uses an Auth0-issued access_token sent as an Authorization header.

## For AI agents

Convert energy use, transactions, food, and transport into CO2-equivalents and translate emissions into relatable units like trees or flight distance through Ducky Data.

## Scope

Does not handle carbon offset purchase, environmental compliance filing, or real-time emission monitoring - use for footprint calculation, comparison, conversion, and translation only.

## Capabilities

- Convert financial transactions, energy, food, and transport to kgCO2e via the /convert endpoints
- Calculate an individual's annual footprint by category via POST /calculator
- Generate behavioural sustainability tips via POST /change
- Compare a footprint against area averages via the /compare endpoints
- Compute Scope 1 and Scope 2 GHG emissions via `/report/scope-1` and `/report/scope-2`
- Translate kgCO2e into car distance, plane distance, energy use, or tree absorption via /translate endpoints
- Read sustainability indicators for an administrative area via POST `/track/transport`

## Use cases

### Carbon Footprint Calculator in a Banking App

Estimate the climate impact of customer transactions inside a banking or expense app. POST `/convert/finance` accepts a monetary amount and category and returns kgCO2e, which the agent surfaces beside each transaction. Pair with `/translate/tree` or `/translate/plane` to render the impact in tangible units the customer understands.

Example prompt: POST `/convert/finance` with amount=120 and category='groceries', then POST `/translate/tree` with the returned kgCO2e to render 'equivalent to X trees per year'

### Annual Personal Footprint Calculator

Compute a complete annual footprint for an individual based on home energy, transport, food, and consumption habits. POST /calculator returns the breakdown by category, which an agent can present back as a sustainability dashboard. POST /change then suggests tailored actions, and POST `/compare/general` puts the result in context against an area average.

Example prompt: POST /calculator with the user's habits, then POST `/compare/general` for the area average, then POST /change to fetch personalised tips

### Corporate GHG Reporting (Scope 1 and 2)

Compute the Scope 1 and Scope 2 emissions a company must report under the GHG Protocol. POST `/report/scope-1` takes direct emissions inputs such as fuel use, and POST `/report/scope-2` takes purchased electricity and heat. Agents can wire these into accounting or ESG tooling so the calculation runs from the same data feeds that drive financial reporting.

Example prompt: POST `/report/scope-2` with annual purchased electricity in kWh and the country code, then write the kgCO2e output into the ESG dashboard

### Agent-Driven Sustainability Insights via Jentic

Wire Ducky Data into agent workflows that score, compare, and translate emissions. Through Jentic the agent searches by intent, loads the schema for the right /convert or /translate endpoint, and executes - the access_token stays in your Jentic One instance, not the agent's prompt context.

Example prompt: Search Jentic for 'convert energy use to kgCO2e', load the schema for POST `/convert/energy`, and execute with the kWh value supplied by the parent workflow

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/convert/energy` | Convert kWh of energy use to kgCO2e |
| POST | `/convert/finance` | Convert a monetary transaction to kgCO2e |
| POST | `/calculator` | Calculate an annual footprint by category |
| POST | `/report/scope-1` | Compute Scope 1 GHG emissions |
| POST | `/report/scope-2` | Compute Scope 2 GHG emissions |
| POST | `/translate/tree` | Translate kgCO2e into tree-absorption equivalence |
| POST | `/change` | Get behavioural sustainability tips |

## Key resources

- **Calculate** — Compute an individual's annual or category footprint under /calculate and /calculator
- **Convert** — Convert energy, finance, food, goods, and transport units to kgCO2e under /convert
- **Compare** — Compare a footprint against area averages under /compare
- **Reporting** — Compute GHG Protocol Scope 1 and Scope 2 emissions under /report
- **Translate** — Translate kgCO2e into relatable units under /translate
- **Change & Track** — Generate sustainability tips and read area indicators under /change and /track

## Why Jentic

- **Setup:** Wiring the Ducky API by hand means obtaining an Auth0 access token from your client id and secret and passing it as a bearer token on every request. Through Jentic you install once, import Ducky from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Ducky takes the inputs for each calculation in the request body, so you limit the agent to the operations it needs, such as converting energy use to emissions or computing a Scope 2 report. You choose which operations are allowed, so other calculators are not included unless you add them.
- **Credential handling:** Your Ducky client id and secret are stored once, encrypted, by your own Jentic One instance and exchanged for a bearer access token at execution time. Neither the secret nor the token enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'convert energy use to kgCO2e' or 'compute Scope 2 emissions', and Jentic returns the matching Ducky operation with its input schema so the agent calls the right endpoint without browsing the docs.

## Related APIs

- **Climatiq API** — Emission factor API with broader activity coverage than Ducky's category-based shape
- **Cloverly API** — Carbon offset purchase API that pairs with footprint calculation
- **Auth0 Management API** — The auth provider Ducky uses for token issuance

## FAQ

### What authentication does the Ducky Data API use?

Ducky Data uses an Auth0-issued access_token sent as an Authorization header. Customers email Ducky for a CLIENT_ID and CLIENT_SECRET, then negotiate the token with Auth0. Through Jentic the credentials are stored in the encrypted vault and the token is injected at execution, so secrets never enter the agent's prompt.

### Can I calculate Scope 2 emissions with the Ducky Data API?

Yes. POST `/report/scope-2` accepts purchased electricity and heat inputs and returns kgCO2e under the GHG Protocol. POST `/report/scope-1` covers direct emissions like fuel combustion.

### How do I convert a transaction amount to CO2-equivalent through Jentic?

Search Jentic for 'convert finance transaction to CO2', load the schema for POST `/convert/finance`, and execute with the amount and category. Install with pip install jentic.

### What are the rate limits for the Ducky Data API?

The OpenAPI spec does not declare rate limits. Ducky sets quotas per contract; have your agent handle 429 responses with exponential backoff and confirm the active limits with Ducky support.

### Can I show users their footprint in relatable units?

Yes. The /translate endpoints convert kgCO2e into car distance (`/translate/car`), plane distance (`/translate/plane`), energy use (`/translate/energy`), or trees needed to absorb it (`/translate/tree`).

### Does Ducky Data return tips to reduce a footprint?

Yes. POST /change accepts the user's habits and returns climate-friendly tips, which agents can use to nudge users toward lower-impact behaviour.

### Can I limit what my agent is allowed to do with the Ducky Data API?

Yes. Because Jentic One is self-hosted, you decide which Ducky operations your agent may call and which credentials it may use, so you can allow just the endpoints a task needs, such as POST `/convert/energy` to convert kWh to kgCO2e or POST `/report/scope-2` to compute a Scope 2 report. Every Ducky calculation takes its inputs in the request body, so an allowed operation only runs on the data you pass it. Other calculators, like /calculator or the /translate endpoints, stay out of reach unless you add them to the agent's allowed set.