openapi: 3.0.3
info:
  title: Atmospore Pollen Forecast API
  description: Global pollen forecasts with species-level accuracy. 21 individual species, 14-day forecasts, area averages with min/max, and multilingual species metadata.
  version: 1.0.0
  contact:
    name: Atmospore
    url: "https://atmospore.com"
    email: support@atmospore.com
  termsOfService: "https://atmospore.com/terms-of-service"
servers:
  - url: "https://pollenapi.com"
    description: Production
security:
  - ApiKeyAuth:[]
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key from your Atmospore account settings
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
    SpeciesData:
      type: object
      properties:
        value:
          type: number
          description: Interpolated pollen concentration
        risk_level:
          type: string
          enum:
            - low
            - moderate
            - high
            - very high
        display_name:
          type: string
          description: Human-readable species name
        category:
          type: string
          enum:
            - tree
            - grass
            - weed
    AreaSpeciesData:
      type: object
      properties:
        avg:
          type: number
        min:
          type: number
        max:
          type: number
        risk_level:
          type: string
          enum:
            - low
            - moderate
            - high
            - very high
        display_name:
          type: string
        category:
          type: string
          enum:
            - tree
            - grass
            - weed
    TopSpeciesData:
      type: object
      properties:
        species:
          type: string
        display_name:
          type: string
        category:
          type: string
          enum:
            - tree
            - grass
            - weed
        max:
          type: number
        avg:
          type: number
        risk_level:
          type: string
          enum:
            - low
            - moderate
            - high
            - very high
  parameters:
    lon:
      name: lon
      in: query
      required: true
      schema:
        type: number
      description: Longitude coordinate
    lat:
      name: lat
      in: query
      required: true
      schema:
        type: number
      description: Latitude coordinate
    dt:
      name: dt
      in: query
      required: true
      schema:
        type: string
        format: date
      description: Start date (YYYY-MM-DD)
    forecast_days:
      name: forecast_days
      in: query
      required: true
      schema:
        type: integer
        minimum: 1
        maximum: 14
      description: Number of forecast days
    species:
      name: species
      in: query
      required: false
      schema:
        type: string
      description: Comma-separated species or groups (tree, grass, weed, all). Defaults to all.
    radius:
      name: radius
      in: query
      required: false
      schema:
        type: integer
        default: 25000
        maximum: 50000
      description: Search radius in meters
paths:
  /v1/pollen:
    get:
      summary: Pollen forecast at a point
      description: Interpolated pollen forecast at a specific coordinate. Returns species-level data with risk levels and an overall daily risk score.
      operationId: getPollenForecast
      parameters:
        - $ref: "#/components/parameters/lon"
        - $ref: "#/components/parameters/lat"
        - $ref: "#/components/parameters/dt"
        - $ref: "#/components/parameters/forecast_days"
        - $ref: "#/components/parameters/species"
      responses:
        200:
          description: Forecast data
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      location:
                        type: object
                        properties:
                          lat:
                            type: number
                          lon:
                            type: number
                      units:
                        type: string
                        example: grains/m³
                      generated_at:
                        type: string
                        format: date-time
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                        overall_risk:
                          type: string
                          enum:
                            - low
                            - moderate
                            - high
                            - very high
                        species:
                          type: object
                          additionalProperties:
                            $ref: "#/components/schemas/SpeciesData"
        400:
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Missing API key
        403:
          description: Invalid API key
        429:
          description: Daily quota exceeded
  /v1/pollen-area:
    get:
      summary: Area pollen averages
      description: Average, minimum, and maximum pollen levels across a configurable radius. Ideal for regional dashboards and area-wide risk assessment.
      operationId: getPollenArea
      parameters:
        - $ref: "#/components/parameters/lon"
        - $ref: "#/components/parameters/lat"
        - $ref: "#/components/parameters/dt"
        - $ref: "#/components/parameters/forecast_days"
        - $ref: "#/components/parameters/species"
        - $ref: "#/components/parameters/radius"
      responses:
        200:
          description: Area forecast data with min/max/avg
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      location:
                        type: object
                        properties:
                          lat:
                            type: number
                          lon:
                            type: number
                      radius:
                        type: integer
                      units:
                        type: string
                      generated_at:
                        type: string
                        format: date-time
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                        overall_risk:
                          type: string
                        species:
                          type: object
                          additionalProperties:
                            $ref: "#/components/schemas/AreaSpeciesData"
        400:
          description: Invalid parameters
        429:
          description: Daily quota exceeded
  /v1/pollen-top:
    get:
      summary: Top pollen species
      description: Top contributing species in a date range, ranked by severity. Returns max and average values aggregated across the period.
      operationId: getPollenTop
      parameters:
        - $ref: "#/components/parameters/lon"
        - $ref: "#/components/parameters/lat"
        - $ref: "#/components/parameters/dt"
        - $ref: "#/components/parameters/forecast_days"
      responses:
        200:
          description: Top species ranked by severity
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      location:
                        type: object
                        properties:
                          lat:
                            type: number
                          lon:
                            type: number
                      units:
                        type: string
                      date_range:
                        type: array
                        items:
                          type: string
                          format: date
                      generated_at:
                        type: string
                        format: date-time
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/TopSpeciesData"
        400:
          description: Invalid parameters
        429:
          description: Daily quota exceeded
  /v1/species:
    get:
      summary: Species metadata
      description: All supported pollen species with display names in multiple languages, categories, and risk thresholds. No authentication required. Cache this response client-side.
      operationId: getSpecies
      security:[]
      responses:
        200:
          description: Species metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      total_species:
                        type: integer
                      categories:
                        type: array
                        items:
                          type: string
                      risk_levels:
                        type: array
                        items:
                          type: string
                      units:
                        type: string
                  data:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        display_name:
                          type: string
                        category:
                          type: string
                        names:
                          type: object
                          additionalProperties:
                            type: string
                        risk_thresholds:
                          type: array
                          items:
                            type: number