---
swagger: '2.0'
basePath: "/api/transportation-incentives-laws"
schemes:
- https
info:
  version: 0.1.0
  title: Transportation Laws and Incentives
  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.
paths:
  "/v1.{output_format}":
    get:
      responses:
        '200':
          description: Successful request
          schema:
            "$ref": "#/definitions/LawsResponse"
      description: ''
      summary: Return a full list of laws and incentives that match your query.
      operationId: transportation_incentives_laws_all
      parameters:
      - in: path
        description: Response format
        name: output_format
        required: true
        type: string
        default: json
        enum:
          - json
          - xml
          - csv
      - in: query
        description: API Key
        name: api_key
        required: true
        type: string
        default: DEMO_KEY
      - in: query
        description: Limit the number of laws returned
        name: limit
        required: false
        type: integer
        default: 10
      - in: query
        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.
        name: jurisdiction
        required: false
        type: string
      - in: query
        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.'
        name: technology
        required: false
        type: string
      - in: query
        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.'
        name: incentive_type
        required: false
        type: string
      - in: query
        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.'
        name: regulation_type
        required: false
        type: string
      - in: query
        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.'
        name: user_type
        required: false
        type: string
      - in: query
        description: Include points of contacts in the return value.
        name: poc
        required: false
        type: boolean
        default: false
      - in: query
        description: Return only recently added or updated laws and incentives
        name: recent
        required: false
        type: boolean
        default: false
      - in: query
        description: 'The ''true'' value returns only expired, repealed, or archived laws and incentives. The default ''false'' value returns only current laws and incentives.'
        name: expired
        required: false
        type: boolean
        default: false
      - in: query
        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.'
        name: law_type
        required: false
        type: string
      - in: query
        description: Search laws by keyword in title or text.
        name: keyword
        required: false
        type: string
      - in: query
        description: Show only local examples of laws and incentives.
        name: local
        required: false
        type: boolean
        default: false
  "/v1/{id}.{output_format}":
    get:
      responses:
        '200':
          description: Successful request
          schema:
            "$ref": "#/definitions/LawResult"
      description: ''
      summary: Fetch the details of a specific law given the law's ID.
      operationId: transportation_incentives_laws_id
      parameters:
      - in: path
        description: Response format
        name: output_format
        required: true
        type: string
        default: json
        enum:
          - json
          - xml
      - in: query
        description: API Key
        name: api_key
        required: true
        type: string
        default: DEMO_KEY
      - in: path
        description: The id of the law that you are searching
        name: id
        required: true
        type: integer
      - in: query
        description: Include points of contacts in the return value.
        name: poc
        required: false
        type: boolean
        default: false
      - in: query
        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.'
        name: expired
        required: false
        type: boolean
        default: false
  "/v1/pocs.{output_format}":
    get:
      responses:
        '200':
          description: Successful request
          schema:
            "$ref": "#/definitions/PocResults"
      description: ''
      summary: Get the points of contact for a given jurisdiction.
      operationId: transportation_incentives_laws_pocs
      parameters:
      - in: path
        description: Response format
        name: output_format
        required: true
        type: string
        default: json
        enum:
          - json
          - xml
      - in: query
        description: API Key
        name: api_key
        required: true
        type: string
        default: DEMO_KEY
      - in: query
        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.
        name: jurisdiction
        required: true
        type: string
  "/v1/category-list.{output_format}":
    get:
      responses:
        '200':
          description: Successful request
          schema:
            "$ref": "#/definitions/CategoryResults"
      description: ''
      summary: Return the law categories for a given category type.
      operationId: transportation_incentives_laws_categories
      parameters:
      - in: path
        description: Response format
        name: output_format
        required: true
        type: string
        default: json
        enum:
          - json
          - xml
      - in: query
        description: API Key
        name: api_key
        required: true
        type: string
        default: DEMO_KEY
      - in: query
        description: Search by the category type.
        name: type
        required: false
        type: string
        enum:
          - tech
          - user
          - regulation
          - incentive
