openapi: 3.0.0
info:
  version: 1.4.0
  title: Pirate Weather API
  termsOfService: https://pirate-weather.apiable.io/terms
  contact:
    email: mail@pirateweather.net
  license:
    name: Apache License 2.0
    url: https://github.com/alexander0042/pirateweather/blob/main/LICENSE
externalDocs:
  description: Full API reference
  url: https://pirate-weather.apiable.io/full-api-reference
tags:
  - name: Weather
    description: Pirate Weather provides an open, free, and documented source of goverment weather data.
      
paths:
  "/forecast/{api_key}/{lat_and_long_or_time}":
    get:
      tags:
        - Weather
      operationId: Weather
      summary: Make a request to Pirate Weather
      description: Fetch a weather forecast or get historical weather data based of input latitude and longitude
      parameters:
        - name: api_key
          in: path
          description: Pirate Weather Authentication Token
          required: true
          schema:
            type: string
        - name: lat_and_long_or_time
          in: path
          description: A single comma delimited string containing Latitude and Longitude information. Optionally, either a UNIX timestamp, ISO 8601 date string, or number of seconds before present can be added.
          required: true
          schema:
            type: string
        - name: exclude
          in: query
          description: Exclude some keys from the Pirate Weather forecast response
          schema:
            type: string
        - name: extend
          in: query
          description: Fetch the next 168 hours (7 days) worth of hourly data, instead of
            the next 24.
          schema:
            type: string
        - name: lang
          in: query
          description: Not presently implemented. Change the forecast language.
          schema:
            type: string
        - name: units
          in: query
          description: Return the weather forecast data in the requested unit system.
          schema:
            type: string
      responses:
        "200":
          description: success
          content:
            "*/*":
              schema:
                properties:
                  latitude:
                    $ref: "#/components/schemas/latitude"
                  longitude:
                    $ref: "#/components/schemas/longitude"
                  timezone:
                    $ref: "#/components/schemas/timezone"
                  offset:
                    $ref: "#/components/schemas/offset"
                  elevation:
                    $ref: "#/components/schemas/elevation"
                  currently:
                    $ref: "#/components/schemas/currently"
                  minutely:
                    $ref: "#/components/schemas/minutely"
                  hourly:
                    $ref: "#/components/schemas/hourly"
                  daily:
                    $ref: "#/components/schemas/daily"
                  alerts:
                    $ref: "#/components/schemas/alerts"
                  flags:
                    $ref: "#/components/schemas/flags"
servers:
  - url: https://api.pirateweather.net
    description: Production forecast data server
  - url: https://dev.pirateweather.net
    description: Development forecast data server
  - url: https://timemachine.pirateweather.net
    description: Production historic data server    
