From v1 to v2

Migrating from v1 to v2 of the SQUAKE API

Conceptual

v1 - Carbon Activity: create, purchase, refund

Single object/endpoint called "carbon activity". One carbon activity had many "carbon activity items". An "carbon activity item" is a single item that is part of a carbon activity. For example, a single flight from A to B. Another item could be a single train ride from C to D.

The /carbon_activities endpoint is a mixture of calculating emissions, and getting pricing information, and handling making purchases and refunding them.

Each emissions calculation is hard-linked to a unique ID. Use this ID to make a single purchase (or refund), meaning if you want to offer compensations for the same activity to many end-users, you must make a separate calculation for each end-user, resulting in N+1 API calls each with the exact same payload and same response (except for the unique ID).

v2 - Calculate, Pricing, Purchase, Refund

Multiple objects/endpoints, each with their own purpose. There are three major concepts are: Calculations, Pricing, Purchases.

  • /calculations: endpoint to calculate emissions for one or multiple "items". These "items" are similar to the "carbon activity items" in v1. The "carbon activity" container is gone.

  • /pricing: get a price quote for either a fixed total (e.g. 25 USD) or a specific amount of carbon emissions (e.g. 150 kg CO2e)

  • /purchases: purchase carbon credits. You must request a price-quote from /pricing before.

  • /refunds: refund a purchase. Within 14 days of a purchase, no refund is necessary, simply call /purchases/:id/cancel to cancel the purchase.

The calculations and pricing endpoints are now stateless. If you want to offer compensations for the same activity to many end-users, you can make a single calculation for each end-user. This results in a single API call for e.g. a flight from A to B in economy class for one traveler. You can use the returned pricing information to make a purchase for all end-users that are interested in the same flight.

Breaking down the single multi-purpose endpoint from v1 allows for a more flexible API, resulting in a simpler integration. At the same time, this allows us to more easily add functionality to the API without breaking changes and keeping complexity low.

v1 - Pricing Split, Projects, Portfolios

Initially, we offered you to choose one specific project to contribute to. Then we added multiple projects, and finally we added the option to split your purchase across multiple projects with a chosen percentage. This is complex and lead to many errors, so we added "portfolios" that are a collection of projects. You can choose a portfolio, and we split your purchase across the projects in the portfolio. Then we added that you can split across multiple portfolios. To avoid a breaking change, combinations of all these options were possible.

The payload options grew complex and became incomprehensible. It also made the process of swapping projects more complex; this is necessary in rare instances due to the volatile and complex nature of the carbon market.

One of many possible ways in v1:

{
  "project_split": [
    {
      "external_pricing_reference": "ps_1",
      "split": [
        {
          "project_code": "project_0110",
          "percentage": 70
        },
        {
          "project_code": "project_0007",
          "percentage": 30
        }
      ]
    },
    {
      "portfolio_id": "portfolio_abc_123"
    }
  ]
}

v2 - Product

We now offer a single concept called "product" that you can purchase. A product is a collection of projects (same as "portfolios"). During the onboarding, we evaluate your needs and goals, and custom-create one or several products for you. In the future, you may be able to create your own products, but for now, we create them for you.

One simple key-value pair is all you need in v2:

{
  "product": "product_abc123"
}

v2 - expand (new concept, v2 only)

v1 returns huge responses; for example the pricing information returns multiple keys, in different variations some with more some with fewer information. This led to confusion, convoluted logs, and a lot of unnecessary data transfer and complexity.

v2 by default returns simplified payloads with only the information that is required for any kind of integration. Further, optional, objects are included as ID only. If you want to get full, nested, objects, you can use the expand parameter. For example, if you want to get the full project information, you can use expand=project.

This concept exists throughout the API and helps you customize the complexity and amount of information the API returns. For an MVP or simple testing, you most likely want to omit expand and get the most simple response. For a more sophisticated integration, you can use expand to cherry-pick all the information you need.

