> For the complete documentation index, see [llms.txt](https://docs-integration.squake.earth/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-integration.squake.earth/travel-data.md).

# 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`              |
| Read back or reconcile what SQUAKE stored                        | `GET /v2/travel-data/trips`         |
| Remove a trip you should not have sent                           | `DELETE /v2/travel-data/trips/{id}` |

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 (optional override)
        ├── amount_in_cents / currency (optional per-activity spend)
        ├── traveler {}
        └── [type-specific fields]
```

Trips can retain their overall booking cost while individual activities carry their own monetary values. Activity-level values take precedence in activity-based spend reporting.

### Supported activity types

If you omit `methodology`, SQUAKE uses your account's configured default methodology for that activity type. Pass `methodology` only when you want to override that default for a specific activity.

| Type     | Available methodology overrides                                                                |
| -------- | ---------------------------------------------------------------------------------------------- |
| `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, REM, 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.
* A **`trips` array** with the ID of every trip the request persisted and the IDs of the activities written under it — your handle for reading the stored data back later.

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.

***

## Reading data back

Ingestion is only half of it. The trip endpoints serve what SQUAKE stored:

| Endpoint                                         | Returns                                                                              |
| ------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `GET /v2/travel-data/trips`                      | Paginated list of your stored trips, newest ingested first.                          |
| `GET /v2/travel-data/trips/{id}`                 | A single trip, addressed by SQUAKE's `id` or your own `trip_reference`.              |
| `GET /v2/travel-data/trips/{trip_id}/activities` | The trip's activities, each with its traveler and the calculations persisted for it. |
| `DELETE /v2/travel-data/trips/{id}`              | Deletes the trip, its activities, and their calculations.                            |

A trip read returns the trip as SQUAKE stored it — name, purpose, status, dates, booking provider, amount, cost center — plus the **IDs** of its activities rather than the activities themselves, so the response stays small however many activities the trip holds. The activities, their travelers, their additional-methodology calculations and their audit references are read through the activities endpoint.

The `trips` array of a submission is narrower on purpose: it echoes the trip's identity (`id`, `trip_reference`, `client_id`, `submitted_by_client_id`, `activity_ids`) — the handle you need to read the rest back.

***

## Next steps

→ [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.

→ [Retrieve & Delete Travel Data](/travel-data/retrieve-travel-data.md) — read stored trips, activities, and calculations back, and delete a trip.