Integration patterns
How the two ways of integrating with the Carbon Measurement API differ, and which to choose.
There are two patterns for integrating with the Carbon Measurement API, and the difference between them comes down to who stores the transaction data. With synchronous integration, your back end sends anonymised transactions and receives CO2e estimates and equivalents in the same response — Connect Earth stores nothing, so your application keeps everything and re-sends transactions for any insight. With asynchronous integration, you upload anonymised transactions for Connect Earth to store, and historical insights, trends, and recommendations are one call away whenever the user opens your app.
Comparing the patterns
| Synchronous integration | Asynchronous integration | |
|---|---|---|
| Who stores the data | You — nothing is held by Connect Earth | Connect Earth stores anonymised transactions |
| Insights | Re-send transactions with each request | Query stored history any time — trends, monthly insights, recommendations |
| Latency for the user | An API call when the user views transactions, unless you cache | Pre-processed — dashboards read from stored data |
| Effort to first value | Lowest — one endpoint to start | Needs an upload pipeline and transaction IDs |
| Consent-gated programmes | — | Supported via backfill after the user opts in |
Which should you choose?
- If you want the fastest start, or your data policy requires that nothing is held outside your estate, choose synchronous integration.
- If you want rich insights over a user's history — trends over time, monthly breakdowns, personalised recommendations — without re-sending data, choose asynchronous integration.
- If users must opt in before their data is shared, use asynchronous integration and backfill their transaction history once they consent.
The guides
Enrich transactions synchronously
Send anonymised transactions to the Connect Earth API and receive CO2e estimates and equivalents back in the same response.
Integrate asynchronously
Upload anonymised transactions for Connect Earth to store, then fetch enriched results, insights, and recommendations whenever the user opens your app.
Backfill transaction history after user consent
Upload a consenting user's full transaction history in batches, then poll until the processing flag is false to know when their dashboard is ready.
Backfill transactions across users
Bulk-upload historical transactions spanning multiple users in a single backfill operation.