components:
  schemas:
    latitude:
      type: number
      description: The requested latitude
      example: 37.3034933
    longitude:
      type: number
      description: The requested longitude.
      example: -89.5230357
    timezone:
      type: string
      description: The forecast timezone.
      example: America/Chicago
    offset:
      type: integer
      format: int32
      description: The offset (in hours) of the timezone.
      example: -6
    elevation:
      type: integer
      format: int32
      description: The elevation (in meters) of the forecast point.
      example: 344
    currently:
      type: object
      properties:
        time:
          type: integer
          format: int32
          example: 1677876000
        summary:
          type: string
          example: Windy
        icon:
          type: string
          example: wind
        nearestStormDistance:
          type: integer
          format: int32
          example: 0
        nearestStormBearing:
          type: integer
          format: int32
          example: 0
        precipIntensity:
          type: integer
          format: int32
          example: 0
        precipProbability:
          type: integer
          format: int32
          example: 0
        precipIntensityError:
          type: integer
          format: int32
          example: 0
        precipType:
          type: string
          example: none
        temperature:
          type: number
          example: 44.44
        apparentTemperature:
          type: number
          example: 35.74
        dewPoint:
          type: number
          example: 39.61
        humidity:
          type: number
          example: 0.83
        pressure:
          type: number
          example: 981.5
        windSpeed:
          type: number
          example: 22.57
        windGust:
          type: number
          example: 43.56
        windBearing:
          type: number
          example: 293.71
        cloudCover:
          type: integer
          format: int32
          example: 1
        uvIndex:
          type: number
          example: 1.9
        visibility:
          type: integer
          format: int32
          example: 10
        ozone:
          type: number
          example: 324.42
    minutely:
      type: object
      properties:
        summary:
          type: string
          example: Clear
        icon:
          type: string
          example: clear
        data:
          type: array
          items:
            type: object
            properties:
              time:
                type: integer
                format: int32
                example: 1677876000
              precipIntensity:
                type: integer
                format: int32
                example: 0
              precipProbability:
                type: number
                example: 0.4
              precipIntensityError:
                type: number
                example: 0.0299
              precipType:
                type: string
                example: none
    hourly:
      type: object
      properties:
        summary:
          type: string
          example: Clear
        icon:
          type: string
          example: clear-night
        data:
          type: array
          items:
            type: object
            properties:
              time:
                type: integer
                format: int32
                example: 1677873600
              icon:
                type: string
                example: rain
              summary:
                type: string
                example: Rain
              precipIntensity:
                type: number
                example: 0.0501
              precipProbability:
                type: number
                example: 0.55
              precipIntensityError:
                type: number
                example: 0.0294
              precipAccumulation:
                type: number
                example: 0.0501
              precipType:
                type: string
                example: rain
              temperature:
                type: number
                example: 44.11
              apparentTemperature:
                type: number
                example: 35.18
              dewPoint:
                type: number
                example: 39.72
              humidity:
                type: number
                example: 0.85
              pressure:
                type: number
                example: 978.1
              windSpeed:
                type: number
                example: 23.17
              windGust:
                type: number
                example: 45.1
              windBearing:
                type: number
                example: 295.33
              cloudCover:
                type: integer
                format: int32
                example: 1
              uvIndex:
                type: number
                example: 1.17
              visibility:
                type: integer
                format: int32
                example: 10
              ozone:
                type: number
                example: 352.77
    daily:
      type: object
      properties:
        summary:
          type: string
          example: Cloudy
        icon:
          type: string
          example: cloudy
        data:
          type: array
          items:
            type: object
            properties:
              time:
                type: integer
                format: int32
                example: 1677823200
              icon:
                type: string
                example: rain
              summary:
                type: string
                example: Rain
              sunriseTime:
                type: integer
                format: int32
                example: 1677846414
              sunsetTime:
                type: integer
                format: int32
                example: 1677887618
              moonPhase:
                type: number
                example: 0.379107617800008
              precipIntensity:
                type: number
                example: 0.0097
              precipIntensityMax:
                type: number
                example: 0.0501
              precipIntensityMaxTime:
                type: integer
                format: int32
                example: 1677873600
              precipProbability:
                type: number
                example: 0.55
              precipAccumulation:
                type: number
                example: 0.087
              precipType:
                type: string
                example: rain
              temperatureHigh:
                type: number
                example: 44.44
              temperatureHighTime:
                type: integer
                format: int32
                example: 1677880800
              temperatureLow:
                type: number
                example: 35.56
              temperatureLowTime:
                type: integer
                format: int32
                example: 1677924000
              apparentTemperatureHigh:
                type: number
                example: 38.36
              apparentTemperatureHighTime:
                type: integer
                format: int32
                example: 1677880800
              apparentTemperatureLow:
                type: number
                example: 35.18
              apparentTemperatureLowTime:
                type: integer
                format: int32
                example: 1677920400
              dewPoint:
                type: number
                example: 39.71
              humidity:
                type: number
                example: 0.862
              pressure:
                type: number
                example: 988.48
              windSpeed:
                type: number
                example: 12.87
              windGust:
                type: number
                example: 29.62
              windGustTime:
                type: integer
                format: int32
                example: 1677873600
              windBearing:
                type: number
                example: 304.92
              cloudCover:
                type: number
                example: 0.496
              uvIndex:
                type: number
                example: 1.9
              uvIndexTime:
                type: integer
                format: int32
                example: 1677877200
              visibility:
                type: number
                example: 9.93
              temperatureMin:
                type: number
                example: 40.62
              temperatureMinTime:
                type: integer
                format: int32
                example: 1677902400
              temperatureMax:
                type: number
                example: 44.44
              temperatureMaxTime:
                type: integer
                format: int32
                example: 1677880800
              apparentTemperatureMin:
                type: number
                example: 35.18
              apparentTemperatureMinTime:
                type: integer
                format: int32
                example: 1677902400
              apparentTemperatureMax:
                type: number
                example: 38.36
              apparentTemperatureMaxTime:
                type: integer
                format: int32
                example: 1677902400
    alerts:
      type: array
      items:
        type: object
        properties:
          title:
            type: string
            example: Wind Advisory issued March 3 at 12:55PM CST until March 3 at
              9:00PM CST by NWS Paducah KY
          regions:
            type: array
            items:
              type: string
              example: Jefferson
          severity:
            type: string
            example: Moderate
          time:
            type: integer
            format: int32
            example: 1677869700
          expires:
            type: integer
            format: int32
            example: 1677898800
          description:
            type: string
            example: "* WHAT...Northwest winds 20 to 30 mph with gusts up to 50 mph.  * WHERE...Portions of southern Illinois western Kentucky and southeast Missouri.  * WHEN...Until 9 PM CST this evening.  * IMPACTS...Gusty winds could blow around unsecured objects. Tree limbs could be blown down and a few power outages may result."
          uri:
            type: string
            example: https://alerts-v2.weather.gov/#/?id=urn%3Aoid%3A2.49.0.1.840.0.cee08d1b3c36dda1525fc273a7c5fd63d52dc895.002.1
    flags:
      type: object
      properties:
        sources:
          type: array
          items:
            type: string
            example: ETOPO1
        sourceTimes:
          type: object
          properties:
            hrrr_0-18:
              type: string
              example: 2023-03-03 18:00:00
            hrrr_subh:
              type: string
              example: 2023-03-03 18:00:00
            hrrr_18-48:
              type: string
              example: 2023-03-03 18:00:00
            gfs:
              type: string
              example: 2023-03-03 12:00:00
            gefs:
              type: string
              example: 2023-03-03 12:00:00
        nearest-station:
          type: integer
          format: int32
          example: 0
        units:
          type: string
          example: us
        version:
          type: string
          example: V1.4