openapi: 3.1.0
info:
  title: EPA Envirofacts Data Service API
  version: "1.0.0"
  description: >-
    Public REST data service from the U.S. Environmental Protection Agency.
    Provides programmatic access to Envirofacts tables (environmental records
    across air, water, land) and to the UV Index forecast (hourly and daily)
    via simple, dynamic path-based queries. No authentication is required.
    Best-effort spec derived from publicly documented surfaces; not
    exhaustive.
  contact:
    name: EPA Envirofacts
    url: https://www.epa.gov/enviro/envirofacts-data-service-api
  license:
    name: U.S. Public Domain
servers:
  - url: https://data.epa.gov
    description: EPA data services production base URL
tags:
  - name: Envirofacts
  - name: UVIndex
paths:
  /efservice/{table}/{format}:
    get:
      tags: [Envirofacts]
      summary: Query an Envirofacts table
      operationId: queryEnvirofactsTable
      description: >-
        Retrieve rows from an Envirofacts table. The dynamic path supports
        filters (e.g. `state_code/equals/CT`), table joins, pagination
        (`<first>:<last>`), and sort directives.
      parameters:
        - in: path
          name: table
          required: true
          description: Envirofacts schema.table name (e.g. `sems.envirofacts_site`).
          schema:
            type: string
            example: sems.envirofacts_site
        - in: path
          name: format
          required: true
          description: Output format.
          schema:
            type: string
            enum: [JSON, CSV, EXCEL, XML, HTML, JSONP, PARQUET, PDF]
      responses:
        "200":
          description: Matching rows
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /efservice/{table}/{column}/{operator}/{value}/{format}:
    get:
      tags: [Envirofacts]
      summary: Query an Envirofacts table with a column filter
      operationId: queryEnvirofactsFiltered
      parameters:
        - in: path
          name: table
          required: true
          schema:
            type: string
        - in: path
          name: column
          required: true
          schema:
            type: string
        - in: path
          name: operator
          required: true
          schema:
            type: string
            enum: [equals, beginning, containing, "<", "<=", ">", ">=", "!="]
        - in: path
          name: value
          required: true
          schema:
            type: string
        - in: path
          name: format
          required: true
          schema:
            type: string
            enum: [JSON, CSV, EXCEL, XML, HTML, JSONP, PARQUET, PDF]
      responses:
        "200":
          description: Matching rows
  /dmapservice/getEnvirofactsUVHOURLY/ZIP/{zip}/{format}:
    get:
      tags: [UVIndex]
      summary: Hourly UV index forecast for a ZIP code
      operationId: getUvHourlyByZip
      parameters:
        - in: path
          name: zip
          required: true
          schema:
            type: string
            example: "20002"
        - in: path
          name: format
          required: true
          schema:
            type: string
            enum: [JSON, XML, CSV]
      responses:
        "200":
          description: Hourly UV index forecast
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UvHourly"
  /dmapservice/getEnvirofactsUVHOURLY/CITY/{city}/STATE/{state}/{format}:
    get:
      tags: [UVIndex]
      summary: Hourly UV index forecast for a city and state
      operationId: getUvHourlyByCityState
      parameters:
        - in: path
          name: city
          required: true
          schema:
            type: string
        - in: path
          name: state
          required: true
          description: Two-letter state code (e.g. `CT`).
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - in: path
          name: format
          required: true
          schema:
            type: string
            enum: [JSON, XML, CSV]
      responses:
        "200":
          description: Hourly UV index forecast
  /dmapservice/getEnvirofactsUVDAILY/ZIP/{zip}/{format}:
    get:
      tags: [UVIndex]
      summary: Daily UV index forecast for a ZIP code
      operationId: getUvDailyByZip
      parameters:
        - in: path
          name: zip
          required: true
          schema:
            type: string
        - in: path
          name: format
          required: true
          schema:
            type: string
            enum: [JSON, XML, CSV]
      responses:
        "200":
          description: Daily UV index forecast
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UvDaily"
  /dmapservice/getEnvirofactsUVDAILY/CITY/{city}/STATE/{state}/{format}:
    get:
      tags: [UVIndex]
      summary: Daily UV index forecast for a city and state
      operationId: getUvDailyByCityState
      parameters:
        - in: path
          name: city
          required: true
          schema:
            type: string
        - in: path
          name: state
          required: true
          schema:
            type: string
        - in: path
          name: format
          required: true
          schema:
            type: string
            enum: [JSON, XML, CSV]
      responses:
        "200":
          description: Daily UV index forecast
components:
  schemas:
    UvHourly:
      type: object
      properties:
        ORDER:
          type: integer
        ZIP:
          type: string
        DATE_TIME:
          type: string
        UV_VALUE:
          type: integer
    UvDaily:
      type: object
      properties:
        CITY:
          type: string
        STATE:
          type: string
        DATE:
          type: string
        UV_INDEX:
          type: integer
        UV_ALERT:
          type: integer