# SQUAKE API Documentation # Introduction ## Trusted technology to achieve your carbon targets. The **SQUAKE Solution Suite** is live with industry leaders from several travel and logistics segments and performs accurate carbon calculations for all types of activities (e.g. flights, road, accommodation amongst others) according to national and international standards. It automates carbon reductions and/or compensations along the supply chain, from supplier selection (SAF, DAC, ecological restoration) to inventory management, invoicing and credit retirement. ## Customer Support For any issues or inquiries, you can reach our dedicated customer support team through our [Support Page](https://support.squake.earth/). This is the best place to ask questions, report incidents, or get assistance with integrating or using SQUAKE's solutions. ## Contact Forms Our contact forms are designed to help you communicate with us effectively. Whether you want to get in contact with our support team or need to report an incident, we've got you covered. Please use the appropriate form below: * [Contact Form](https://support.squake.earth/hc/en-gb/requests/new?ticket_form_id=5351278647581): Get in contact with our customer support team or share your thoughts and suggestions about our services and processes. * [Incident Form](https://support.squake.earth/hc/en-gb/requests/new?ticket_form_id=21154347283741): Report any issues or incidents you've encountered, and our support team will respond as soon as possible. ## Authentication SQUAKE uses API keys to authenticate requests. You can create and revoke API keys in the [Dashboard](https://app.squake.earth/), which you can access by contacting us under `product@squake.earth`. You should securely store your API keys; and encrypt them on rest if possible. Be aware that each API key is shown exactly once in the UI during creation. SQUAKE advises rotating API keys on a regular basis. To use the sandbox environment, a separate API key must be created. Switch to sandbox mode in the dashboard, then create an API key. All requests must be authenticated and made over HTTPS. SQUAKE supports TLS 1.2 - TLS 1.3. Requests without authentication or via plain HTTP result in an error. When using HTTP Basic Auth, the API key is the username; leave the password blank. For bearer auth, pass the API key as the token. Example using HTTP Basic Auth (note: there is no password, but a colon is still required): ```shell curl https://api.squake.earth/v2/pricing -u ``` Example using bearer auth: ```shell curl https://api.squake.earth/v2/pricing -H "Authorization: Bearer " ``` ## Request ID SQUAKE associates each API request with a unique identifier. Find this value in the `SQUAKE-Request-Id` header. If you need to contact us regarding a specific request, providing the request identifier helps the resolution process. ## Uptime Monitoring Please visit [status.squake.earth](https://status.squake.earth) to check our uptime monitor. You can subscribe to events to stay informed of any service disruption. We will also publish a post-mortem about any incident should one occur. You can programmatically check if servers are reachable. Read the documentation of the `Health Check` endpoints for details. The health check endpoints are the only endpoints that do not require authentication. ## Sandbox There is a sandbox server available for testing at `https://api.sandbox.squake.earth` Sandbox and production are separate systems and share no data. Sandbox uses less computing power and may be slower than production. Both sandbox and production environments run the same version of the API; thus, they share the same feature set. To use the sandbox environment, a separate API key must be created. Switch to sandbox mode in the dashboard, then create an API key. ## Static IP Addresses All outgoing traffic originates from one of the following static IP addresses. SQUAKE owns these IP addresses and never shares them for any other traffic. | Environment | IP Address | Geo Region | |-------------|----------------|----------------| | Production | 52.59.66.213 | Europa/Germany | | Production | 52.7.39.159 | USA | | Sandbox | 18.197.251.125 | Europa/Germany | ## Getting Started with SQUAKE API This guide will help you make requests to the SQUAKE API in order to calculate emissions for a travel journey. ### Choose a group of Endpoints SQUAKE API has the following group of endpoints: - [Calculations](https://docs-v2.squake.earth/docs/openapi/calculations) - Calculates carbon emissions for various activities in a low-latency process. - [Pricing](https://docs-v2.squake.earth/docs/openapi/pricing) - Returns pricing for a given product and carbon quantity, valid for two weeks by default. - [Combined Calculation & Pricing](https://docs-v2.squake.earth/docs/openapi/combined-calculation-and-pricing) - Performs carbon calculation and pricing in a single call for convenience. - [Carbon Comparison](https://docs-v2.squake.earth/docs/openapi/carbon-comparison) - Compares carbon quantities to recognizable items like cars or light bulbs. - [Purchases](https://docs-v2.squake.earth/docs/openapi/purchases) - Registers a purchase to compensate for carbon emissions, requiring a prior pricing quote. - [Products](https://docs-v2.squake.earth/docs/openapi/products) - Lists purchasable compensation options, including single climate projects and bundles. - [Files](https://docs-v2.squake.earth/docs/openapi/files) - Manages file attachments related to purchases, such as compensation confirmations. - [Webhooks](https://docs-v2.squake.earth/docs/openapi/webhooks) - Allows you to receive notifications about events happening in SQUAKE. - [Audits](https://docs-v2.squake.earth/docs/openapi/audits) - Provides a list of audits or a specific audit for calculations. - [Health Check](https://docs-v2.squake.earth/docs/openapi/health-check) - Verifies if SQUAKE's server is reachable. ### Precision of Calculations #### Bus Databases If you want operator-specific calculations for buses, then use the following [dataset](https://squake.notion.site/31f83752e3bd4cf2ba314ceb8fa2acc6?v=5190873dd753431187b735a8fe40038f) supported by SQUAKE's methodology. #### Car Databases If you have specific information about car models, then use one of the following methodologies: [ADEME](https://squake.notion.site/136f89fa8b1949e899f82f874d4f648c?v=49c586d0b74d4a6bbe2cf03d16546f5c) (France), [US-EPA](https://squake.notion.site/7f437246ecec4760a8b95b5c1d06f34a?v=454b352108e640ceb124890cf75f1c9f) (USA) and [EU-EEA](https://squake.notion.site/Car-EU-EEA-f38231a59f934d819ac1014c65bb701c) (EU). #### Hotel Databases Use the [HCMI](https://squake.notion.site/Hotel-HCMI-SQUAKE-7bd2c02fe23b45889e1c30ffc8018bcd) and [GreenView](https://squake.notion.site/Hotel-GreenView-Locations-237754e0050480fc9dfcd3ea65ce7c51?source=copy_link) methodologies to obtain more accurate emissions. #### GLEC Databases For road and sea logistics activities according to GLEC, use the [GLEC dataset](https://squake.notion.site/GLEC-6947b398c6704220838ae5a16902b064). #### Train Databases For operator-specific calculations for trains, use the [train dataset](https://squake.notion.site/21a17389cc5c4e38946f97ecaf6435bb?v=6be41159e77247599fe9b3672782fd5e). #### Van Databases For van calculations, use the [EU-EEA supported dataset](https://squake.notion.site/b9afb2b6c23e4b60868c5b6148224c6d?v=49a2ac9295ab4cc18a328da841b7b583). ### Carbon Comparison Compare carbon quantities to more recognizable items like cars or kettles. View accepted units in this [comparison database](https://squake.notion.site/96b220031e8e4d64aec4f0e46a5bde97?v=8c67ffdcf91c4477acf0640688beea11).


