Skip to main content
GET
Get vehicle carbon emissions
Provisional endpoint
This endpoint is available for early access. The core schema is stable, but minor details — such as field names or added fields — may change before it becomes generally available. Backward compatibility is not guaranteed.

See API Stability & Versioning for details on provisional endpoints.

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

vehicle_id
string<uuid>
required

Query Parameters

from_date
string<date> | null

Inclusive start of the emissions window. Format: YYYY-MM-DD Default: 30 days before yesterday. Restriction: to_date - from_date cannot exceed 90 days.

Example:

null

to_date
string<date> | null

Inclusive end of the emissions window. Format: YYYY-MM-DD Default: yesterday. Restriction: to_date - from_date cannot exceed 90 days.

Example:

null

Response

Successful Response

Estimated CO2 emissions for a single vehicle over a date window.

Estimate is miles_traveled x emission_factor_kg_per_mile, where miles_traveled comes from odometer readings and emission_factor_kg_per_mile is derived from the vehicle's GVWR class (decoded from its VIN via the NHTSA vPIC registry). method and factor_version always identify which methodology and factor table produced (or would have produced) the figure, regardless of whether this particular estimate could be computed.

method is tank-to-wheel (tailpipe combustion) only — it does not include upstream well-to-tank fuel-production emissions (roughly another 15-25% under GLEC/ISO 14083).

miles_traveled and co2_kg are null when an odometer reading isn't available at both boundaries of the window. gvwr_class, fuel_type, vehicle_class_bucket, and emission_factor_kg_per_mile are null when the vehicle has no VIN on file or the VIN can't be decoded (NHTSA timeout/error, or VIN not recognized). vehicle_class_bucket, emission_factor_kg_per_mile, and co2_kg are also null when gvwr_class doesn't map to a recognized class, or when fuel_type is one this factor table doesn't cover (electric, CNG) — fuel_type itself stays populated in that case so the reason is visible. These are independent: e.g. class/factor can be populated while miles/co2 are null, or vice versa. No field being null ever produces an error response — an estimate is only computed when every required input is available and supported.

vehicle_id
string<uuid>
required

Catena vehicle identifier.

window
VehicleEmissionWindow · object
required

Date range used for the estimate.

vin
string | null
required

VIN on file for the vehicle. Null if none is recorded.

miles_traveled
number | null
required

Odometer-derived miles traveled over the window. Null if an odometer reading is missing at either boundary.

gvwr_class
string | null
required

Raw GVWR value decoded from the VIN via NHTSA vPIC (e.g. 'Class 8: 33,001 lb and above'). Null if the VIN is missing/undecodable or NHTSA is unavailable.

fuel_type
string | null
required

Raw FuelTypePrimary value decoded from the VIN via NHTSA vPIC (e.g. 'Diesel', 'Electric'). Null under the same conditions as gvwr_class.

vehicle_class_bucket
enum<string> | null
required

Emission-factor bucket the GVWR class mapped to. Null under the same conditions as gvwr_class, if GVWR didn't match a recognized class, or if fuel_type isn't covered by this factor table (electric, CNG).

Available options:
1,
1-2a,
2b-8
emission_factor_kg_per_mile
number | null
required

Emission factor applied (kg CO2 / vehicle-mile). Null under the same conditions as vehicle_class_bucket.

co2_kg
number | null
required

Estimated CO2 emissions in kg: miles_traveled x emission_factor_kg_per_mile. Null if either input is null.

method
string
default:tailpipe_only

Emissions accounting method used. v1: always tank-to-wheel tailpipe combustion, no upstream fuel-production emissions.

Allowed value: "tailpipe_only"
factor_version
string
default:v2

Version identifier for the emission-factor table used to compute this estimate.