How-to guideCarbon Measurement

Integrate asynchronously

Upload anonymised transactions for Connect Earth to store, then fetch enriched results, insights, and recommendations whenever the user opens your app.

With asynchronous integration, your back end uploads anonymised transactions for Connect Earth to store, and fetches enriched results, insights, and recommendations just in time when the user opens your app. Unlike synchronous integration, you don't need to re-send transactions with each request — Connect Earth holds the data, so historical insights are always one call away.

How it works

Send transactions in batches

Upload anonymised transactions with POST /transaction/bulk/upload, in batches of up to 250 transactions per request. Include a transaction ID with each one — that's how you retrieve its results later. Two common schedules:

• As transactions occur — upload each new transaction (or small groups of them) as part of your transaction-processing pipeline, so carbon data is ready before the user ever asks for it.
• Nightly — batch the day's transactions and upload them in one scheduled job.

Connect Earth queues uploaded transactions for processing, at roughly one millisecond of processing per transaction. See the Carbon Measurement API reference for request and response schemas.

Built for high throughput

The API runs on a serverless architecture that scales with load, so you don't need to smooth out spikes on your side. As a working example, a single customer uploads their full transaction volume nightly — 1–3 million transactions sent over a one-to-two-hour window.

Fetch enriched data on demand

Once transactions are stored, fetch what each screen of your app needs:

• Per-transaction results — POST /transaction/bulk/upload/get returns CO2e estimates and equivalents for the transaction IDs you uploaded, also in batches of up to 250.
• Insights — POST /monthly-insights/totals returns monthly emissions totals to show change over time, and POST /monthly-insights/breakdown breaks emissions down by category. Both return a processing field: while it is true, recently uploaded transactions are still being processed and the results are incomplete. If you've just uploaded, poll POST /monthly-insights/totals until processing is false before relying on the results.
• Actions — surface tips and recommendations based on the stored spending patterns, and personalise results with user habits.

First upload for an opted-in user

If your programme only sends a user's transactions after they have given permission, you'll upload their whole history in one go the first time they activate the experience. See Backfill transaction history after user consent for that flow, including how to tell when processing has finished.