openapi: 3.0.0
servers:
  - url: /api/transportation-incentives-laws
info:
  contact:
    x-twitter: NRELdev
  description: Query our database of federal and state laws and incentives for alternative fuels and vehicles, air quality, fuel efficiency, and other transportation-related topics. This dataset powers the <a href="https://afdc.energy.gov/laws">Federal and State Laws and Incentives</a> on the Alternative Fuels Data Center.
  title: Transportation Laws and Incentives
  version: 0.1.0
  x-apisguru-categories:
    - open_data
  x-logo:
    backgroundColor: "#0079C5"
    url: https://twitter.com/NRELdev/profile_image?size=original
  x-origin:
    - converter:
        url: https://github.com/mermade/oas-kit
        version: 2.0.1
      format: openapi
      url: http://developer.nrel.gov/docs/transportation/transportation-incentives-laws-v1/spec.yml
      version: "3.0"
  x-providerName: nrel.gov
  x-serviceName: transportation-incentives-laws
paths:
  "/v1.{output_format}":
    get:
      description: ""
      operationId: transportation_incentives_laws_all
      parameters:
        - description: Response format
          in: path
          name: output_format
          required: true
          schema:
            default: json
            enum:
              - json
              - xml
              - csv
            type: string
        - description: API Key
          in: query
          name: api_key
          required: true
          schema:
            default: DEMO_KEY
            type: string
        - description: Limit the number of laws returned
          in: query
          name: limit
          required: false
          schema:
            default: 10
            type: integer
        - description: Return laws for the given Jurisdiction. Jurisdiction must be given as a two character state code (eg, 'CO' for Colorado). A single jurisdiction, or a comma-separate list of multiple jurisdiction, may be given.  Use the code 'US' for federal laws and the code 'DC' for Washington D.C.
          in: query
          name: jurisdiction
          required: false
          schema:
            type: string
        - description: "Search by the technology type. A single type, or a comma-separate list of multiple types, may be given. Values and what they stand for are as follows: 'BIOD' for Biodiesel, 'ETH' for Ethanol / Flexible Fuel Vehicles, 'NG' for Natural Gas / Natural Gas Vehicles, 'LPG' for Liquefied Petroleum Gas (Propane) / Propane Vehicles, 'HY' for Hydrogen / Fuel Cell Electric Vehicles, 'ELEC' for All-Electric Vehicles (EVs), 'PHEV' for Plug-In Hybrid Electric Vehicles (PHEVs), 'HEV' for Hybrid Electric Vehicles (HEVs), 'NEVS' for Neighborhood Electric Vehicles (NEVs), 'RD' for Renewable Diesel, 'AFTMKTCONV' for Aftermarket Conversions, 'EFFEC' for Fuel Economy / Efficiency, 'IR' for Idle Reduction, 'AUTONOMOUS' for Connected and Autonomous Vehicles, and 'OTHER' for Other."
          in: query
          name: technology
          required: false
          schema:
            type: string
        - description: "Search by the incentive type. A single type, or a comma-separate list of multiple types, may be given. Values and what they stand for are as follows: 'GNT' for Grants, 'TAX' for Tax Incentives, 'LOANS' for Loans and Leases, 'RBATE' for Rebates, 'EXEM' for Exemptions, 'TOU' for Time-of-Use Rate, and 'OTHER' for Other."
          in: query
          name: incentive_type
          required: false
          schema:
            type: string
        - description: "Search by the regulation type. A single type, or a comma-separate list of multiple types, may be given. Values and what they stand for are as follows: 'REQ' for Acquisition / Fuel Use, 'DREST' for Driving / Idling, 'REGIS' for Registration / Licensing, 'EVFEE' for EV Registration Fee, 'FUEL' for Fuel Taxes, 'STD' for Fuel Production / Quality, 'RFS' for Renewable Fuel Standard / Mandate, 'AIRQEMISSIONS' for Air Quality / Emissions, 'CCEINIT' for Climate Change / Energy Initiatives, 'UTILITY' for Utility Definition, 'BUILD' for Building Codes, 'RTC' for Right-to-Charge, and 'OTHER' for Other."
          in: query
          name: regulation_type
          required: false
          schema:
            type: string
        - description: "Search by the user type. A single type, or a comma-separate list of multiple types, may be given. Values and what they stand for are as follows: 'FLEET' for Commercial, 'GOV' for Government Entity, 'TRIBAL' for Tribal Government, 'IND' for Personal Vehicle Owner or Driver, 'STATION' for Alternative Fuel Infrastructure Operator, 'AFP' for Alternative Fuel Producer, 'PURCH' for Alternative Fuel Purchaser, 'MAN' for Alternative Fuel Vehicle (AFV) Manufacturer or Retrofitter, 'MUD' for Multi-Unit Dwelling, 'TRANS' for Transit, and 'OTHER' for Other."
          in: query
          name: user_type
          required: false
          schema:
            type: string
        - description: Include points of contacts in the return value.
          in: query
          name: poc
          required: false
          schema:
            default: false
            type: boolean
        - description: Return only recently added or updated laws and incentives
          in: query
          name: recent
          required: false
          schema:
            default: false
            type: boolean
        - description: The 'true' value returns only expired, repealed, or archived laws and incentives. The default 'false' value returns only current laws and incentives.
          in: query
          name: expired
          required: false
          schema:
            default: false
            type: boolean
        - description: "Search by the law type. A single type, or a comma-separate list of multiple types, may be given. Values are as follows: 'STATEINC' for State Incentives, 'UPINC ' for Utility/Private Incentives, 'LAWREG' for Laws and Regulations, 'INC' for Incentives, 'PROG' for Programs, 'LUP' for Last Updated, 'OVIEW' for Overview, and 'HILITE' for Highlights."
          in: query
          name: law_type
          required: false
          schema:
            type: string
        - description: Search laws by keyword in title or text.
          in: query
          name: keyword
          required: false
          schema:
            type: string
        - description: Show only local examples of laws and incentives.
          in: query
          name: local
          required: false
          schema:
            default: false
            type: boolean
      responses:
        "200":
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/LawsResponse"
          description: Successful request
      summary: Return a full list of laws and incentives that match your query.
  "/v1/category-list.{output_format}":
    get:
      description: ""
      operationId: transportation_incentives_laws_categories
      parameters:
        - description: Response format
          in: path
          name: output_format
          required: true
          schema:
            default: json
            enum:
              - json
              - xml
            type: string
        - description: API Key
          in: query
          name: api_key
          required: true
          schema:
            default: DEMO_KEY
            type: string
        - description: Search by the category type.
          in: query
          name: type
          required: false
          schema:
            enum:
              - tech
              - user
              - regulation
              - incentive
            type: string
      responses:
        "200":
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CategoryResults"
          description: Successful request
      summary: Return the law categories for a given category type.
  "/v1/pocs.{output_format}":
    get:
      description: ""
      operationId: transportation_incentives_laws_pocs
      parameters:
        - description: Response format
          in: path
          name: output_format
          required: true
          schema:
            default: json
            enum:
              - json
              - xml
            type: string
        - description: API Key
          in: query
          name: api_key
          required: true
          schema:
            default: DEMO_KEY
            type: string
        - description: Return the points of contact for the given Jurisdiction. Jurisdiction must be given as a two character state code (eg, 'CO' for Colorado). A single jurisdiction, or a comma-separate list of multiple jurisdiction, may be given.  Use the code 'US' for federal laws and the code 'DC' for Washington D.C.
          in: query
          name: jurisdiction
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/PocResults"
          description: Successful request
      summary: Get the points of contact for a given jurisdiction.
  "/v1/{id}.{output_format}":
    get:
      description: ""
      operationId: transportation_incentives_laws_id
      parameters:
        - description: Response format
          in: path
          name: output_format
          required: true
          schema:
            default: json
            enum:
              - json
              - xml
            type: string
        - description: API Key
          in: query
          name: api_key
          required: true
          schema:
            default: DEMO_KEY
            type: string
        - description: The id of the law that you are searching
          in: path
          name: id
          required: true
          schema:
            type: integer
        - description: Include points of contacts in the return value.
          in: query
          name: poc
          required: false
          schema:
            default: false
            type: boolean
        - description: The 'true' value returns a record no matter its status (current, expired, archived, or repealed). The default 'false' value returns only current laws and incentives.
          in: query
          name: expired
          required: false
          schema:
            default: false
            type: boolean
      responses:
        "200":
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/LawResult"
          description: Successful request
      summary: Fetch the details of a specific law given the law's ID.