definitions:
  Metadata:
    description: The identifying metadata.
    required:
    - version
    properties:
      version:
        type: string
        description: This is the version of the api
      count:
        type: integer
        description: If the request returns an array of results, this is the number
          of results returned in the array
  Inputs:
    description: The parameters that were passed to the API
    properties: {}
  Law:
    description: This is a Law
    required:
    - id
    - state
    - title
    - text
    - plaintext
    - type
    - categories
    - types
    - references
    - topics
    properties:
      id:
        type: integer
        description: A unique identifier for this specific incentive/law/regulation.
      state:
        type: string
        description: The state in which the incentive/law/regulation was enacted and
          is active.
      title:
        type: string
        description: The brief title assigned to the incentive/law/regulation description.
      text:
        type: string
        description: Description of the incentive/law/regulation, including applicable
          legislative references, html formated.
      enacted_date:
        type: string
        format: date-time
        description: The date the enacting legislation (if applicable) was signed
          into law.
      amended_date:
        type: string
        format: date-time
        description: The date the incentive/law/regulation was updated through new
          legislation or rulemaking.
      expired_date:
        type: string
        format: date-time
        description: The date the incentive/law/regulation is set to end.
      archived_date:
        type: string
        format: date-time
        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.
      repealed_date:
        type: string
        format: date-time
        description: The date legislation is enacted or a rulemaking is finalized
          to repeal the incentive/law/regulation.
      plaintext:
        type: string
        description: Description of the incentive/law/regulation, including applicable
          legislative references, in <a href="https://guides.github.com/features/mastering-markdown/">markdown
          formatting</a>
      is_recent:
        type: boolean
        description: The true or false value used to distinguish between recent federal
          executive actions (TRUE) and active incentives/laws/regulations (FALSE).
      seq_num:
        type: integer
        description: The numerical value assigned to a description to show the order
          in which it is displayed online within a jurisdiction (state).
      type:
        type: string
        description: 'The category that the incentive/law/regulation falls under,
          described below: -State Incentives, -Laws and Regulations, -Utility/Private
          Incentives'
      agency:
        type: string
        description: The agency with primary responsibility for federal incentives/regulations.
      significant_update_date:
        type: string
        format: date-time
        description: When the last significant update to the law was made.
      recent_update_or_new:
        type: string
        description: An indicator if the last significant update was an update or
          the laws creation.
      contacts:
        type: array
        description: The contacts for the given law, returned only if the parameter
          poc is true
        items:
          "$ref": "#/definitions/Poc"
      categories:
        type: array
        description: The various law categories that apply to this law
        items:
          "$ref": "#/definitions/Category"
      types:
        type: array
        description: The types that apply to this law
        items:
          "$ref": "#/definitions/LawType"
      references:
        type: array
        description: The URL associated with any bill or legislative reference included
          in the description.
        items:
          "$ref": "#/definitions/LawReference"
      topics:
        type: array
        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": "#/definitions/LawTopics"
      status:
        type: string
        description: The status of the law or incentive.
      status_date:
        type: string
        description: The status effective date.
  Poc:
    required:
    - name
    - state
    properties:
      title:
        type: string
        description: The job title of the contact
      name:
        type: string
        description: The name of the contact
      state:
        type: string
        description: The state in which the contact is based ('US' for Federal laws
          and 'DC' for the District of Columbia)
      agency:
        type: string
        description: The agency that the contact represents
      web_page:
        type: string
        description: The contacts webpage
      telephone:
        type: string
        description: The contacts phone number
      fax:
        type: string
        description: The contacts fax number
      email:
        type: string
        description: The contacts email address
  Category:
    description: A category that the law applies to
    required:
    - code
    - title
    - category_type
    properties:
      code:
        type: string
        description: The code used to identify the category
      title:
        type: string
        description: The full name of the category
      category_type:
        type: string
        description: The type of category. (E.g. tech, incentive, regulation, user)
  LawType:
    description: 'The category that the incentive/law/regulation falls under, described
      below: -State Incentives, -Laws and Regulations, -Utility/Private Incentives'
    required:
    - id
    - title
    - code
    properties:
      id:
        type: integer
        description: The id of the law type
      title:
        type: string
        description: The name of the law type
      code:
        type: string
        description: The code used to identify the law type
  LawReference:
    description: The URL associated with any bill or legislative reference included
      in the description.
    required:
    - description
    - url
    properties:
      description:
        type: string
        description: The context of the reference
      url:
        type: string
        description: The url linking to the reference.
  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'
    required:
    - id
    - title
    - sort_order
    properties:
      id:
        type: integer
        description: The database id of the law topic
      title:
        type: string
        description: The name of the law topic
      sort_order:
        type: integer
        description: The sort order of the law topic
  LawsResponse:
    required:
    - metadata
    - inputs
    - result
    properties:
      metadata:
        "$ref": "#/definitions/Metadata"
      inputs:
        "$ref": "#/definitions/Inputs"
      result:
        description: The array of laws returned
        type: array
        items:
          "$ref": "#/definitions/Law"
  LawResult:
    required:
    - metadata
    - inputs
    - result
    properties:
      metadata:
        "$ref": "#/definitions/Metadata"
      inputs:
        "$ref": "#/definitions/Inputs"
      result:
        "$ref": "#/definitions/Law"
  PocResults:
    required:
    - metadata
    - inputs
    - result
    properties:
      metadata:
        "$ref": "#/definitions/Metadata"
      inputs:
        "$ref": "#/definitions/Inputs"
      result:
        description: The array of Points of Contacts for the state requested
        type: array
        items:
          "$ref": "#/definitions/Poc"
  FullCategory:
    required:
    - code
    - title
    - category_type
    - sort_order
    properties:
      code:
        type: string
        description: The code used to identify the category
      title:
        type: string
        description: The full name of the category
      category_type:
        type: string
        description: The type of category. (E.g. tech, incentive, regulation, user)
      sort_order:
        type: string
        description: The sort order for the categories
      help_text:
        type: string
        description: A short description of what the law category encompasses
  CategoryResults:
    required:
    - metadata
    - inputs
    - result
    properties:
      metadata:
        "$ref": "#/definitions/Metadata"
      inputs:
        "$ref": "#/definitions/Inputs"
      result:
        description: The array of law categories returned
        type: array
        items:
          "$ref": "#/definitions/FullCategory"
