---
openapi: 3.0.3
info:
  title: Pollen Forecast - A Weather Source API
  description: "Pollen forecast data for latitude/longitude points. Hourly forecast is up to 48 hours.\n\n  **IMPORTANT:** To authenticate to the Weather Source Forecast API, each request must contain your API key set to a custom header named `X-API-KEY`. If you do not have a Weather Source API key [sign up for a free 30-day developer account](https://developer.weathersourceapis.com/account/sign-up/). You may use the evaluation API Key `C0W60UOFRML47ytbXk4xlLBfv` to access example locations found in this documentation.\n  \n  When using the \\\"Try it out\\\" capability in the documentation, the API key should be added by clicking the green \\\"Authorize\\\" button at the top of the page.\n"
  termsOfService: https://weathersource.com/company/legal/terms-of-service/
  contact:
    name: Weather Source APIs
    url: https://developer.weathersourceapis.com/
    email: support@weathersource.com
  version: 2.0.0
servers:
- url: https://pollenforecast.weathersourceapis.com/v2
security:
- ApiKeyAuth: []
tags:
- name: points
  description: Latitude/Longitude pollen forecast data
paths:
  /points/{latitude},{longitude}:
    get:
      tags:
      - points
      summary: The complete hourly pollen forecast for a Latitude/Longitude point.
      description: |
        Returns the complete set of pollen forecast data for a Latitude/Longitude point.

        **IMPORTANT:** To authenticate to the Weather Source Forecast API, each request must contain your API key set to a custom header named `X-API-KEY`. If you do not have a Weather Source API key [sign up for a free 30-day developer account](https://developer.weathersourceapis.com/account/sign-up/). You may use the evaluation API Key `C0W60UOFRML47ytbXk4xlLBfv` to access example locations found in this documentation.

        When using the \"Try it out\" capability in the documentation, the API key should be added by clicking the green \"Authorize\" button at the top of the page.
      parameters:
      - name: latitude
        in: path
        description: A latitude value between -90° and 90°.
        required: true
        schema:
          maximum: 90
          minimum: -90
          type: number
          format: float
          example: 38.8552
      - name: longitude
        in: path
        description: A longitude value between -180° (West) and 180° (East).
        required: true
        schema:
          maximum: 180
          minimum: -180
          type: number
          format: float
          example: -77.0513
      - name: fields
        in: query
        description: |
          A comma separated list of field names to return. The timestamp field is always returned.

          **Limiting the query to needed fields will improve the query response time.**

          In addition to individual field names, following convenience field groups are supported:
          * all *(all fields)*
        required: true
        style: form
        explode: false
        schema:
          type: array
          example: all
          items:
            type: string
            enum:
            - timestamp
            - count
            - risk
            - species
      responses:
        "200":
          description: Hourly pollen forecast response for a Latitude/Longitude point.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pollenForecastPointHourObj'
        default:
          description: Unexpected error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorObj'
components:
  schemas:
    fieldListHourObj:
      title: fieldListObj
      required:
      - fields
      type: object
      properties:
        fields:
          $ref: '#/components/schemas/fields'
      description: A list of returned field names the associated units.
      example:
        fields:
          timestamp: 'Timestamp as string: RFC 3339'
          count: Count of each type of pollen in pollen particles per meters cubed
          risk: Risk for each type of pollen, values can be low, moderate, high, or very high
          species: Species provides count for subspecies for pollen.
    pollenForecastHourArr:
      type: array
      description: An array of hourly pollen forecast objects.
      items:
        $ref: '#/components/schemas/pollenForecastHourObj'
    pollenForecastHourObj:
      required:
      - timestamp
      type: object
      properties:
        timestamp:
          $ref: '#/components/schemas/timestamp'
        count:
          $ref: '#/components/schemas/count'
        risk:
          $ref: '#/components/schemas/risk'
        species:
          $ref: '#/components/schemas/species'
      description: An hourly pollen forecast object.
    pollenForecastPointHourObj:
      required:
      - fieldList
      - location
      - pollenforecast
      type: object
      properties:
        location:
          $ref: '#/components/schemas/pointObj'
        fieldList:
          $ref: '#/components/schemas/fieldListHourObj'
        pollenforecast:
          $ref: '#/components/schemas/pollenForecastHourArr'
      description: Hourly Latitude/Longitude pollen forecast object
    count:
      type: object
      properties:
        grassPollen:
          $ref: '#/components/schemas/grassPollenNum'
        treePollen:
          $ref: '#/components/schemas/treePollenNum'
        weedPollen:
          $ref: '#/components/schemas/weedPollenNum'
      description: Count of each type of pollen in pollen particles per meters cubed.
      format: uint32
    risk:
      type: object
      properties:
        grassPollen:
          $ref: '#/components/schemas/grassPollenString'
        treePollen:
          $ref: '#/components/schemas/treePollenString'
        weedPollen:
          $ref: '#/components/schemas/weedPollenString'
      description: Risk for each type of pollen, values can be low, moderate, high, or very high.
      format: string
    species:
      type: object
      properties:
        grass:
          $ref: '#/components/schemas/grass'
        tree:
          $ref: '#/components/schemas/tree'
        weed:
          $ref: '#/components/schemas/weed'
        others:
          $ref: '#/components/schemas/others'
      description: Species provides count for subspecies for pollen.
      format: map
    grassPollenNum:
      type: number
      description: Count of grass pollen
      format: uint32
      example: 9
    treePollenNum:
      type: number
      description: Count of tree pollen
      format: uint32
      example: 12
    weedPollenNum:
      type: number
      description: Count of weed pollen
      format: uint32
      example: 7
    grassPollenString:
      type: string
      description: Risk of grass pollen
      format: string
      example: Low
    treePollenString:
      type: string
      description: Risk of tree pollen
      format: string
      example: High
    weedPollenString:
      type: string
      description: Risk of weed pollen
      format: string
      example: Very High
    grass:
      type: object
      description: Map of different grass species
      format: number
      example:
        Grass / Poaceae: 0
    tree:
      type: object
      description: Map of different tree species
      format: number
      example:
        Ash: 1
    weed:
      type: object
      description: Map of different weed species
      format: number
      example:
        Ragweed: 7
    others:
      type: object
      description: Map of different other species
      format: number
      example:
        Other pollen type: 0
    errorObj:
      type: object
      properties:
        errorCode:
          maximum: 600
          minimum: 100
          type: integer
          example: 404
        errorMessage:
          type: string
          example: NOT FOUND. Item not found.
    fields:
      type: object
      additionalProperties:
        type: string
        description: Unit value for field identified in the related key.
        example: Fahrenheit
    timestamp:
      type: string
      description: A timestamp formatted as an RFC3339 date-time value.
      format: date-time
      example: 2019-12-20T23:00:00-05:00
    pointObj:
      required:
      - boundingPoints
      - elevation
      - grid
      - latitude
      - longitude
      - timezone
      type: object
      properties:
        latitude:
          $ref: '#/components/schemas/latitude'
        longitude:
          $ref: '#/components/schemas/longitude'
        timezone:
          $ref: '#/components/schemas/timezone'
        countryCode:
          $ref: '#/components/schemas/countryCode'
        countryName:
          $ref: '#/components/schemas/countryName'
        subdivCode:
          $ref: '#/components/schemas/subdivCode'
        subdivName:
          $ref: '#/components/schemas/subdivName'
        boundingPoints:
          $ref: '#/components/schemas/boundingPoints'
        grid:
          $ref: '#/components/schemas/grid'
        elevation:
          $ref: '#/components/schemas/elevation'
      description: Metadata object for a postcode
    latitude:
      maximum: 90
      minimum: -90
      type: number
      description: A latitude value between -90° and 90°.
      format: float
      example: 38.8552
    longitude:
      maximum: 180
      minimum: -180
      type: number
      description: A longitude value between -180° (West) and 180° (East).
      format: float
      example: -77.0513
    timezone:
      type: string
      description: An Olson timezone ID.
      example: America/New_York
    countryCode:
      type: string
      description: An [ISO 3166-1 Alpha-2 country code](https://developer.weathersourceapis.com/apis/countries-with-postal-code-support/).
      example: US
    countryName:
      type: string
      description: A common country name.
      example: United States of America
    subdivCode:
      type: string
      description: An ISO 3166-2 country subdivision code.
      example: US-VA
    subdivName:
      type: string
      description: A common country subdivision name.
      example: Virginia
    boundingPoints:
      type: array
      description: A list of OnPoint™ points related to the location
      items:
        $ref: '#/components/schemas/boundingPoints_inner'
    onpointId:
      type: integer
      description: An OnPoint™ ID.
      example: 10725864
    grid:
      type: string
      description: The OnPoint™ grid on which the resource exists.
      example: NORTH_AMERICA_GRID
      enum:
      - GLOBAL_GRID
      - NORTH_AMERICA_GRID
    distance:
      type: number
      description: A distance from the provided point in miles.
      format: float
      example: 2.6772
    elevation:
      type: number
      description: The elevation above sea level of a location in meters
      format: float
      example: 173.5
    boundingPoints_inner:
      required:
      - distance
      - elevation
      - grid
      - latitude
      - longitude
      - onpointId
      type: object
      properties:
        onpointId:
          $ref: '#/components/schemas/onpointId'
        latitude:
          $ref: '#/components/schemas/latitude'
        longitude:
          $ref: '#/components/schemas/longitude'
        grid:
          $ref: '#/components/schemas/grid'
        distance:
          $ref: '#/components/schemas/distance'
        elevation:
          $ref: '#/components/schemas/elevation'
  responses:
    errorResponse:
      description: Unexpected error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorObj'
  parameters:
    fieldsHour:
      name: fields
      in: query
      description: |
        A comma separated list of field names to return. The timestamp field is always returned.

        **Limiting the query to needed fields will improve the query response time.**

        In addition to individual field names, following convenience field groups are supported:
        * all *(all fields)*
      required: true
      style: form
      explode: false
      schema:
        type: array
        example: all
        items:
          type: string
          enum:
          - timestamp
          - count
          - risk
          - species
    latitude:
      name: latitude
      in: path
      description: A latitude value between -90° and 90°.
      required: true
      schema:
        maximum: 90
        minimum: -90
        type: number
        format: float
        example: 38.8552
    longitude:
      name: longitude
      in: path
      description: A longitude value between -180° (West) and 180° (East).
      required: true
      schema:
        maximum: 180
        minimum: -180
        type: number
        format: float
        example: -77.0513
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: |
        API key to authorize requests. If you do not have a Weather Source API key [sign up for a free 30-day developer account](https://developer.weathersourceapis.com/account/sign-up/). You may use the evaluation API Key `C0W60UOFRML47ytbXk4xlLBfv` to access example locations found in this documentation.
      name: X-API-KEY
      in: header