> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 🧪 Get Vehicle Carbon Emissions

> Estimate a vehicle's CO2 emissions over a date window from odometer-derived miles traveled and an emission factor based on the vehicle's GVWR class and fuel type, decoded from its VIN via the NHTSA vPIC registry.

**Method:** Tank-to-wheel (tailpipe combustion) only — does not include upstream well-to-tank fuel-production emissions. See `method` on the response.

**Factors:** kg CO2/vehicle-mile by GVWR class, from the EPA GHG Emission Factors Hub (Table 8, distance-based method, January 2025 edition): Class 1 (Passenger Car) 0.297, Class 1-2a (Light-Duty Truck) 0.394, Class 2b-8 (Medium-/Heavy-Duty Truck) 1.298 — https://www.epa.gov/system/files/documents/2025-01/ghg-emission-factors-hub-2025.pdf . See `factor_version` on the response for which table version produced a given figure. Electric and CNG vehicles aren't covered by this table and return a null factor/co2.

**Window:** Defaults to the trailing 30 days. Supply `from_date` and `to_date` to request a custom range (max 90 days).

**Nullability:** `miles_traveled`/`co2_kg` are null when an odometer reading isn't available at both boundaries of the window. `gvwr_class`/`fuel_type`/`vehicle_class_bucket`/`emission_factor_kg_per_mile` are null when the vehicle has no VIN on file or the VIN couldn't be decoded. `vehicle_class_bucket`/`emission_factor_kg_per_mile`/`co2_kg` are also null when `fuel_type` isn't covered by the factor table (electric, CNG). These are independent of each other.

<Callout icon="vial" color="#FFC107" iconType="solid"><strong>Provisional endpoint</strong><br />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.<br /><br /><em>See <a href="/api-reference/stability-versioning">API Stability & Versioning</a> for details on provisional endpoints.</em></Callout>


## OpenAPI

````yaml https://api.catenatelematics.com/v2/intelligence/openapi.json get /v2/intelligence/emission/vehicles/{vehicle_id}
openapi: 3.1.0
info:
  title: Telematics Intelligence Service - REST API
  description: Telematics Intelligence Service REST API.
  version: 0.1.0
servers:
  - url: https://api.catenatelematics.com
    description: Catena Intelligence API
security: []
tags:
  - name: Analytics
    description: >-
      Endpoints providing analytical insights and aggregated data for vehicles,
      fleets, drivers, and trailers.
  - name: Benchmarks
    description: >-
      Endpoints providing cross-fleet benchmark data. A vehicle's metrics are
      ranked against a cohort of peer vehicles drawn from the full Catena fleet
      population. Cohort statistics are k-anonymised: percentile and cohort
      counts are suppressed when the cohort covers too few distinct fleets to
      protect individual fleet privacy.
paths:
  /v2/intelligence/emission/vehicles/{vehicle_id}:
    get:
      tags:
        - Emissions
      summary: Get vehicle carbon emissions
      description: >-
        Estimate a vehicle's CO2 emissions over a date window from
        odometer-derived miles traveled and an emission factor based on the
        vehicle's GVWR class and fuel type, decoded from its VIN via the NHTSA
        vPIC registry.


        **Method:** Tank-to-wheel (tailpipe combustion) only — does not include
        upstream well-to-tank fuel-production emissions. See `method` on the
        response.


        **Factors:** kg CO2/vehicle-mile by GVWR class, from the EPA GHG
        Emission Factors Hub (Table 8, distance-based method, January 2025
        edition): Class 1 (Passenger Car) 0.297, Class 1-2a (Light-Duty Truck)
        0.394, Class 2b-8 (Medium-/Heavy-Duty Truck) 1.298 —
        https://www.epa.gov/system/files/documents/2025-01/ghg-emission-factors-hub-2025.pdf
        . See `factor_version` on the response for which table version produced
        a given figure. Electric and CNG vehicles aren't covered by this table
        and return a null factor/co2.


        **Window:** Defaults to the trailing 30 days. Supply `from_date` and
        `to_date` to request a custom range (max 90 days).


        **Nullability:** `miles_traveled`/`co2_kg` are null when an odometer
        reading isn't available at both boundaries of the window.
        `gvwr_class`/`fuel_type`/`vehicle_class_bucket`/`emission_factor_kg_per_mile`
        are null when the vehicle has no VIN on file or the VIN couldn't be
        decoded. `vehicle_class_bucket`/`emission_factor_kg_per_mile`/`co2_kg`
        are also null when `fuel_type` isn't covered by the factor table
        (electric, CNG). These are independent of each other.
      operationId: get_vehicle_emissions
      parameters:
        - name: vehicle_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Vehicle Id
        - name: from_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: >-
              Inclusive start of the emissions window. **Format:** YYYY-MM-DD
              **Default:** 30 days before yesterday. **Restriction:** `to_date -
              from_date` cannot exceed 90 days.
            examples:
              - null
            title: From Date
          description: >-
            Inclusive start of the emissions window. **Format:** YYYY-MM-DD
            **Default:** 30 days before yesterday. **Restriction:** `to_date -
            from_date` cannot exceed 90 days.
        - name: to_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: >-
              Inclusive end of the emissions window. **Format:** YYYY-MM-DD
              **Default:** yesterday. **Restriction:** `to_date - from_date`
              cannot exceed 90 days.
            examples:
              - null
            title: To Date
          description: >-
            Inclusive end of the emissions window. **Format:** YYYY-MM-DD
            **Default:** yesterday. **Restriction:** `to_date - from_date`
            cannot exceed 90 days.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleEmission'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not Found
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed'
          description: Method Not Allowed
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotImplementedResponse'
          description: Not Implemented
      security:
        - Bearer:
            - telematics:read
