openapi: 3.0.3
info:
  title: Fuel Economy Web Services Emissions User MPG Menus API
  description: RESTful web services providing official EPA fuel economy ratings, vehicle specifications, CO2 emissions records, current fuel prices, and community-contributed real-world MPG data for passenger cars and light trucks from 1984 through the current model year. Administered by Oak Ridge National Laboratory for the US Department of Energy and the EPA. All endpoints are free and require no authentication. Responses are returned in XML format.
  version: '1.0'
  contact:
    name: FuelEconomy.gov Feedback
    email: fueleconomy@ornl.gov
  x-api-id: fueleconomy:fuel-economy-web-services
  license:
    name: Public Domain (US Government Work)
    url: https://www.usa.gov/government-works
servers:
- url: https://www.fueleconomy.gov/ws/rest
  description: FuelEconomy.gov REST API
tags:
- name: User MPG Menus
  description: Navigation menus for community MPG data lookup
paths:
  /ympg/shared/menu/make:
    get:
      operationId: getUserMpgMenuMakes
      summary: Get makes with community MPG data
      description: Returns a list of vehicle makes for which community-contributed real-world MPG data exists. Spans historical makes including discontinued brands. Use the returned make values with the /ympg/shared/menu/model endpoint.
      tags:
      - User MPG Menus
      responses:
        '200':
          description: List of makes with shared MPG data
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/MenuItems'
  /ympg/shared/menu/model:
    get:
      operationId: getUserMpgMenuModels
      summary: Get models with community MPG data for a make
      description: Returns a list of vehicle models for the specified make for which community-contributed real-world MPG data exists. Use the returned values with the /ympg/shared/vehicles endpoint.
      tags:
      - User MPG Menus
      parameters:
      - $ref: '#/components/parameters/makeQuery'
      responses:
        '200':
          description: List of models with shared MPG data
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/MenuItems'
  /ympg/shared/vehicles:
    get:
      operationId: getUserMpgVehicles
      summary: Get vehicles with community MPG data for a make and model
      description: Returns a list of vehicle records for the specified make and model that have community-contributed real-world MPG data. Each record contains full EPA fuel economy specifications and can be used to retrieve user MPG summaries via /ympg/shared/ympgVehicle/{id}.
      tags:
      - User MPG Menus
      parameters:
      - $ref: '#/components/parameters/makeQuery'
      - $ref: '#/components/parameters/modelQuery'
      responses:
        '200':
          description: List of vehicle records with shared MPG data
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/VehicleList'
components:
  schemas:
    EmissionsInfo:
      type: object
      description: EPA tailpipe emissions certification record for a specific sales territory
      properties:
        efid:
          type: string
          description: Emissions family identifier (EPA certification code)
        id:
          type: integer
          description: Vehicle ID
        salesArea:
          type: integer
          description: Sales territory code (e.g., 3 = 49-state, 7 = California)
        score:
          type: number
          format: double
          description: Air pollution score (1-10 scale; -1 if not rated)
        scoreAlt:
          type: number
          format: double
          description: Air pollution score for alternative fuel; -1 if not rated
        smartwayScore:
          type: integer
          description: SmartWay score (-1 if not rated)
        standard:
          type: string
          description: Emissions standard code (e.g., B5, B8, LEV2-ULEV)
        stdText:
          type: string
          description: Human-readable emissions standard (e.g., "Bin 5", "LEV2-ULEV")
    EmissionsResponse:
      type: object
      description: Container for one or more emissions certification records
      properties:
        emissionsInfo:
          oneOf:
          - $ref: '#/components/schemas/EmissionsInfo'
          - type: array
            items:
              $ref: '#/components/schemas/EmissionsInfo'
    MenuItem:
      type: object
      description: A single selectable option in a navigation menu
      properties:
        text:
          type: string
          description: Human-readable display label
        value:
          type: string
          description: Machine-readable value to pass as query parameter or path segment. For the /vehicle/menu/options endpoint, this is the numeric vehicle ID.
    VehicleList:
      type: object
      description: List of vehicle records
      properties:
        vehicle:
          oneOf:
          - $ref: '#/components/schemas/Vehicle'
          - type: array
            items:
              $ref: '#/components/schemas/Vehicle'
    Vehicle:
      type: object
      description: Full EPA fuel economy and specification record for a single vehicle configuration (year/make/model/trim/option).
      properties:
        id:
          type: integer
          description: Unique vehicle identifier
        year:
          type: integer
          description: Model year
        make:
          type: string
          description: Vehicle manufacturer
        model:
          type: string
          description: Vehicle model and trim designation
        baseModel:
          type: string
          description: Base model name without trim suffix
        atvType:
          type: string
          description: Alternative fuel vehicle type code (e.g., FFV for flex-fuel, EV, Hybrid, PHEV, FCV)
        city08:
          type: integer
          description: City MPG for primary fuel (EPA rating)
        city08U:
          type: number
          format: double
          description: Unrounded city MPG for primary fuel
        cityA08:
          type: integer
          description: City MPG for alternative fuel (e.g., E85)
        cityA08U:
          type: number
          format: double
          description: Unrounded city MPG for alternative fuel
        highway08:
          type: integer
          description: Highway MPG for primary fuel (EPA rating)
        highway08U:
          type: number
          format: double
          description: Unrounded highway MPG for primary fuel
        highwayA08:
          type: integer
          description: Highway MPG for alternative fuel
        highwayA08U:
          type: number
          format: double
          description: Unrounded highway MPG for alternative fuel
        comb08:
          type: integer
          description: Combined MPG for primary fuel (EPA rating, 55% hwy / 45% city)
        comb08U:
          type: number
          format: double
          description: Unrounded combined MPG for primary fuel
        combA08:
          type: integer
          description: Combined MPG for alternative fuel
        combA08U:
          type: number
          format: double
          description: Unrounded combined MPG for alternative fuel
        fuelType:
          type: string
          description: Fuel type description (e.g., "Regular Gasoline", "Gasoline or E85")
        fuelType1:
          type: string
          description: Primary fuel type
        fuelType2:
          type: string
          description: Secondary/alternative fuel type
        cylinders:
          type: integer
          description: Number of engine cylinders
        displ:
          type: number
          format: double
          description: Engine displacement in liters
        trany:
          type: string
          description: Transmission description (e.g., "Automatic 4-spd", "CVT")
        drive:
          type: string
          description: Drive axle type (e.g., "Front-Wheel Drive", "All-Wheel Drive")
        VClass:
          type: string
          description: EPA vehicle size class
        co2TailpipeGpm:
          type: number
          format: double
          description: CO2 tailpipe emissions in grams per mile for primary fuel
        co2TailpipeAGpm:
          type: number
          format: double
          description: CO2 tailpipe emissions in grams per mile for alternative fuel
        fuelCost08:
          type: integer
          description: Estimated annual fuel cost in USD for primary fuel
        fuelCostA08:
          type: integer
          description: Estimated annual fuel cost in USD for alternative fuel
        barrels08:
          type: number
          format: double
          description: Barrels of oil used per year for primary fuel
        barrelsA08:
          type: number
          format: double
          description: Barrels of oil used per year for alternative fuel
        ghgScore:
          type: integer
          description: EPA greenhouse gas score (1-10 scale; -1 if not rated)
        ghgScoreA:
          type: integer
          description: EPA greenhouse gas score for alternative fuel
        feScore:
          type: integer
          description: EPA fuel economy score (1-10 scale; -1 if not rated)
        co2:
          type: integer
          description: CO2 emissions (g/mile) from official test; -1 if not available
        co2A:
          type: integer
          description: CO2 emissions for alternative fuel; -1 if not available
        smartwayScore:
          type: integer
          description: SmartWay environmental score (-1 if not rated)
        guzzler:
          type: string
          description: Gas guzzler tax designation if applicable
        mfrCode:
          type: string
          description: Manufacturer code
        engId:
          type: integer
          description: Engine identifier
        eng_dscr:
          type: string
          description: Engine descriptor (e.g., GUZZLER, TURBO, FFV)
        trans_dscr:
          type: string
          description: Transmission descriptor codes
        sCharger:
          type: string
          description: Supercharger indicator
        tCharger:
          type: string
          description: Turbocharger indicator
        startStop:
          type: string
          description: Start-stop technology indicator
        cylDeact:
          type: string
          description: Cylinder deactivation indicator code
        cylDeactYesNo:
          type: string
          description: Cylinder deactivation human-readable (Yes/No)
        mpgData:
          type: string
          description: Source of MPG data indicator (Y = EPA tested, N = estimated)
        mpgRevised:
          type: boolean
          description: Whether MPG data has been revised
        phevBlended:
          type: boolean
          description: Whether PHEV operates in blended mode
        phevCity:
          type: integer
          description: PHEV city MPGe
        phevHwy:
          type: integer
          description: PHEV highway MPGe
        phevComb:
          type: integer
          description: PHEV combined MPGe
        range:
          type: integer
          description: Electric range in miles (for EVs/PHEVs)
        rangeA:
          type: integer
          description: Range on alternative fuel
        charge120:
          type: number
          format: double
          description: Hours to charge on 120V outlet
        charge240:
          type: number
          format: double
          description: Hours to charge on 240V outlet
        battery:
          type: number
          format: double
          description: Battery capacity in kWh (-1 if not applicable)
        evMotor:
          type: string
          description: Electric motor description
        combE:
          type: number
          format: double
          description: Combined electricity consumption (kWh/100mi)
        cityE:
          type: number
          format: double
          description: City electricity consumption (kWh/100mi)
        highwayE:
          type: number
          format: double
          description: Highway electricity consumption (kWh/100mi)
        youSaveSpend:
          type: integer
          description: Estimated 5-year fuel cost savings (positive) or additional spend (negative) versus average new vehicle
        hlv:
          type: integer
          description: Hatchback luggage volume (cu ft)
        hpv:
          type: integer
          description: Hatchback passenger volume (cu ft)
        lv2:
          type: integer
          description: 2-door luggage volume (cu ft)
        lv4:
          type: integer
          description: 4-door luggage volume (cu ft)
        pv2:
          type: integer
          description: 2-door passenger volume (cu ft)
        pv4:
          type: integer
          description: 4-door passenger volume (cu ft)
        emissionsList:
          $ref: '#/components/schemas/EmissionsResponse'
        createdOn:
          type: string
          format: date-time
          description: Date/time the record was created
        modifiedOn:
          type: string
          format: date-time
          description: Date/time the record was last modified
    MenuItems:
      type: object
      description: Collection of navigation menu items for vehicle lookup
      properties:
        menuItem:
          oneOf:
          - $ref: '#/components/schemas/MenuItem'
          - type: array
            items:
              $ref: '#/components/schemas/MenuItem'
  parameters:
    modelQuery:
      name: model
      in: query
      required: true
      description: Vehicle model name (e.g., Camry LE/SE). Must match a value from the model menu.
      schema:
        type: string
        example: Corolla
    makeQuery:
      name: make
      in: query
      required: true
      description: Vehicle manufacturer name (e.g., Toyota, Ford). Must match a value from the make menu.
      schema:
        type: string
        example: Toyota
externalDocs:
  description: Official API Documentation
  url: https://www.fueleconomy.gov/feg/ws/index.shtml