## Servers Production ``` https://api.squake.earth ``` Sandbox ``` https://api.sandbox.squake.earth ``` ## Security ### HTTP-Basic-Auth Type: http Scheme: basic ### Bearer-Auth Type: http Scheme: bearer ## Download OpenAPI description [SQUAKE API Documentation](https://docs-v2.squake.earth/_spec/docs/openapi.yaml) ## Calculations ### Perform a Calculation - [POST /v2/calculations](https://docs-v2.squake.earth/docs/openapi/calculations/post-calculations.md): The calculations endpoint can calculate carbon emissions for one or multiple activities. The carbon footprint or your journey consisting of, for example, a return flight, two cab rides, and a hotel stay can be computed all at once, passing all five activities in the items array. Include the string literal "items" in the "expand" array to retrieve values for each item separately in addition to the total carbon quantity. This is a low-latency endpoint. SQUAKE does not provide you with a unique identifier for any calculation results. You must quote a price on the pricing endpoint to purchase compensation for your carbon emissions. Some data sets are extensive and thus documented separately here. ## Pricing ### Quote a Pricing - [GET /v2/pricing](https://docs-v2.squake.earth/docs/openapi/pricing/get-pricing.md): Returns pricing for a given product and carbon quantity (or a fixed total amount in any supported currency). By default, requested pricing is valid for two weeks starting the moment you request it. Expired pricings can still be used as long as the underlying price hasn''t changed for your convenience. Repeated purchases using the same pricing are possible via API and the checkout page using the pricing id or , respectively. You can append additional parameters to the ; SQUAKE's checkout page supports the following: * : Please use a two-letter ISO 639-1 code, for example: for English. : any valid UTM tracking parameters, e.g., . This is a low-latency endpoint, useful for previewing pricing before making a purchase either via API or on the SQUAKE checkout page via the returned .' ## Combined Calculation & Pricing ### Perform a Calculation including a Price Quote - [POST /v2/calculations-with-pricing](https://docs-v2.squake.earth/docs/openapi/combined-calculation-and-pricing/post-calc-and-pricing.md): Convenience all-in-one endpoint to perform carbon calculation and pricing. A purchase can be performed via API or SQUAKE's checkout page using the returned . All features supported by either the or endpoint are equally valid for this combined endpoint. Please read the respective descriptions for details. If you need only either pricing or carbon emissions, SQUAKE advises using the specific endpoints for lower latency and reduced implementation complexity.' ## Carbon Comparison ### Compare Carbon Usage - [POST /v2/carbon-comparison](https://docs-v2.squake.earth/docs/openapi/carbon-comparison/post-v2-carbon-comparison.md): This endpoint allows you to compare carbon quantities to more recognizable items such as cars, light bulbs, or kettles. Our list of metrics and comparison units are quite extensive so a list of accepted combinations has been compiled and is available here ## Purchases ### Create a Purchase - [POST /v2/purchases](https://docs-v2.squake.earth/docs/openapi/purchases/post-purchases.md): You can register a purchase programmatically to compensate for carbon emissions on this endpoint. You must quote for pricing beforehand and pass the returned pricing ID as a parameter. Alternatively, you can use the from the pricing endpoint to finalize the purchase using SQUAKE's provided checkout page. ### Lifecycle #### When purchasing via API (this endpoint) * : A successful purchase starts in the state "reserved"; SQUAKE registered your purchase and reserved carbon credits accordingly. * : SQUAKE offers 14 days to cancel a purchase worry-free. This is a terminal state. * : The refundable period has passed. If you need to cancel the purchase beyond this point, please request a refund on the refunds endpoint. * : Without further action, a purchase is invoiced after the grace period and transitions to "invoiced". #### When purchasing via the checkout page * : the end customer entered the payment flow on the checkout page * : the payment failed permanently, for example, because the customer exited the page without finalizing the payment and didn''t return before the pricing''s validity ended. This is a terminal state. * : the payment provider informed SQUAKE about the successful payment. In this flow, this state exists only for a short time; the purchase immediately continues to "settled". #### Both * : SQUAKE has received the payment. * : a refund request was successfully processed. This is a terminal state. * : all certificates for the carbon credits have been confirmed from all project partners related to the purchase. * : all certificates have been retired in the corresponding registries. This is a terminal state. ### Retrieve a Purchase - [GET /v2/purchases/{id}](https://docs-v2.squake.earth/docs/openapi/purchases/get-purchases-id.md): Retrieve a purchase placed earlier. Useful to check for its state. To avoid short polling, you can register a webhook to stay informed about all your purchases automatically. You can use the as ID as well for the lookup; i.e. your unique identifier. ### Update a Purchase - [PATCH /v2/purchases/{id}](https://docs-v2.squake.earth/docs/openapi/purchases/patch-purchases-id.md): Update a purchase placed earlier. You can use the as ID as well for the lookup; i.e. your unique identifier. Omitted keys will not affect any present data. To remove optional data you must explicitly set the value to . ### Cancel a Purchase - [POST /v2/purchases/{id}/cancel](https://docs-v2.squake.earth/docs/openapi/purchases/post-purchases-id-cancel.md): A purchase can be canceled as long as it is not confirmed; this is in the state . After the cancelation period passes, the purchase transitions to . Confirmed purchases go to the batch settlement. ## Products ### Retrieve Products - [GET /v2/products](https://docs-v2.squake.earth/docs/openapi/products/get-products.md): A product is any purchasable compensation option SQUAKE offers. In the simplest case, a product maps to a single climate project such as "Sustainable Biofuel for Shipping". Depending on client need, SQUAKE also offers bundles of multiple climate projects; these can be centered around specific goals, e.g.,"carbon reduction", "location", or what is desired to achieve a particular price point or sustainability goal. Feel free to contact us for more information or custom products. ### Retrieve a Product - [GET /v2/products/{id}](https://docs-v2.squake.earth/docs/openapi/products/get-products-id.md): Retrieve details about a specific product ## Files ### Retrieve a File - [GET /v2/files/{id}](https://docs-v2.squake.earth/docs/openapi/files/get-files-id.md): Certain records may have files attached. For a purchase, you can request a compensation confirmation, for example. SQUAKE can send this via email; you can have it returned from the purchase request immediately or fetch the file from this endpoint later. SQUAKE advises fetching files async after the purchase to keep the latency of the purchase API call low. You will always receive the file ID from the purchase endpoint if files are, or will be, attached to the record. ## Webhooks ### Retrieve Registered Webhooks - [GET /v2/webhooks](https://docs-v2.squake.earth/docs/openapi/webhooks/get-v2-webhooks.md): Webhooks are HTTP callbacks that notify your application when events happen in SQUAKE's system. Instead of continuously polling our API, webhooks push data to your endpoint when events occur. This endpoint returns the list of currently registered webhooks. See the Integration Documentation for more information. ### Register New Webhook - [POST /v2/webhooks](https://docs-v2.squake.earth/docs/openapi/webhooks/post-v2-webhooks.md): This endpoint allows you to register a new Webhook to subscribe to certain kind of events being triggered by Squake This endpoint returns a newly created webhook upon a successful request. The webhook includes a used to verify the authenticity of future webhook messages. Please ensure you save this , as it cannot be retrieved later. ### Retrieve Webhook Information - [GET /v2/webhooks/{id}](https://docs-v2.squake.earth/docs/openapi/webhooks/get-v2-webhooks-id.md): This endpoint allows you to retrieve an information about a specific Webhook ### Update Webhook - [PUT /v2/webhooks/{id}](https://docs-v2.squake.earth/docs/openapi/webhooks/put-v2-webhooks-id.md): This endpoint allows you to update a previously registered webhook. It accepts the same parameters as the Register New Webhook endpoint and responds with an updated Webhook entity ### Delete Webhook - [DELETE /v2/webhooks/{id}](https://docs-v2.squake.earth/docs/openapi/webhooks/delete-v2-webhooks-id.md): This endpoint allows you to delete previously registered webhook ## Audits Audit logs are created when enabled on calculation requests. | ℹ️ To use this feature you need to have it enabled for your account, please contact us for more information.| |------------------------------------------------------------------------------------------------------------| ### Retrieve the list of Audit logs - [GET /v2/audits](https://docs-v2.squake.earth/docs/openapi/audits/get-v2-audits.md): Retrieve the list of audit logs for the authenticated client ### Retrieve a specific Audit log - [GET /v2/audits/{id}](https://docs-v2.squake.earth/docs/openapi/audits/get-v2-audits-id.md): Retrieves detailed information about a specific Audit log ## Health Check Check if SQUAKE's server can be reached. ### Healthz - [GET /v2/healthz](https://docs-v2.squake.earth/docs/openapi/health-check/get-v2-healthz.md): Simple health check to verify SQUAKE's server can be reached. ### Livez - [GET /v2/livez](https://docs-v2.squake.earth/docs/openapi/health-check/get-v2-livez.md): Health check to verify SQUAKE's server can be reached; this additionally checks the most critical sub-dependencies, such as database systems. ### Readyz - [GET /v2/readyz](https://docs-v2.squake.earth/docs/openapi/health-check/get-v2-readyz.md): Extensive health check to verify SQUAKE's server can be reached; this additionally checks all sub-dependencies, such as database systems, and also considers the error rate of the most recent history. Meaning even if SQUAKE's servers are reachable, including their sub-systems, if other clients experience excessively many errors, this endpoint returns an error.