# Travel Data API

The Travel Data API lets you ingest complete trip records — flights, hotels, car rides, and train journeys — directly into SQUAKE's reporting and analytics platform.

Use it when you want SQUAKE to store, attribute, and calculate emissions for travel data you already have, rather than performing an on-demand calculation at booking time.

***

## When to use this endpoint

| Scenario                                                         | Recommended endpoint    |
| ---------------------------------------------------------------- | ----------------------- |
| Real-time emissions estimate at booking / point-of-sale          | `POST /v2/calculations` |
| Push completed or in-progress trip records for reporting         | `POST /v2/travel-data`  |
| Batch-import historical travel data from a TMC or expense system | `POST /v2/travel-data`  |

The key difference: [`/v2/calculations`](/api-calculations-request-response.md) is a **synchronous, low-latency calculation** — you pass activities and get emissions back in one call. `/v2/travel-data` is a **data ingestion endpoint** — it accepts trip records, calculates emissions per activity, stores everything in your SQUAKE account, and makes it available for dashboards, reporting, and carbon accounting.

***

## The data model

Every request wraps one or more **trips**. A trip groups activities that belong together (e.g. a single business journey) and carries metadata like cost, traveler, and cost center.

```
trips[]
  ├── trip_reference        (your unique ID — reusing it appends activities)
  ├── trip_name / purpose / status
  ├── start_date_utc / end_date_utc
  ├── booking_provider / pnr
  ├── amount_in_cents / currency
  ├── cost_center {}
  └── activities[]
        ├── type: flight | hotel | car | train
        ├── methodology
        ├── traveler {}
        └── [type-specific fields]
```

### Supported activity types

| Type     | Available methodologies                                                                     |
| -------- | ------------------------------------------------------------------------------------------- |
| `flight` | ADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GATE4, ICAO, TIM, TU-CHALMERS, US-EPA |
| `hotel`  | DEFRA, HCMI, GREENVIEW                                                                      |
| `car`    | ACRISS, BASIC, DEFRA, EU-EEA, US-EPA                                                        |
| `train`  | ADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GREEN-TRAVEL-PLEDGE, SQUAKE, US-EPA   |

***

## Environments and authentication

| Environment | Base URL                           |
| ----------- | ---------------------------------- |
| Sandbox     | `https://api.sandbox.squake.earth` |
| Production  | `https://api.squake.earth`         |

All requests require an API key — pass it as a Bearer token or as the username in HTTP Basic Auth (no password). Sandbox and production are fully isolated and use separate keys. Create keys in the [SQUAKE Dashboard](https://app.squake.earth/).

> 💡 Always develop and test against the **sandbox** environment first.

***

## What to expect from the response

A successful `200` response returns:

* A **total `carbon_quantity`** across all activities in the request (in kilograms by default).
* An **`items` array** with per-activity breakdowns — each entry echoes your `external_reference`, `type`, calculated `carbon_quantity`, distance, and methodology details.

If a single activity cannot be calculated (e.g. a missing required field), its result will contain a `methodology.errors` array rather than causing the entire request to fail.

***

## Next step

→ [Create Travel Data Items](/travel-data/create-travel-data-items.md) — full endpoint reference with copy-paste request/response examples and field-by-field explanations.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-integration.squake.earth/travel-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.