# MyCO2 Suite — Freight Emissions API

> The freight endpoint calculates logistics CO₂e from weight and distance across road, rail, sea and air — single-leg or multi-leg intermodal. Locations accept UN/LOCODE, IATA, free-text names or coordinates; the response returns tonne-kilometres, distance and the mode factor with its provenance.

Endpoint: POST https://api.myco2suite.io/v1/freight
Price: $0.003 / call (from the first call). Pay with an API key (x-api-key) or, with no signup, via x402 pay-per-call in USDC on Base — a keyless request returns HTTP 402 with machine-readable payment requirements.
Free tier: 1,000 calls/month with a key (get one at https://myco2suite.io).

## Inputs
- weight_kg (required): Shipment weight in kilograms (> 0)
- mode (required): sea | road | rail | air (single-leg)
- origin (required): UN/LOCODE, IATA, name, or origin_lat + origin_lon
- destination (required): UN/LOCODE, IATA, name, or destination_lat + destination_lon
- legs (optional): Multi-leg: array of { mode, origin, destination } (omit top-level mode/origin/destination)

## Example request
POST https://api.myco2suite.io/v1/freight
Header: content-type: application/json
Header: x-api-key: <your key>   # or pay per call via x402 (no key)
Body: {"mode":"sea","weight_kg":20000,"origin":"GBSOU","destination":"SGSIN"}

## Example response (JSON)
{
  "co2e_kg": 1520.44,
  "co2e_tonnes": 1.52044,
  "route": {
    "distance_km": 15320.5,
    "tonne_km": 306410
  },
  "factor": {
    "unit": "kgCO2e/tonne.km",
    "source": "IMO GHG Study"
  }
}

Every response is methodology-stamped: it includes the exact factor value, unit, source, licence, data year, gas basis (CO2 vs CO2e) and GWP version used.

## Common use cases
- Supply-chain & logistics Scope 3.4 / 3.9 reporting
- Compare shipping modes (sea vs air vs rail) by carbon
- Footprint multi-leg intermodal shipments in one call

## Related capabilities
- https://myco2suite.io/carbon/flight (flight)
- https://myco2suite.io/carbon/activity (activity)
- https://myco2suite.io/carbon/cbam (cbam)

## Links
- Human page: https://myco2suite.io/carbon/freight
- Full API docs: https://myco2suite.io/docs
- Full agent/LLM docs: https://api.myco2suite.io/llms.txt
- Code examples: https://github.com/Jaws22/myco2-examples
- MCP server: https://api.myco2suite.io/v1/mcp (registry: io.myco2suite/carbon-intelligence)
- Contact: admin@myco2suite.io