E.g. the pricing without expand returns just an ID:

{
  "product": "product_5ea9f3",

  "id": "...",
  "carbon_quantity": 89257,
  "carbon_unit": "gram",
  "currency": "EUR",
  ...
}

with expand we include more information:

{
  "product": {
      "id": "product_5ea9f3",
      "title": "CO2 reduction through SAF - Sustainable Aviation Fuel",
      "description": "SAF saves up to 80% of CO2 emissions compared to fossil fuel. SQUAKE partners with Compensaid, replacing fossil jet fuel with SAF. Your purchased SAF is put into circulation within the next 12 months. It is certified according to EU-ISCC and RED and feedstocks have not been derived from palm oil or acid distillates.",
      "locations": [
        {
          "country": "DE",
          "sub_region": "150",
          "region": "155"
        }
      ],
      "certifications": [],
      "sdgs": [
          9,
          13
      ]
  },

  "id": "...",
  "carbon_quantity": 89257,
  "carbon_unit": "gram",
  "currency": "EUR",
  ...
}

Code Examples

A few code examples to get you started.

Feel free to send us a sample of your typical API call payloads; we'll then send you back the respective v2 payloads and responses. -- Or head over to the API docs and Postman collection and give it a try (your v1 client_secret from the OAuth flow is migrated to v2, so you can use it as API Key).

v1 - Carbon Activity "creation"

Request body:

{
  "items": [
    {
      "carbon_activity_type": "flight",
      "parameters": {
        "origin": "TXL",
        "destination": "HAM",
        "booking_class": "economy",
        "number_of_travelers": 2,
        "aircraft_type": "320",
        "algorithm_type": "icao"
      }
    }
  ],
  "project_split": [
    {
      "project_code": "project_0110",
      "percentage": 100
    }
  ]
}

Returned emissions, a price-quote, and a unique ID for a one-time purchase.

v2 - Calculation & Pricing

Notice: payloads and responses are not deeply nested anymore. The naming is more consistent and easier to understand.

E.g. algorithm_type is now methodology. carbon_activity_type is now type. Methodologies have a consistent spelling and express now the underlying methodology that is applied. E.g. "specific" is named "US-EPA"; now you can research the US EPA methodology.

Request body:

{
  "items": [
    {
      "type": "flight",
      "methodology": "ICAO",
      "origin": "TXL",
      "destination": "HAM",
      "booking_class": "economy",
      "number_of_travelers": 2,
      "aircraft_type": "320"
    }
  ]
}

Returns only emission values ("carbon quantity & unit"). No ID, no price quote.

Request for a pricing (this is a GET):

curl \
 -X GET https://api.squake.earth/v2/pricing \
  -d product=product_5ea9f3 \
  -d carbon_quantity=1000000 \
  -d carbon_unit=gram
  -d currency=EUR

Returns a price quote, and an ID that you can use to make one or multiple purchases for the requested carbon quantity at the price we returned.

We still offer a combined endpoint to get calculation and pricing in one API call if needed: Use the same request body as for the calculation, and add a product and a currency:

{
  "product": "product_5ea9f3",
  "currency": "EUR",
  "items": [
    {
      "type": "flight",
      "methodology": "ICAO",
      "origin": "TXL",
      "destination": "HAM",
      "booking_class": "economy",
      "number_of_travelers": 2,
      "aircraft_type": "320"
    }
  ]
}

Returns emissions, a price quote, and the ID for purchasing.

v1 - Purchase

Request:

curl \
 -X POST https://api.squake.earth/carbon_activities/{id}/purchase

v2 - Purchase

Additional payload options to request a receipt via email, a PDF certificate, and so on, are the same as in v1. We have renamed a few keys and un-nested the payloads as far as possible.

