openapi: 3.0.3
info:
  title: EPA Air Quality System (AQS) Account Type Codes Allowance Holdings API
  description: 'The Air Quality System (AQS) Data Mart API provides programmatic access to ambient air

    sample data collected by state, local, tribal and federal air pollution control agencies

    from thousands of monitors across the United States. The API exposes monitor metadata,

    raw sample observations, daily/quarterly/annual aggregates, and quality assurance results.

    '
  version: '1.0'
  contact:
    name: AQS Data Mart Support
    email: aqsdatamart@epa.gov
    url: https://aqs.epa.gov/aqsweb/documents/data_api.html
  license:
    name: U.S. Government Work / Public Domain
    url: https://www.usa.gov/government-works
servers:
- url: https://aqs.epa.gov/data/api
  description: Production AQS Data Mart API
security:
- emailKey: []
tags:
- name: Allowance Holdings
paths:
  /account-mgmt/allowance-holdings:
    get:
      operationId: AllowanceHoldingsController_getAllowanceHoldings
      parameters:
      - name: accountType
        required: false
        in: query
        description: Type of allowance account (Facility, General, etc.).
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - Compliance Assurance Surrender Account
            - Enforcement Surrender Account
            - Facility Account
            - General Account
            - Overdraft Account
            - EPA Reserve Account
            - State Early Reduction Reserve Account
            - State General Reserve Account
            - State Holding Account
            - New Unit Set Aside Reserve Account
            - State Opt-In Reserve Account
            - State Other Reserve Account
            - State Primary Reserve Account
            - State Retirement Account
            - Surrender Account
            - Unit Account
            - Voluntary Surrender Account
        example:
        - Compliance Assurance Surrender Account
      - name: accountNumber
        required: false
        in: query
        description: The unique identification number of an account.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
        example:
        - string
      - name: facilityId
        required: false
        in: query
        description: The Facility ID code assigned by the Department of Energy's Energy Information Administration. The Energy Information Administration Plant ID code is also referred to as the "ORIS code", "ORISPL code", "Facility ID", or "Facility code", among other names. If a Plant ID code has not been assigned by the Department of Energy's Energy Information Administration, then plant code means a code beginning with "88" assigned by the EPA's Clean Air Markets Division for electronic reporting.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: number
        example:
        - 0.0
      - name: stateCode
        required: false
        in: query
        description: Two letter abbreviation for the State.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - AL
            - AK
            - AS
            - AZ
            - AR
            - CA
            - CO
            - CT
            - DE
            - DC
            - FM
            - FL
            - GA
            - GU
            - HI
            - ID
            - IL
            - IN
            - IA
            - KS
            - KY
            - LA
            - ME
            - MH
            - MD
            - MA
            - MI
            - MN
            - MS
            - MO
            - MT
            - NE
            - NV
            - NH
            - NJ
            - NM
            - NY
            - NC
            - ND
            - MP
            - OH
            - OK
            - OR
            - PW
            - PA
            - PR
            - RI
            - SC
            - SD
            - TN
            - TX
            - UT
            - VT
            - VI
            - VA
            - WA
            - WV
            - WI
            - WY
        example:
        - AL
      - name: vintageYear
        required: false
        in: query
        description: Year allowance becomes eligible for use in compliance.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: number
        example:
        - 2024
      - name: ownerOperator
        required: false
        in: query
        description: The name of any company that owns an allowance account or an affected unit.The name of any company that operates an affected unit.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
        example:
        - string
      - name: programCodeInfo
        required: false
        in: query
        description: Statutory or regulatory based options for tracking and reducing air pollution emissions.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - ARP
            - CSNOX
            - CSOSG1
            - CSOSG2
            - CSOSG2E
            - CSOSG3
            - CSSO2G1
            - CSSO2G2
            - TXSO2
        example:
        - ARP
      - name: page
        required: true
        in: query
        description: Page number of data being requested.
        schema:
          type: number
        example: 0.0
      - name: perPage
        required: true
        in: query
        description: Number of results per page.
        schema:
          type: number
        example: 0.0
      responses:
        '200':
          description: Retrieve Allowance Holdings per filter criteria
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AllowanceHoldingsDTO'
              examples:
                AllowanceHoldingsController_getAllowanceHoldings200Example:
                  summary: Default AllowanceHoldingsController_getAllowanceHoldings 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Example response
            text/csv:
              schema:
                type: string
                example: Account Number,Account Name,Facility ID,Program Code,Allowance Vintage Year,Allowance Block Total,Serial Number Start,Serial Number End,State,EPA Region,Owner/Operator,Account Type
              examples:
                AllowanceHoldingsController_getAllowanceHoldings200Example:
                  summary: Default AllowanceHoldingsController_getAllowanceHoldings 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Example response
        '400':
          description: Invalid Request
        '404':
          description: Resource Not Found
      security:
      - APIKey: []
      tags:
      - Allowance Holdings
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /account-mgmt/allowance-holdings/attributes/applicable:
    get:
      operationId: AllowanceHoldingsController_getAllApplicableAllowanceHoldingsAttributes
      parameters: []
      responses:
        '200':
          description: Retrieved All Applicable Allowance Holdings Attributes
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicableAllowanceHoldingsAttributesDTO'
              examples:
                AllowanceHoldingsController_getAllApplicableAllowanceHoldingsAttributes200Example:
                  summary: Default AllowanceHoldingsController_getAllApplicableAllowanceHoldingsAttributes 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Example response
        '400':
          description: Invalid Request
        '404':
          description: Resource Not Found
      security:
      - APIKey: []
      tags:
      - Allowance Holdings
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /account-mgmt/allowance-holdings/owner-operators:
    get:
      operationId: AllowanceHoldingsController_getAllOwnerOperators
      parameters: []
      responses:
        '200':
          description: Retrieved All Valid Owner Operators
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/OwnerOperatorsDTO'
              examples:
                AllowanceHoldingsController_getAllOwnerOperators200Example:
                  summary: Default AllowanceHoldingsController_getAllOwnerOperators 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Example response
        '400':
          description: Invalid Request
        '404':
          description: Resource Not Found
      security:
      - APIKey: []
      tags:
      - Allowance Holdings
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /streaming-services/allowance-holdings:
    get:
      operationId: AllowanceHoldingsController_streamAllowanceHoldings
      parameters:
      - name: accountType
        required: false
        in: query
        description: Type of allowance account (Facility, General, etc.).
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - Compliance Assurance Surrender Account
            - Enforcement Surrender Account
            - Facility Account
            - General Account
            - Overdraft Account
            - EPA Reserve Account
            - State Early Reduction Reserve Account
            - State General Reserve Account
            - State Holding Account
            - New Unit Set Aside Reserve Account
            - State Opt-In Reserve Account
            - State Other Reserve Account
            - State Primary Reserve Account
            - State Retirement Account
            - Surrender Account
            - Unit Account
            - Voluntary Surrender Account
        example:
        - Compliance Assurance Surrender Account
      - name: accountNumber
        required: false
        in: query
        description: The unique identification number of an account.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
        example:
        - string
      - name: facilityId
        required: false
        in: query
        description: The Facility ID code assigned by the Department of Energy's Energy Information Administration. The Energy Information Administration Plant ID code is also referred to as the "ORIS code", "ORISPL code", "Facility ID", or "Facility code", among other names. If a Plant ID code has not been assigned by the Department of Energy's Energy Information Administration, then plant code means a code beginning with "88" assigned by the EPA's Clean Air Markets Division for electronic reporting.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: number
        example:
        - 0.0
      - name: stateCode
        required: false
        in: query
        description: Two letter abbreviation for the State.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - AL
            - AK
            - AS
            - AZ
            - AR
            - CA
            - CO
            - CT
            - DE
            - DC
            - FM
            - FL
            - GA
            - GU
            - HI
            - ID
            - IL
            - IN
            - IA
            - KS
            - KY
            - LA
            - ME
            - MH
            - MD
            - MA
            - MI
            - MN
            - MS
            - MO
            - MT
            - NE
            - NV
            - NH
            - NJ
            - NM
            - NY
            - NC
            - ND
            - MP
            - OH
            - OK
            - OR
            - PW
            - PA
            - PR
            - RI
            - SC
            - SD
            - TN
            - TX
            - UT
            - VT
            - VI
            - VA
            - WA
            - WV
            - WI
            - WY
        example:
        - AL
      - name: vintageYear
        required: false
        in: query
        description: Year allowance becomes eligible for use in compliance.
        schema:
          type: array
          items:
            type: number
        example:
        - 2024
      - name: ownerOperator
        required: false
        in: query
        description: The name of any company that owns an allowance account or an affected unit.The name of any company that operates an affected unit.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
        example:
        - string
      - name: programCodeInfo
        required: false
        in: query
        description: Statutory or regulatory based options for tracking and reducing air pollution emissions.
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - ARP
            - CSNOX
            - CSOSG1
            - CSOSG2
            - CSOSG2E
            - CSOSG3
            - CSSO2G1
            - CSSO2G2
            - TXSO2
        example:
        - ARP
      - name: exclude
        required: false
        in: query
        description: Selected items will be excluded from the response
        style: pipeDelimited
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - epaRegion
            - facilityId
            - ownerOperator
            - stateCode
            - unit_id
        example:
        - epaRegion
      responses:
        '200':
          description: Streams Allowance Holdings per filter criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowanceHoldingsDTO'
              examples:
                AllowanceHoldingsController_streamAllowanceHoldings200Example:
                  summary: Default AllowanceHoldingsController_streamAllowanceHoldings 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Example response
            text/csv:
              schema:
                type: string
                example: Account Number,Account Name,Facility ID,Program Code,Allowance Vintage Year,Allowance Block Total,Serial Number Start,Serial Number End,State,EPA Region,Owner/Operator,Account Type
              examples:
                AllowanceHoldingsController_streamAllowanceHoldings200Example:
                  summary: Default AllowanceHoldingsController_streamAllowanceHoldings 200 response
                  x-microcks-default: true
                  value:
                    status: ok
                    message: Example response
        '400':
          description: Invalid Request
        '404':
          description: Resource Not Found
      security:
      - APIKey: []
      tags:
      - Allowance Holdings
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    OwnerOperatorsDTO:
      type: object
      properties:
        ownerOperator:
          type: string
          description: The name of any company that owns an allowance account or an affected unit.The name of any company that operates an affected unit.
          example: Alabama Power Company
        ownType:
          type: string
          description: Owner/Operator type. Either Owner, Operator, or Both.
          example: OPR
      required:
      - ownerOperator
      - ownType
    AllowanceHoldingsDTO:
      type: object
      properties:
        accountNumber:
          type: string
          description: The unique identification number of an account.
          example: 000003FACLTY
        accountName:
          type: string
          description: The name of the account in which allowances are held.
          example: Barry
        facilityId:
          type: number
          description: The Facility ID code assigned by the Department of Energy's Energy Information Administration. The Energy Information Administration Plant ID code is also referred to as the "ORIS code", "ORISPL code", "Facility ID", or "Facility code", among other names. If a Plant ID code has not been assigned by the Department of Energy's Energy Information Administration, then plant code means a code beginning with "88" assigned by the EPA's Clean Air Markets Division for electronic reporting.
          example: 3
        programCodeInfo:
          type: string
          description: Statutory or regulatory based options for tracking and reducing air pollution emissions.
          example: ARP,CSNOX,CSSO2G2,MATS
        vintageYear:
          type: number
          description: Year allowance becomes eligible for use in compliance.
          example: 2016
        totalBlock:
          type: number
          description: The quantity of allowances as identified by the Start Serial Number through End Serial Number.
          example: 10033
        startBlock:
          type: number
          description: The starting serial number of an allowance block.
          example: 266955
        endBlock:
          type: number
          description: The ending serial number of an allowance block.
          example: 276987
        stateCode:
          type: string
          description: Two letter abbreviation for the State.
          example: AK
        epaRegion:
          type: number
          description: An EPA Region is a group of U.S. states. EPA Regions are numbered from 1 to 10 and each state belongs to one and only one EPA Region.
          example: 5
        ownerOperator:
          type: string
          description: The name of any company that owns an allowance account or an affected unit.The name of any company that operates an affected unit.
          example: Alabama Power Company (Operator)|Alabama Power Company (Owner)
        accountType:
          type: string
          description: Type of allowance account (Facility, General, etc.).
          example: Facility Account
      required:
      - accountNumber
      - accountName
      - programCodeInfo
      - stateCode
      - ownerOperator
      - accountType
    ApplicableAllowanceHoldingsAttributesDTO:
      type: object
      properties:
        vintageYear:
          type: number
          description: Year allowance becomes eligible for use in compliance.
          example: 2016
        programCode:
          type: string
          description: Code for statutory or regulatory based options for tracking and reducing air pollution emissions.
          example: CAIRNOX
        accountNumber:
          type: string
          description: The unique identification number of an account.
          example: 000003FACLTY
        accountTypeCode:
          type: string
          description: Code for the type of allowance account.
          example: RESERVE
        facilityId:
          type: number
          description: The Facility ID code assigned by the Department of Energy's Energy Information Administration. The Energy Information Administration Plant ID code is also referred to as the "ORIS code", "ORISPL code", "Facility ID", or "Facility code", among other names. If a Plant ID code has not been assigned by the Department of Energy's Energy Information Administration, then plant code means a code beginning with "88" assigned by the EPA's Clean Air Markets Division for electronic reporting.
          example: 3
        stateCode:
          type: string
          description: Two letter abbreviation for the State.
          example: AK
        ownerOperator:
          type: string
          description: The name of any company that owns an allowance account or an affected unit.The name of any company that operates an affected unit.
          example: Alabama Power Company
      required:
      - vintageYear
      - programCode
      - accountNumber
      - accountTypeCode
      - stateCode
      - ownerOperator
  securitySchemes:
    emailKey:
      type: apiKey
      in: query
      name: key
      description: 'AQS requires `email` and `key` query parameters on every request. Register at

        `/signup?email=YOUR_EMAIL` to receive a key by email.

        '