
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
    timezone:
      name: timezone
      in: query
      required: false
      schema:
        type: string
        default: UTC
        example: auto
      description: "Clock for the `hourly` arrays (only used with resolution=hourly). Default `UTC`: index 0 is 00:00 UTC on that date. An IANA name (e.g. `America/New_York`) or `auto` (the location's own zone) makes each date's array that date's local hours, from local midnight: 24 values, or 23 / 25 on the days the clocks change. `meta.hourly_timezone` names the zone used."
    resolution:
      name: resolution
      in: query
      required: false
      schema:
        type: string
        enum:
          - daily
          - hourly
        default: daily
      description: "Response resolution. 'hourly' requires a paid plan (otherwise 403). It adds an `hourly` array to each species: hourly mean concentrations (in UTC unless `timezone` is set), which AVERAGE to the daily `value` rather than summing to it. A day is a UTC day, so both the level and the diurnal shape are interpolated between neighbouring days (centred on 12:00 UTC) instead of stepping at 00:00 UTC, while each day's 24 values still average to its daily value exactly; first and last day of a response, and days with a missing neighbour, stay flat on that side. Where the stored diurnal shape is unavailable the hours follow the species climatology."
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/resolution"
        - $ref: "#/components/parameters/timezone"
        - $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/map-tiles:
    get:
      summary: Signed map tiles (paid plans)
      description: "Returns TileJSON for global pollen vector tiles (Mapbox Vector Tile, layer `pollen`, zoom 0–5; overzoom above 5). Each feature is a grid cell (0.25° at zoom 3–5; combined into 2°/1°/0.5° cells holding the highest value at zoom 0–2) with one attribute per species holding a level from 1 to 16: 1–4 Low, 5–8 Moderate, 9–12 High, 13–16 Very High (the same risk bands as `risk_level`, each split into four steps), so one colour scale fits every species. A missing attribute means 0 (no pollen). Tiles are for display; for values in grains/m³ use /v1/pollen. Tiles that would be all ocean return 404. Tile URLs are signed and expire after 6–7 hours (`expires`), so call this from your backend and pass the response to your map client (MapLibre, Mapbox GL, OpenLayers, deck.gl MVTLayer); your API key is never exposed. Tile requests do not count against your quota; each call to this endpoint counts once. Included in paid plans. Guide with a working example: https://atmospore.com/article/map-tiles"
      operationId: getMapTiles
      parameters:
        - name: step
          in: query
          required: false
          schema:
            type: string
            example: 2026-11-04
          description: Forecast day (YYYY-MM-DD) or hour (YYYY-MM-DDTHH, UTC) for the top-level `tiles` URL. Defaults to today. All days are listed in `steps`, all hours in `hourly_steps`.
        - name: resolution
          in: query
          required: false
          schema:
            type: string
            enum:
              - daily
              - hourly
            default: daily
          description: "`hourly` adds `hourly_steps`: one entry per UTC hour of the forecast. `steps` always lists days only."
      responses:
        200:
          description: TileJSON 3.0.0 with signed tile URLs
          content:
            application/json:
              schema:
                type: object
                properties:
                  tilejson:
                    type: string
                    example: 3.0.0
                  tiles:
                    type: array
                    items:
                      type: string
                    description: Signed URL template for `step`
                  minzoom:
                    type: integer
                    example: 0
                  maxzoom:
                    type: integer
                    example: 5
                  bounds:
                    type: array
                    items:
                      type: number
                  vector_layers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: pollen
                        fields:
                          type: object
                          additionalProperties:
                            type: string
                          description: Species keys, e.g. birch, grass_tot
                  encoding:
                    type: string
                    enum:
                      - level
                    description: What the attributes hold
                  levels:
                    type: object
                    description: The risk band of each level range
                    example:
                      min: 0
                      max: 16
                      none: 0
                      bands:
                        - risk: low
                          from: 1
                          to: 4
                        - risk: moderate
                          from: 5
                          to: 8
                        - risk: high
                          from: 9
                          to: 12
                        - risk: very_high
                          from: 13
                          to: 16
                  run:
                    type: string
                    description: Forecast run id
                  generated_at:
                    type: string
                    format: date-time
                    description: When the tiles for this run were built
                  step:
                    type: string
                    description: "The step `tiles` points at: YYYY-MM-DD, or YYYY-MM-DDTHH (UTC) for an hour"
                  steps:
                    type: array
                    items:
                      type: object
                      properties:
                        step:
                          type: string
                          format: date
                        tiles:
                          type: array
                          items:
                            type: string
                  hourly_steps:
                    type: array
                    description: "Only with resolution=hourly: every forecast hour (step YYYY-MM-DDTHH, UTC) with its own tile URL"
                    items:
                      type: object
                      properties:
                        step:
                          type: string
                          example: 2026-11-04T14
                        time:
                          type: string
                          format: date-time
                          example: "2026-11-04T14:00:00Z"
                          description: "Start of the hour (UTC); format it in the viewer's time zone for labels"
                        tiles:
                          type: array
                          items:
                            type: string
                  expires:
                    type: string
                    format: date-time
                    description: Tile URLs stop working after this time; call again before then
        401:
          description: Missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Invalid key, or plan without map tiles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Unknown step
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        429:
          description: Daily quota exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /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