Idempotency: This endpoint accepts the external_reference parameter. It works as an idempotency key; meaning it'll create a purchase related to this key only once by giving you 201 (created) in response. If you call it again with the payload and key, you get 200 (ok) and the same purchase object as before.

Request:

curl \
 -X POST https://api.squake.earth/v2/purchases/ \
 -d pricing={id}

List of all breaking changes

Besides the obvious structural changes, a few keys and values have been renamed:

Counting human beings

v1:

  • number_of_passengers

  • number_of_travelers

  • number_of_visitors

v2: Unified into: number_of_travelers

(Carbon Activity) Types

  • ship_freight is now sea_freight

  • ship_freight_inland_waterway is now inland_waterways

  • train_freigth is now rail_freight

  • truck is now road_freight

  • parcel is now logistics

  • money_amount: removed, simply request a pricing for a fixed total

  • general: removed, this was just a fixed amount of carbon, request a pricing straight for a specific amount of carbon

  • co2_amount: removed, same as "general"

Algorithm Type --> Methodology

Besides renaming this property from algorithm_type into methodology, we also improved their naming.

All methodologies are consistently named using ALL-CAPS-WITH-DASHES.

v1:

  • specific: removed

  • simple: removed

  • extend: removed

  • etc.

v2:

  • US-EPA: tells you, we use the methodology published by "United States Environmental Protection Agency". This formerly was called "specific" or similar.

  • EU-EEA: tells you, we use the methodology published by the "European Environment Agency". This formerly was called "simple" or similar.

  • SQUAKE: methodology developed by our in-house research team. This formerly was called "extend" or similar. These methodologies are based on the best available data and latest research.

  • BASIC: Simply approximation, useful when you have sparse data. These are either public or in-house developed approximations, e.g. based on industry averages. Formerly, this was called "simple" or similar.

  • we still have all the others, e.g. ACRISS, GLEC, etc. (and a few new ones!)

Authentication

v1: OAuth2, which proved to be complex to implement for many customers. Generated access tokens where short-lived and rotation had to be implemented by you.

v2: API Keys do not expire automatically anymore. You can still rotate them (in the dashboard) if you wish.

  • API Key Auth: send your API key in the header of each request

  • Basic Auth: send your API key as username and leave the password empty, base64 encoded

  • contact us, if you require mTLS

Error messages

v1: Not consistent errors usually contained the code/message or schema_errors object.

v2 Errors which follow the JSON API standard. If the request is failing, you get an errors array in response, which looks like this:

{
  "errors": [
    {
      "code": "invalid_params",
      "detail": "Positive number expected for 'number_of_nights', got '-1'.",
      "source": {
        "attribute": "number_of_nights",
        "model": "campingsite_parameters",
        "id": "my-test-booking"
      }
    },
    {
      "code": "invalid_params",
      "detail": "Invalid country 'FR1'. Expected one of: DE, FR, FI, NO, SE, DK, IS, FO.",
      "source": {
        "attribute": "country",
        "model": "camping_site",
        "id": "my-test-booking"
      }
    },
    {
      "code": "invalid_params",
      "detail": "Invalid camping_type: 'invalid'. Expected one of: caravan_mobile_home, semi-integrated_motorhome, integrated_motorhome, panel_van.",
      "source": {
        "attribute": "camping_type",
        "model": "camping_site",
        "id": "my-test-booking"
      }
    }
  ]
}

Other name changes

  • Expenditure: price_in_cents --> total

  • Hotel: the *_stars options for hotel_type are removed, we infer this now from stars if hotel type is omitted.

  • Hotel: eco_label --> eco_labels the key is pluralized, since it accepted an array of values

  • Response from calculations: algorithm_specific --> energy_and_emission_factors, the content is the same; this is included in the items object return from the calculations endpoint and contains factors used for the calculation (as required by some of the methodologies).

  • SeaFreight (v1: "ShipFreight"): freight_type --> cargo_type. Allowed values are dry and reefer

PreviousMigration Guide

Last updated