components:
  schemas:
    VehicleEmission:
      properties:
        vehicle_id:
          type: string
          format: uuid
          title: Vehicle Id
          description: Catena vehicle identifier.
        window:
          $ref: '#/components/schemas/VehicleEmissionWindow'
          description: Date range used for the estimate.
        vin:
          anyOf:
            - type: string
            - type: 'null'
          title: Vin
          description: VIN on file for the vehicle. Null if none is recorded.
        miles_traveled:
          anyOf:
            - type: number
            - type: 'null'
          title: Miles Traveled
          description: >-
            Odometer-derived miles traveled over the window. Null if an odometer
            reading is missing at either boundary.
        gvwr_class:
          anyOf:
            - type: string
            - type: 'null'
          title: Gvwr Class
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Fuel Type
          description: >-
            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:
          anyOf:
            - type: string
              enum:
                - '1'
                - 1-2a
                - 2b-8
            - type: 'null'
          title: Vehicle Class Bucket
          description: >-
            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).
        emission_factor_kg_per_mile:
          anyOf:
            - type: number
            - type: 'null'
          title: Emission Factor Kg Per Mile
          description: >-
            Emission factor applied (kg CO2 / vehicle-mile). Null under the same
            conditions as vehicle_class_bucket.
        co2_kg:
          anyOf:
            - type: number
            - type: 'null'
          title: Co2 Kg
          description: >-
            Estimated CO2 emissions in kg: miles_traveled x
            emission_factor_kg_per_mile. Null if either input is null.
        method:
          type: string
          const: tailpipe_only
          title: Method
          description: >-
            Emissions accounting method used. v1: always tank-to-wheel tailpipe
            combustion, no upstream fuel-production emissions.
          default: tailpipe_only
        factor_version:
          type: string
          title: Factor Version
          description: >-
            Version identifier for the emission-factor table used to compute
            this estimate.
          default: v2
      type: object
      required:
        - vehicle_id
        - window
        - vin
        - miles_traveled
        - gvwr_class
        - fuel_type
        - vehicle_class_bucket
        - emission_factor_kg_per_mile
        - co2_kg
      title: VehicleEmission
      description: >-
        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.
    BadRequest:
      properties:
        code:
          type: integer
          title: Code
          default: 400
        message:
          type: string
          title: Message
          default: Bad Request
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: BadRequest
    Unauthorized:
      properties:
        code:
          type: integer
          title: Code
          default: 401
        message:
          type: string
          title: Message
          default: Unauthorized
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: Unauthorized
    Forbidden:
      properties:
        code:
          type: integer
          title: Code
          default: 403
        message:
          type: string
          title: Message
          default: Forbidden
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: Forbidden
    NotFound:
      properties:
        code:
          type: integer
          title: Code
          default: 404
        message:
          type: string
          title: Message
          default: Not Found
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: NotFound
    MethodNotAllowed:
      properties:
        code:
          type: integer
          title: Code
          default: 405
        message:
          type: string
          title: Message
          default: Method Not Allowed
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: MethodNotAllowed
    Conflict:
      properties:
        code:
          type: integer
          title: Code
          default: 409
        message:
          type: string
          title: Message
          default: Conflict
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: Conflict
    UnprocessableEntity:
      properties:
        code:
          type: integer
          title: Code
          default: 422
        message:
          type: string
          title: Message
          default: Invalid Request Body
        detail:
          anyOf:
            - items:
                $ref: '#/components/schemas/ValidationErrorDetail'
              type: array
            - type: 'null'
          title: Detail
      type: object
      title: UnprocessableEntity
    TooManyRequests:
      properties:
        code:
          type: integer
          title: Code
          default: 429
        message:
          type: string
          title: Message
          default: Too Many Requests
        detail:
          anyOf:
            - $ref: '#/components/schemas/RetryAfterDetail'
            - type: 'null'
      type: object
      title: TooManyRequests
    InternalServerError:
      properties:
        message:
          type: string
          title: Message
          default: Internal Server Error
      type: object
      title: InternalServerError
    NotImplementedResponse:
      properties:
        code:
          type: integer
          title: Code
          default: 501
        message:
          type: string
          title: Message
          default: Not Implemented
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: NotImplementedResponse
    VehicleEmissionWindow:
      properties:
        from_date:
          type: string
          format: date
          title: From Date
          description: Inclusive start of the emissions window (YYYY-MM-DD).
        to_date:
          type: string
          format: date
          title: To Date
          description: Inclusive end of the emissions window (YYYY-MM-DD).
      type: object
      required:
        - from_date
        - to_date
      title: VehicleEmissionWindow
      description: Date range covered by an emission response.
    ValidationErrorDetail:
      properties:
        path:
          type: string
          title: Path
        input:
          type: string
          title: Input
        message:
          type: string
          title: Message
        error_type:
          type: string
          title: Error Type
      type: object
      required:
        - path
        - input
        - message
        - error_type
      title: ValidationErrorDetail
    RetryAfterDetail:
      properties:
        retry_after_seconds:
          type: integer
          title: Retry After Seconds
        message:
          type: string
          title: Message
      type: object
      required:
        - retry_after_seconds
        - message
      title: RetryAfterDetail
  securitySchemes:
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          refreshUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
          scopes: {}
          tokenUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
        authorizationCode:
          refreshUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
          scopes: {}
          authorizationUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/auth
          tokenUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token

````