components:
  schemas:
    Category:
      description: A category that the law applies to
      properties:
        category_type:
          description: The type of category. (E.g. tech, incentive, regulation, user)
          type: string
        code:
          description: The code used to identify the category
          type: string
        title:
          description: The full name of the category
          type: string
      required:
        - code
        - title
        - category_type
    CategoryResults:
      properties:
        inputs:
          $ref: "#/components/schemas/Inputs"
        metadata:
          $ref: "#/components/schemas/Metadata"
        result:
          description: The array of law categories returned
          items:
            $ref: "#/components/schemas/FullCategory"
          type: array
      required:
        - metadata
        - inputs
        - result
    FullCategory:
      properties:
        category_type:
          description: The type of category. (E.g. tech, incentive, regulation, user)
          type: string
        code:
          description: The code used to identify the category
          type: string
        help_text:
          description: A short description of what the law category encompasses
          type: string
        sort_order:
          description: The sort order for the categories
          type: string
        title:
          description: The full name of the category
          type: string
      required:
        - code
        - title
        - category_type
        - sort_order
    Inputs:
      description: The parameters that were passed to the API
      properties: {}
    Law:
      description: This is a Law
      properties:
        agency:
          description: The agency with primary responsibility for federal incentives/regulations.
          type: string
        amended_date:
          description: The date the incentive/law/regulation was updated through new legislation or rulemaking.
          format: date-time
          type: string
        archived_date:
          description: The date that an incentive/law/regulation is no longer relevant to the database. This may include longstanding Executive Orders or laws requiring legislative studies that have been completed.
          format: date-time
          type: string
        categories:
          description: The various law categories that apply to this law
          items:
            $ref: "#/components/schemas/Category"
          type: array
        contacts:
          description: The contacts for the given law, returned only if the parameter poc is true
          items:
            $ref: "#/components/schemas/Poc"
          type: array
        enacted_date:
          description: The date the enacting legislation (if applicable) was signed into law.
          format: date-time
          type: string
        expired_date:
          description: The date the incentive/law/regulation is set to end.
          format: date-time
          type: string
        id:
          description: A unique identifier for this specific incentive/law/regulation.
          type: integer
        is_recent:
          description: The true or false value used to distinguish between recent federal executive actions (TRUE) and active incentives/laws/regulations (FALSE).
          type: boolean
        plaintext:
          description: Description of the incentive/law/regulation, including applicable legislative references, in <a href="https://guides.github.com/features/mastering-markdown/">markdown formatting</a>
          type: string
        recent_update_or_new:
          description: An indicator if the last significant update was an update or the laws creation.
          type: string
        references:
          description: The URL associated with any bill or legislative reference included in the description.
          items:
            $ref: "#/components/schemas/LawReference"
          type: array
        repealed_date:
          description: The date legislation is enacted or a rulemaking is finalized to repeal the incentive/law/regulation.
          format: date-time
          type: string
        seq_num:
          description: The numerical value assigned to a description to show the order in which it is displayed online within a jurisdiction (state).
          type: integer
        significant_update_date:
          description: When the last significant update to the law was made.
          format: date-time
          type: string
        state:
          description: The state in which the incentive/law/regulation was enacted and is active.
          type: string
        text:
          description: Description of the incentive/law/regulation, including applicable legislative references, html formated.
          type: string
        title:
          description: The brief title assigned to the incentive/law/regulation description.
          type: string
        topics:
          description: "For local incentive/regulation descriptions, the category that the incentive/regulation falls under, described below: Infrastructure Requirements, Vehicle Purchase and Infrastructure Development Incentives, Fuel Use Incentives, Parking Incentives, Technical Assistance, Vehicle Acquisition Requirements, Promotion Initiatives, Idle Reduction Requirements, Renewable Fuels Mandates and Standards"
          items:
            $ref: "#/components/schemas/LawTopics"
          type: array
        type:
          description: "The category that the incentive/law/regulation falls under, described below: -State Incentives, -Laws and Regulations, -Utility/Private Incentives"
          type: string
        types:
          description: The types that apply to this law
          items:
            $ref: "#/components/schemas/LawType"
          type: array
      required:
        - id
        - state
        - title
        - text
        - plaintext
        - type
        - categories
        - types
        - references
        - topics
    LawReference:
      description: The URL associated with any bill or legislative reference included in the description.
      properties:
        description:
          description: The context of the reference
          type: string
        url:
          description: The url linking to the reference.
          type: string
      required:
        - description
        - url
    LawResult:
      properties:
        inputs:
          $ref: "#/components/schemas/Inputs"
        metadata:
          $ref: "#/components/schemas/Metadata"
        result:
          $ref: "#/components/schemas/Law"
      required:
        - metadata
        - inputs
        - result
    LawTopics:
      description: "For local incentive/regulation descriptions, the category that the incentive/regulation falls under, described below: Infrastructure Requirements, Vehicle Purchase and Infrastructure Development Incentives, Fuel Use Incentives, Parking Incentives, Technical Assistance, Vehicle Acquisition Requirements, Promotion Initiatives, Idle Reduction Requirements, Renewable Fuels Mandates and Standards"
      properties:
        id:
          description: The database id of the law topic
          type: integer
        sort_order:
          description: The sort order of the law topic
          type: integer
        title:
          description: The name of the law topic
          type: string
      required:
        - id
        - title
        - sort_order
    LawType:
      description: "The category that the incentive/law/regulation falls under, described below: -State Incentives, -Laws and Regulations, -Utility/Private Incentives"
      properties:
        code:
          description: The code used to identify the law type
          type: string
        id:
          description: The id of the law type
          type: integer
        title:
          description: The name of the law type
          type: string
      required:
        - id
        - title
        - code
    LawsResponse:
      properties:
        inputs:
          $ref: "#/components/schemas/Inputs"
        metadata:
          $ref: "#/components/schemas/Metadata"
        result:
          description: The array of laws returned
          items:
            $ref: "#/components/schemas/Law"
          type: array
      required:
        - metadata
        - inputs
        - result
    Metadata:
      description: The identifying metadata.
      properties:
        count:
          description: If the request returns an array of results, this is the number of results returned in the array
          type: integer
        version:
          description: This is the version of the api
          type: string
      required:
        - version
    Poc:
      properties:
        agency:
          description: The agency that the contact represents
          type: string
        email:
          description: The contacts email address
          type: string
        fax:
          description: The contacts fax number
          type: string
        name:
          description: The name of the contact
          type: string
        state:
          description: The state in which the contact is based ('US' for Federal laws and 'DC' for the District of Columbia)
          type: string
        telephone:
          description: The contacts phone number
          type: string
        title:
          description: The job title of the contact
          type: string
        web_page:
          description: The contacts webpage
          type: string
      required:
        - name
        - state
    PocResults:
      properties:
        inputs:
          $ref: "#/components/schemas/Inputs"
        metadata:
          $ref: "#/components/schemas/Metadata"
        result:
          description: The array of Points of Contacts for the state requested
          items:
            $ref: "#/components/schemas/Poc"
          type: array
      required:
        - metadata
        - inputs
        - result
