Jobs API

POST /jobs

Submit a transport job and receive an NGER Method 1 emission calculation.

POST https://<project-ref>.supabase.co/functions/v1/jobs-api/jobs
Authorization: Bearer ew_<your-api-key>
Content-Type: application/json

Request body

{
  "job": {
    "origin": "string",
    "destination": "string",
    "reference_number": "string (optional)",
    "client_id": "uuid (optional)",
    "distance": 0,
    "departure_date": "2024-08-01T06:00:00Z",
    "arrival_date": "2024-08-01T18:00:00Z",
    "cargo_weight_tonnes": 0
  },
  "calculation": {
    "transport_mode": "road",
    "fuel_type": "diesel",
    "vehicle_class": "heavy_vehicle_euro4",
    "fuel_quantity": 85.4
  }
}

job object fields

Field	Type	Required	Constraints	Description
origin	string	Yes	Non-empty	Origin location
destination	string	Yes	Non-empty	Destination location
reference_number	string	No	—	Idempotency key. Duplicate submissions with the same value return the original result
client_id	UUID	No	Must exist in your org	Links the job to a client for per-client reporting
distance	number	No	0–99,999	Distance in km (stored, not used in calculation)
departure_date	ISO 8601	No	—	Used to determine the NGER reporting year. Preferred over arrival_date
arrival_date	ISO 8601	No	—	Fallback date for reporting year if departure_date is absent
cargo_weight_tonnes	number	No	—	Cargo weight in tonnes (stored, not used in calculation)

calculation object fields

Field	Type	Required	Constraints	Description
transport_mode	string	Yes	See table below	Transport mode code
fuel_type	string	Yes	Must be valid for the mode	Fuel type code
fuel_quantity	number	Yes	> 0, ≤ 999,999	Fuel consumed in kilolitres (kL)
vehicle_class	string	Conditional	See table below	Required for road diesel; recommended for all

Valid transport mode / fuel type / vehicle class combinations

transport_mode	fuel_type	vehicle_class	Notes
road	diesel	heavy_vehicle_euro4	Euro IV+ heavy vehicles (post-2006)
road	diesel	heavy_vehicle_euro3	Euro III heavy vehicles (~2001–2006)
road	diesel	heavy_vehicle_euro1	Euro I heavy vehicles (~pre-2001)
road	diesel	light_vehicle_post2004_diesel	Diesel light vehicles post-2004
road	diesel	road_vehicle_unspecified_diesel	Diesel vehicles, pre-2004 or unknown standard
road	petrol	light_vehicle_post2004_petrol	Petrol light vehicles post-2004
road	petrol	road_vehicle_unspecified_petrol	Petrol vehicles, pre-2004 or unknown
road	lpg	light_vehicle_post2004_lpg	LPG light vehicles post-2004
rail	diesel_rail	diesel_locomotive	Diesel rail traction
aviation	jet_a1	jet_aircraft	Jet kerosene aircraft
aviation	avgas	turboprop	Avgas / turboprop aircraft
sea	hfo	vessel_fuel_oil	Heavy fuel oil vessels
sea	mdo	vessel_diesel	Marine diesel oil vessels

The API accepts both type codes (e.g. road) and display names (e.g. Road) — matching is case-insensitive.

Success response — 201 Created

{
  "success": true,
  "idempotent": false,
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "calculation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "reporting_year": 2025,
  "emissions": {
    "total_emissions": 22.87,
    "scope1_emissions": 22.20,
    "scope3_emissions": 0.67,
    "co2_emissions": 22.07,
    "ch4_emissions": 0.02,
    "n2o_emissions": 0.13,
    "energy_content": 3296.44
  },
  "transport_info": {
    "transport_mode": "Road",
    "transport_code": "road",
    "fuel_type": "Diesel",
    "fuel_code": "diesel"
  }
}

All emission values are in tonnes CO₂-e. energy_content is in GJ.

When an idempotent duplicate is detected, the response is 200 OK with "idempotent": true and the original job_id, calculation_id, and emission values.

Example request

curl -X POST https://<project-ref>.supabase.co/functions/v1/jobs-api/jobs \
  -H "Authorization: Bearer ew_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "job": {
      "origin": "Sydney",
      "destination": "Melbourne",
      "reference_number": "TRP-20240801-001",
      "distance": 869,
      "departure_date": "2024-08-01T06:00:00Z",
      "cargo_weight_tonnes": 22.5
    },
    "calculation": {
      "transport_mode": "road",
      "fuel_type": "diesel",
      "vehicle_class": "heavy_vehicle_euro4",
      "fuel_quantity": 85.4
    }
  }'

Error responses

401 — Missing or invalid API key

{
  "error": "Missing Authorization header",
  "code": "UNAUTHORIZED",
  "details": {}
}

400 — Validation error

{
  "error": "fuel_quantity must be greater than 0",
  "code": "VALIDATION_ERROR",
  "details": {
    "fields": [
      { "field": "fuel_quantity", "message": "fuel_quantity must be greater than 0" }
    ]
  }
}

422 — Vehicle class required

{
  "error": "Multiple factors exist — specify vehicle_class",
  "code": "VEHICLE_CLASS_REQUIRED",
  "details": {
    "available_classes": [
      { "class_code": "heavy_vehicle_euro4", "display_name": "Heavy vehicle — Euro IV or higher" },
      { "class_code": "heavy_vehicle_euro3", "display_name": "Heavy vehicle — Euro III" },
      { "class_code": "heavy_vehicle_euro1", "display_name": "Heavy vehicle — Euro I" },
      { "class_code": "light_vehicle_post2004_diesel", "display_name": "Light vehicle — post-2004 (diesel)" },
      { "class_code": "road_vehicle_unspecified_diesel", "display_name": "Road vehicle — unspecified/pre-2004 (diesel)" }
    ]
  }
}

422 — No emission factor found

{
  "error": "No emission factor found for reporting year 2022",
  "code": "FACTOR_NOT_FOUND",
  "details": {
    "reporting_year": 2022,
    "transport_mode": "road",
    "fuel_type": "diesel"
  }
}

429 — Rate limit exceeded

{
  "error": "Rate limit exceeded. Maximum 1000 requests per hour per API key.",
  "code": "RATE_LIMITED",
  "details": {
    "limit": 1000,
    "reset": "2024-08-01T09:00:00.000Z"
  }
}