Skip to content

API Docs

This page serves as the documentation for the Pirate Weather API call and response format. Since this service is designed to be a drop in replacement for the Dark Sky API, the goal is to match that as closely as possible, and any disagreement between their service and Pirate Weather will be treated as a bug. However, as Pirate Weather continues to evolve, I plan on adding small, non-breaking additions where I can, and they will be documented here! Plus, always better to have my own (open source and editable) version of the docs!

Request

The minimum structure for every request to this service is the same: 

https://api.pirateweather.net/forecast/[apikey]/[latitude],[longitude]
This specifies the service (either api, dev or timemachine), root url (pirateweather.net/forecast), the api key used in the request ([apikey]), and the location ([latitude],[longitude]). There are many other ways to customize this request, but this is the minimum requirement! Calling the API with this request will return a JSON data structure (described below) with the requested weather information! All request attributes are contained within the URL. Request headers are not parsed by the API, and returned headers only contain debugging information, with all the data contained in the JSON payload.

Request Parameters

The forecast request can be extended in several ways by adding parameters to the URL. The full set of URL options is: 

https://api.pirateweather.net/forecast/[apikey]/[latitude],[longitude],[time]?exclude=[excluded]&units=[unit]&extend=[hourly]&version=[2]&lang=[lang]&extraVars=[stationPressure]&include=[day_night_forecast]

API Key

The API key needs to be requested from https://pirateweather.net/. After signing up for the service, the forecast API needs to be subscribed to, by logging in and clicking subscribe. Once subscribed to the API, it can take up to 20 minutes for the change to propagate to the gateway to allow requests, so go grab a coffee and it should be ready shortly after. As a reminder, this key is secret, and unique to each user. Keep it secret, and do not have it hard-coded into an application's source, and definitely don't commit it to a git repo!

Alternatively, you can also add the API key to the request headers by using the apikey header. You will still need to add a dummy API key to the URL so it would look like the following:

https://api.pirateweather.net/forecast/{anythingAtAll}/{lat},{lon}

Location

The location is specified by a latitude (1st) and longitude (2nd) in decimal degrees (ex. 45.42,-75.69). An unlimited number of decimal places are allowed; however, the API only returns data to the closest 13 km model square, so there's no benefit after 3 digits. While the recommended way to format this field is with positive (North/East) and negative (South/West) degrees, results should be valid when submitting longitudes from 0 to 360, instead of -180 to 180.

If you are looking for a place to figure out the latitude and longitude, https://www.latlong.net/ is a good starting point.

Time

The time field is optional for the forecast request, but mandatory for a historic request. If present, time can be specified in one of three different ways:

  1. UNIX timestamp, or the number of seconds since midnight GMT on 1 Jan 1970 (this is the preferred way).
  2. A datestring in the local time zone of the location being requested: [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS].
  3. A datestring in UTC time: [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z
  4. A time delta (in seconds) from the current time (ex. to get results for the previous day): -86400.

It's worth noting that Dark Sky also allows strings with a specified time zone (ex. +[HH][MM]). Right now this isn't supported, but if it's important for a workflow I can try to get it working. If the time variable is not included, then the current time is used for the request. If a time variable is included, the request is treated as if it was requested at that time. This means that the API will return the forecast data that would have been returned then- so not quite observations, but the last forecast for that date. Results are always returned in UTC time using UNIX timestamps, and internally UNIX time is used for everything, with the exception of calculating where to begin and end the daily data. Also, for checking time format conversions, I found https://www.silisoftware.com/tools/date.php to be an invaluable resource.

Also worth noting that times far in the future are not supported and will return an error. Specifically, times within 1 hour of the present time will be rounded to present to account for small timing issues, with anything beyond that returning a 400 error.

Units

Specifies the requested unit for the weather conditions. Options are

  • ca: SI, with Wind Speed and Wind Gust in kilometres per hour.
  • uk: SI, with Wind Speed and Wind Gust in miles per hour and visibility are in miles.
  • us: Imperial units
  • si: SI units

For compatibility with Dark Sky, us (Imperial units) are the default if nothing is specified.

Units si ca uk us
summary Temperatures in degrees Celsius or accumulation in centimetres Temperatures in degrees Celsius or accumulation in centimetres Temperatures in degrees Celsius or accumulation in centimetres Temperatures in degrees Fahrenheit or accumulation in inches
precipIntensity Millimetres per hour Millimetres per hour Millimetres per hour Inches per hour
precipIntensityMax Millimetres per hour Millimetres per hour Millimetres per hour Inches per hour
precipAccumulation Centimetres Centimetres Centimetres Inches
liquidAccumulation Centimetres Centimetres Centimetres Inches
snowAccumulation Centimetres Centimetres Centimetres Inches
iceAccumulation Centimetres Centimetres Centimetres Inches
temperature Degrees Celsius Degrees Celsius Degrees Celsius Degrees Fahrenheit
temperatureMin Degrees Celsius Degrees Celsius Degrees Celsius Degrees Fahrenheit
temperatureMax Degrees Celsius Degrees Celsius Degrees Celsius Degrees Fahrenheit
apparentTemperature Degrees Celsius Degrees Celsius Degrees Celsius Degrees Fahrenheit
dewPoint Degrees Celsius Degrees Celsius Degrees Celsius Degrees Fahrenheit
windSpeed Meters per second Kilometres per hour Miles per hour Miles per hour
windGust Meters per second Kilometres per hour Miles per hour Miles per hour
pressure Hectopascals Hectopascals Hectopascals Millibars
visibility Kilometres Kilometres Kilometres Miles

Exclude

Added as part of the V1.0 release, this parameter removes some of the data blocks from the reply. This can speed up the requests (especially if alerts are not needed!), and reduce the reply size. Exclude parameters can be added as a comma-separated list, with the options being:

  • currently
  • minutely
  • hourly
  • daily
  • alerts
  • summary - Allows you to get the summaries in the old format before the translations module was added. This also improves response times if detailed text is not needed.

Some models can also be excluded, which will force data from the fallback sources to be used:

  • hrrr
  • nbm
  • gefs
  • gfs
  • rtma_ru
  • ecmwf_ifs
  • dwd_mosmix

Extend

If extend=hourly is included, hourly data for the next 168 hours will be included, instead of the standard 48! This adds some time (~0.3s) to the response, since additional processing is required.

Version

If version>1 is included fields which were not part of the Dark Sky API will be included. These fields are smoke, smokeMax, smokeMaxTime, fireIndex, fireIndexMax, fireIndexMaxTime, liquidAccumulation, snowAccumulation, iceAccumulation, dawnTime, duskTime, currentDayIce, currentDayLiquid, currentDaySnow, processTime, ingestVersion, nearestCity, nearestCountry, nearestSubNational, cape, solar, capeMax, solarMax, rainIntensity, snowIntensity, iceIntensity, rainIntensityMax, snowIntensityMax, iceIntensityMax. It also includes nearestStormDistance and nearestStormBearing to each of the hourly blocks and sourceIDX where you can see the X/Y and lat/long coordinate for each returned model.

Language

Added as part of the V2.5 release, this parameter allows you to sepecify what language the text summaries use. The possible values for language may be:

Language
  • ar: Arabic
  • az: Azerbaijani
  • be: Belarusian
  • bg: Bulgarian
  • bn: Bengali
  • bs: Bosnian
  • ca: Catalan
  • cs: Czech
  • cy: Welsh
  • da: Danish
  • de: German
  • el: Greek
  • en: English (which is the default)
  • eo: Esperanto
  • es: Spanish
  • et: Estonian
  • fa: Persian
  • fi: Finnish
  • fr: French
  • ga: Irish
  • gd: Gaelic
  • he: Hebrew
  • hi: Hindi
  • hr: Croatian
  • hu: Hungarian
  • id: Indonesian
  • is: Icelandic
  • it: Italian
  • ja: Japanese
  • ka: Georgian
  • kn: Kannada
  • ko: Korean
  • kw: Cornish
  • lv: Latvian
  • ml: Malayam
  • mr: Marathi
  • nl: Dutch
  • no: Norwegian Bokmål
  • pa: Punjabi
  • pl: Polish
  • pt: Portuguese
  • ro: Romanian
  • ru: Russian
  • sk: Slovak
  • sl: Slovenian
  • sr: Serbian
  • sv: Swedish
  • ta: Tamil
  • te: Telugu
  • tet: Tetum
  • tr: Turkish
  • uk: Ukrainian
  • ur: Urdu
  • vi: Vietnamese
  • x-pig-latin: Igpay Atinlay
  • zh: simplified Chinese
  • zh-tw: traditional Chinese

If you require a language not listed above, please consider contributing to the API translation module.

Icon

If you add icon=pirate to the list of parameters you can get an expanded icon set with icons that were not available in the Dark Sky API.

Extra Variables

extraVars= is used to show additional parameters that are not required for most users and may cause confusion. Currently, only stationPressure is allowed, but others may be added in the future.

Include

include= is used to add additional data blocks not available in the Dark Sky API. Currently, only day_night_forecast is allowed, but others may be added in the future.

API Response Example

    GET https://api.pirateweather.net/forecast/1234567890abcdefghijklmnopqrstuvwxyz/45.42,-74.30?&units=ca
    "latitude": 45.42,
    "longitude": -74.3,
    "timezone": "America/Toronto",
    "offset": -5,
    "elevation": 77,
    "currently": {
        "time": 1762718100,
        "summary": "Light Snow",
        "icon": "snow",
        "nearestStormDistance": 17.88,
        "nearestStormBearing": 270,
        "precipIntensity": 0.5321,
        "precipProbability": 0.61,
        "precipIntensityError": 0.159,
        "precipType": "snow",
        "temperature": -0.88,
        "apparentTemperature": -6.77,
        "dewPoint": -3.5,
        "humidity": 0.82,
        "pressure": 1015.24,
        "windSpeed": 17.73,
        "windGust": 46.84,
        "windBearing": 41,
        "cloudCover": 0.81,
        "uvIndex": 0.38,
        "visibility": 16.09,
        "ozone": 311.75
    },
    "minutely": {
        "summary": "Flurries for the hour.",
        "icon": "snow",
        "data": [
        {
            "time": 1762718100,
            "precipIntensity": 0.5321,
            "precipProbability": 0.61,
            "precipIntensityError": 0.159,
            "precipType": "snow"
        },
       ...
      ]
    },
    "hourly": {
        "summary": "Sleet (with a chance of 6–8 cm. of snow) until tomorrow morning and foggy tomorrow afternoon.",
        "icon": "sleet",
        "data": [
            {
                "time": 1762714800,
                "summary": "Light Snow",
                "icon": "snow",
                "precipIntensity": 0.508,
                "precipProbability": 0.47,
                "precipIntensityError": 0.15,
                "precipAccumulation": 0.2985,
                "precipType": "snow",
                "temperature": -0.49,
                "apparentTemperature": -7.05,
                "dewPoint": -3.38,
                "humidity": 0.81,
                "pressure": 1015.9,
                "windSpeed": 21.6,
                "windGust": 35.28,
                "windBearing": 50,
                "cloudCover": 0.93,
                "uvIndex": 0.52,
                "visibility": 4.05,
                "ozone": 313.39
            },
            ...
        ]
    },
    "day_night": {
        "data": [
            {
                "time": 1762678800,
                "summary": "Snow (1–3 cm.) in the afternoon.",
                "icon": "snow",
                "precipIntensity": 0.2345,
                "precipIntensityMax": 1.778,
                "precipProbability": 0.81,
                "precipAccumulation": 1.8828,
                "precipType": "snow",
                "temperature": 0.04,
                "apparentTemperature": -5.22,
                "dewPoint": -4.69,
                "humidity": 0.76,
                "pressure": 1016.93,
                "windSpeed": 16.62,
                "windGust": 28.36,
                "windBearing": 56,
                "cloudCover": 0.87,
                "uvIndex": 0.53,
                "visibility": 10.96,
                "ozone": 314.77,
                "smoke": 0,
            },
            ...
        ]
    },
    "daily": {
    "summary": "Mixed precipitation today through Wednesday and next Sunday, with high temperatures peaking at 3°C on Thursday.",
    "icon": "sleet",
    "data": [
        {
            "time": 1762664400,
            "summary": "Sleet (with a chance of 6–8 cm. of snow) starting in the afternoon.",
            "icon": "sleet",
            "sunriseTime": 1762688903,
            "sunsetTime": 1762723986,
            "moonPhase": 0.65,
            "precipIntensity": 0.7514,
            "precipIntensityMax": 3.81,
            "precipIntensityMaxTime": 1762732800,
            "precipProbability": 1,
            "precipAccumulation": 7.5957,
            "precipType": "sleet",
            "rainIntensityMax": 1.27,
            "temperatureHigh": 0.04,
            "temperatureHighTime": 1762704000,
            "temperatureLow": -1.29,
            "temperatureLowTime": 1762732800,
            "apparentTemperatureHigh": -5.22,
            "apparentTemperatureHighTime": 1762704000,
            "apparentTemperatureLow": -7.92,
            "apparentTemperatureLowTime": 1762732800,
            "dewPoint": -3.96,
            "humidity": 0.81,
            "pressure": 1015.02,
            "windSpeed": 15.36,
            "windGust": 26.74,
            "windGustTime": 1762725600,
            "windBearing": 62,
            "cloudCover": 0.89,
            "uvIndex": 1.8,
            "uvIndexTime": 1762704000,
            "visibility": 9.29,
            "temperatureMin": -2.81,
            "temperatureMinTime": 1762664400,
            "temperatureMax": 0.04,
            "temperatureMaxTime": 1762704000,
            "apparentTemperatureMin": -7.92,
            "apparentTemperatureMinTime": 1762732800,
            "apparentTemperatureMax": -5.22,
            "apparentTemperatureMaxTime": 1762704000
        },
        ...
      ]
    }
    "alerts": [
        {
            "title": "avertissement de neige en vigueur",
            "regions": [
                "secteur de Soulanges"
            ],
            "severity": "Moderate",
            "time": 1762704172,
            "expires": 1762761772,
            "description": "Première bordée de neige de la saison\n\nQuoi : jusqu'à 10 centimètres de neige sont possibles\n\nQuand : d'aujourd'hui à tard ce soir\n\nOù : sud de la province\n\nInformations supplémentaires :\nLa neige pourrait devenir mêlée de grésil par moments. Un court épisode de pluie verglaçante est possible ce soir. Les précipitations se changeront en pluie tard ce soir.\n\nCes conditions pourraient rendre les routes enneigées et glissantes, compliquant ainsi les déplacements dimanche et lundi.\n\n###\n\nLa visibilité sera probablement réduite par moments.\n\nUn avertissement de neige est émis lorsqu’on prévoit des impacts significatifs en raison d’une accumulation de neige.\n\nVeuillez continuer à surveiller les alertes et les prévisions émises par Environnement Canada. Pour signaler du temps violent, envoyez un courriel à meteoQC@ec.gc.ca ou publiez un message sur X en utilisant #meteoqc.",
            "uri": "https://severeweather.wmo.int/v2/cap-alerts/ca-msc-xx/2025/11/09/16/09/12-3372a8228b861e43112cdf50691d180.xml"
        },
    ]
    "flags": {
        "sources": [
            "ETOPO1",
            "hrrrsubh",
            "rtma_ru",
            "hrrr_0-18",
            "nbm",
            "nbm_fire",
            "ecmwf_ifs",
            "hrrr_18-48",
            "gfs",
            "gefs"
        ],
        "sourceTimes": {
            "hrrr_subh": "2025-11-09 17Z",
            "rtma_ru": "2025-11-09 19:30Z",
            "hrrr_0-18": "2025-11-09 17Z",
            "nbm": "2025-11-09 17Z",
            "nbm_fire": "2025-11-09 12Z",
            "ecmwf_ifs": "2025-11-09 00Z",
            "hrrr_18-48": "2025-11-09 12Z",
            "gfs": "2025-11-09 12Z",
            "gefs": "2025-11-09 12Z"
        },
        "nearest-station": -999,
        "units": "ca",
        "version": "V2.9.3"
    }

Time Machine Request

The Time Machine uses either archived 1-hour model results (last 10 days) or the Google ERA5 dataset which is updated weekly and is approximately ten days behind realtime. The forecast request can be extended in several ways by adding parameters to the URL. The full set of URL options is:

      https://timemachine.pirateweather.net/forecast/[apikey]/[latitude],[longitude],[time]?exclude=[excluded]&units=[unit]

Crucially, there's now three different ways a request could be handled:

  1. Requests for the last 24 hours use all the sources and are unchanged;
  2. Request for the last 10 days rely only on GFS data (although ECMWF would be easy to add) stored in the zip file on the server;
  3. Requests >10 days rely on Google's ERA5 zarr dataset, which is a perfect source for this sort of application.

The response format is the same as the forecast except:

  • The currently block will refer to the requested time and not the present time.
  • The minutely block is not present except when querying data from the last 24h.
  • The hourly block will return data from midnight of the requested day to midnight the next day.
  • The day_night block is not included.
  • The daily block will return the data for the current day except when querying data from the last 24h.
  • The alerts block is not included.
  • The flags block will show the sources used in the request, the requested units and the API version.

When requesting data from the PW archive, the optional tmextra query parameter controls which variables are returned. When it is included, same variables that are present in a forecast request (except alerts) are returned. When it is not included (by default), the same range of parameters returned by ERA5 requests is included.

Response

GET https://timemachine.pirateweather.net/forecast/1234567890abcdefghijklmnopqrstuvwxyz/45.42,-74.30,1654056000?&units=ca
{
  "latitude": 45.42,
  "longitude": -74.3,
  "timezone": "America/Toronto",
  "offset": -4.0,
  "currently": {
    "time": 1654056000,
    "summary": "Overcast",
    "icon": "cloudy",
    "precipIntensity": 0,
    "precipType": "none",
    "temperature": 15.2,
    "apparentTemperature": 11.61,
    "dewPoint": 7.57,
    "pressure": 1016.18,
    "windSpeed": 15.23,
    "windGust": 24.4,
    "windBearing": 72,
    "cloudCover": 1
  },
  "hourly": {
    "data": [
      {
        "time": 1654056000,
        "summary": "Overcast",
        "icon": "cloudy",
        "precipIntensity": 0,
        "precipAccumulation": 0,
        "precipType": "none",
        "temperature": 15.2,
        "apparentTemperature": 11.61,
        "dewPoint": 7.57,
        "pressure": 1016.18,
        "windSpeed": 15.23,
        "windGust": 24.4,
        "windBearing": 72,
        "cloudCover": 1
      },
     ...
    ]
  },
  "daily": {
    "data": [
      {
        "time": 1654056000,
        "summary": "Rain throughout the day.",
        "icon": "rain",
        "sunriseTime": 1654074749,
        "sunsetTime": 1654130288,
        "moonPhase": 0.06,
        "precipIntensity": 0.3127,
        "precipIntensityMax": 2.9816,
        "precipIntensityMaxTime": 1654088400,
        "precipAccumulation": 0.7526,
        "precipType": "rain",
        "rainIntensityMax": 2.9816,
        "temperatureHigh": 16.37,
        "temperatureHighTime": 1654102800,
        "temperatureLow": 12.39,
        "temperatureLowTime": 1654092000,
        "apparentTemperatureHigh": 16.27,
        "apparentTemperatureHighTime": 1654102800,
        "apparentTemperatureLow": 8.47,
        "apparentTemperatureLowTime": 1654077600,
        "dewPoint": 9.87,
        "pressure": 1012.11,
        "windSpeed": 15.03,
        "windGust": 30.69,
        "windGustTime": 1654102800,
        "windBearing": 72,
        "cloudCover": 0.98,
        "temperatureMin": 12.39,
        "temperatureMinTime": 1654092000,
        "temperatureMax": 16.37,
        "temperatureMaxTime": 1654102800,
        "apparentTemperatureMin": 8.47,
        "apparentTemperatureMinTime": 1654077600,
        "apparentTemperatureMax": 16.27,
        "apparentTemperatureMaxTime": 1654102800
      }
    ]
  },
  "flags": {
    "sources": [
        "ETOPO1",
        "era5"
    ],
    "sourceTimes": {},
    "nearest-station": 0,
    "units": "ca",
    "version": "V2.9.3"
    }
}

Data Block

The API returns a JSON object with the following properties

latitude

The requested latitude.

longitude

The requested longitude.

timezone

Ex. America/Toronto. The timezone name for the requested location. This is used to determine when the hourly and daily blocks start and calculating the text summaries.

offset

The timezone offset in hours.

elevation

The height above sea level in meters the requested location is.

currently

A block containing the current weather for the requested location.

minutely

A block containing the minute-by-minute precipitation intensity for the 60 minutes.

hourly

A block containing the hour-by-hour forecasted conditions for the next 48 hours. If extend=hourly is used then the hourly block gives hour-by-hour forecasted conditions for the next 168 hours.

day_night

A block containing a day and night forecast for the next 7 days. The day portion of the forecast is calculated from 4:00 am to 4:59 pm and the night portion is calculated from 5:00 pm to 3:59 am. The data is included as a 16 item list, alternating between the day and night forecast starting from the current day.

daily

A block containing the day-by-day forecasted conditions for the next 7 days.

alerts

A block containing any severe weather alerts if any for the current location.

flags

A block containing miscellaneous data for the API request.

Data Point

apparentTemperature

Temperature adjusted for wind and humidity, based the Steadman 1994 approach used by the Australian Bureau of Meteorology. Implemented using the Breezy Weather approach with solar radiation, which follows this equation:

\[ AT = Ta + 0.348 × rh / 100 × 6.105 × exp(17.27 × Ta / (237.7 + Ta)) − 0.70 × ws + 0.70 × Q / (ws + 10) − 4.25\]
  • \(Ta\) is the ambient temperature in °C
  • \(ws\) is the wind speed in m/s
  • \(Q\) is solar radiation in W/m^2

This equation produces results that are similar to heat index and wind chill values.

apparentTemperatureMax

Only on daily. The maximum "feels like" temperature during a day, from midnight to midnight.

apparentTemperatureMaxTime

Only on daily. The time (in UTC) that the maximum "feels like" temperature occurs during a day, from 12:00 am and 11:59 pm.

apparentTemperatureMin

Only on daily. The minimum "feels like" temperature during a day, from from 12:00 am and 11:59 pm.

apparentTemperatureMinTime

Only on daily. The time (in UTC) that the minimum "feels like" temperature occurs during a day, from from 12:00 am and 11:59 pm.

apparentTemperatureHigh

Only on daily. The maximum "feels like" temperature during the daytime, from 6:00 am to 6:00 pm.

apparentTemperatureHighTime

Only on daily. The time of the maximum "feels like" temperature during the daytime, from 6:00 am to 6:00 pm.

apparentTemperatureLow

Only on daily. The minimum "feels like" temperature during the daytime, from 6:00 am to 6:00 pm.

apparentTemperatureLowTime

Only on daily. The time of the minimum "feels like" temperature during the daytime, from 6:00 am to 6:00 pm.

cape

The Convective Available Potential Energy measured in J/kg.

capeMaxTime

Only on daily. the time in which the maximum cape occurs represented in UNIX time.

cloudCover

Percentage of the sky that is covered in clouds. This value will be between 0 and 1 inclusive. Calculated from the the GFS (#650) or HRRR (#115) TCDC variable for the entire atmosphere.

currentDayIce

Only on currently. The ice precipitation that has accumulated so far during the day, from midnight until the forecast request time.

currentDayLiquid

Only on currently. The liquid precipitation that has accumulated so far during the day, from midnight until the forecast request time.

currentDaySnow

Only on currently. The snow precipitation that has accumulated so far during the day, from midnight until the forecast request time.

dawnTime

Only on daily. The time when the the sun is a specific (6 degrees) height above the horizon after sunrise. Calculated from Astal dawn defaults.

dewPoint

The point in which the air temperature needs (assuming constant pressure) in order to reach a relative humidity of 100%. This is value is represented in degrees Celsius or Fahrenheit depending on the requested units. See this resource for more information.

duskTime

Only on daily. The time when the the sun is a specific (6 degrees) height above the horizon before sunset. Calculated from Astal dusk defaults.

feelsLike

The apparent temperature from the GFS or NBM models.

fireIndex

Only on currently and hourly. Only available for the US and parts of Canada. Outside of these locations this will return -999. The Fosburg fire index. Notably, this 0-100 index deals only with conditions, not fuels, and so a high index area is not necessarily high risk for fires.

fireIndexMax

Only on daily. The maximum fireIndex for the given day.

fireIndexMaxTime

Only on daily. the time in which the maximum fireIndex occurs represented in UNIX time.

humidity

Relative humidity expressed as a value between 0 and 1 inclusive. This is a percentage of the actual water vapour in the air compared to the total amount of water vapour that can exist at the current temperature. See this resource for more information.

iceAccumulation

Only on hourly and daily. The amount of ice precipitation expected to fall over an hour or a day expressed in centimetres or inches depending on the requested units.

iceIntensity

Only on hourly, day_night and daily. The intensity of ice precipitation expected to fall over an hour or a day expressed in milimetres or inches depending on the requested units.

iceIntensityMax

Only on day_night and daily. The UNIX time the maximum ice intensity occurs.

icon

One of a set of icons to provide a visual display of what's happening. This could be one of: clear-day, clear-night, thunderstorm, rain, snow, sleet, wind, fog, cloudy, partly-cloudy-day and partly-cloudy-night and may include hail in the future. In some rare cases the API may return none as an icon which could be defined as Not Available.

If icon=pirate is added as a query string parameter the icon set is expanded to include:

  • mostly-clear-day
  • mostly-clear-night
  • mostly-cloudy-day
  • mostly-cloudy-night
  • possible-rain-day
  • possible-rain-night
  • possible-snow-day
  • possible-snow-night
  • possible-sleet-day
  • possible-sleet-night
  • possible-precipitation-day
  • possible-precipitation-night
  • possible-thunderstorm-day
  • possible-thunderstorm-night
  • precipitation
  • drizzle
  • light-rain
  • heavy-rain
  • flurries
  • light-snow
  • heavy-snow
  • very-light-sleet
  • light-sleet
  • heavy-sleet
  • breezy
  • dangerous-wind
  • mist
  • haze
  • smoke
  • mixed

Note that smoke and haze may be moved to the default icon set in the future, at which point they will be removed from this expanded list.

The daily icon is calculated between 4:00 am and 4:00 am local time. The algorithm here is straightforward, coming from this NOAA resource:

Currently:
  • If precipitation accumulation is greater than 0.02 mm, then the precipitation type.
    • If CAPE is greater than or equal to 2500J/kg then thunderstorm.
  • If visibility is less than 10 km, then fog.
  • If winds are greater than 6.7056 m/s, then wind.
  • If cloud cover is greater than 87.5%, then cloudy.
  • If cloud cover is greater than 37.5% and less than 87.5%, then partly-cloudy-day or partly-cloudy-night.
  • If cloud cover is less than 37.5%, then clear.
Hourly:
  • If precipitation probability is greater than 25% and accumulation is greater than 0.02 mm, then the precipitation type.
    • If CAPE is greater than or equal to 2500J/kg then thunderstorm.
  • If visibility is less than 10 km, then fog.
  • If winds are greater than 6.7056 m/s, then wind.
  • If cloud cover is greater than 87.5%, then cloudy.
  • If cloud cover is greater than 37.5% and less than 87.5%, then partly-cloudy-day or partly-cloudy-night.
  • If cloud cover is less than 37.5%, then clear.
Daily and Day/Night:

With the daily summaries being introduced in version 2.7 the day icon now considers the day as a whole rather than using daily averages. The icon shown will generally be whichever condition comes first so if the morning is foggy and the evening is windy the fog icon will be shown. The cloud cover icons will only be shown as long as no other conditions are forecasted for the day.

Precipitation

The precipitation icon logic is as follows:

  • If max probability is greater than 25% in any hour
  • The total accumulation depends on the number of periods has precipitation forecasted
    • Total precipitation needs to be 0.25 mm for one period
    • Total precipitation needs to be 0.50 mm for two periods
    • Total precipitation needs to be 0.75 mm for three periods
    • Total precipitation needs to be 1 mm for four periods

The precipitation with the most accumulation forecasted is generally the icon which is shown unless:

  • If maximum CAPE (with precipitation) is greater than 2500J/kg then thunderstorm.
  • If more than 10 mm of rain is forecast, then rain
  • If more than 5 mm of snow is forecast, then snow
  • Else, if more than 1 mm of ice is forecast, then sleet

Fog and Wind

The fog and wind icons are shown if at least one period has at least half of its hours (or three or more hours for longer periods) as foggy or windy and there is no precipitation then the icon is shown.

  • If visibility is less than 10 km then fog.
  • If wind speed is greater than 6.7056 m/s, then wind.

Cloud Cover

The average cloud cover is calculated for each period and the most common level (clear, mostly clear, partly cloudy, mostly cloudy or overcast) is chosen as the icon. The exception is if all of the periods have a different level. In this case the following logic is used:

  • If the maximum cloud cover occurs in the last period then use the lowest cloud cover level
  • Otherwise use the maximum cloud cover level for the day

The cloud cover icon thresholds are the following:

  • If cloud cover is greater than 87.5%, then cloudy.
  • If cloud cover is greater than 37.5% and less than 87.5%, then partly-cloudy-day.
  • If cloud cover is less than 37.5%, then clear.

For additional details, see issue #3.

liquidAccumulation

Only on hourly and daily. The amount of liquid precipitation expected to fall over an hour or a day expressed in centimetres or inches depending on the requested units.

moonPhase

Only on daily. The fractional lunation number for the given day. 0.00 represents a new moon, 0.25 represents the first quarter, 0.50 represents a full moon and 0.75 represents the last quarter.

nearestStormBearing

The approximate direction in degrees in which a storm is travelling with 0° representing true north. Calculated with the excellent XArray-Spatial package using a 0.2 mm/h water equivalent (so 2 mm/h of snow or 0.2 mm/h of rain) threshold for a storm.

nearestStormDistance

The approximate distance to the nearest storm in kilometers or miles depending on the requested units. Calculated with the excellent XArray-Spatial package using a 0.2 mm/h water equivalent (so 2 mm/h of snow or 0.2 mm/h of rain) threshold for a storm. Note that the distance is calculated from the midpoint of a GFS model cell to the midpoint of a model cell with a "storm".

ozone

Only on currently, hourly and day_night. The density of total atmospheric ozone at a given time in Dobson units.

precipAccumulation

Only on hourly, day_night and daily. The total amount of precipitation expected to fall over an hour or a day expressed in centimetres or inches depending on the requested units. For day 0, this is the precipitation during the remaining hours of the day.

Snow accumulation is estimated using a density formulation, adjusting based on the temperature and wind speed when the snow falls. It tends to be around 1:10, but will vary when it's a warm, slushy snowfall.

  • 5 cm (50 mm) of snow is forecasted for an hour, precipAccumulation, in cm, will return 5.
  • 5 mm of rain is forecasted for an hour, precipAccumulation, in cm, will return 0.5.
  • 5 mm of rain and 5 cm of snow is forecasted for an hour, precipAccumulation, in cm, will return 5.5. This illustrates the value of using the liquidAccumulation, snowAccumulation, and iceAccumulation parameters instead of precipAccumulation.

precipIntensity

Precipitation intensity units have been revised to reflect the Dark Sky style. This means that intensity is always reported in liquid water equivalent, and this should be reflected when displaying the data.

  • So if 5 cm (50 mm) of snow is forecasted for an hour, precipIntensity, in mm, will return 5, as 5 mm of rain provides 50 mm of snow.
    • If 5 mm of rain is forecasted for an hour, precipIntensity, in mm, will return 5, for 5 mm of rain.
  • See this thread for details.
  • It is strongly recommended to use the type specific intensities.

precipIntensityError

The standard deviation of the precipIntensity from the GEFS/ECMWF IFS model.

precipIntensityMax

Only on day_night and daily. The maximum value of precipIntensity for the given day.

precipIntensityMaxTime

Only on daily. The point in which the maximum precipIntensity occurs represented in UNIX time.

precipIntensityMin

Only on daily. The minimum value of precipIntensity for the given day.

precipIntensityMinTime

Only on daily. The point in which the minimum precipIntensity occurs represented in UNIX time.

precipProbability

The probability of precipitation occurring expressed as a decimal between 0 and 1 inclusive.

  • Currently precipProbability is the chance of precipitation occurring at the requested time.
  • Hourly precipProbability is the chance of precipitation occurring in that hour.
  • Daily precipProbability is the maximum chance of precipitation occurring in that day. If the maximum precipProbability for a day is 80% then the daily precipProbability would be 80%. For day 0, this is the probability of precipitation during the remaining hours of the day.

You can get a probability >0 with no precipitation. It's because they're sometimes coming from different sources or different models, and the ensemble will sometimes show a chance of something but not confident in any amount. Basically, one is probabilistic, the other deterministic.

precipType

The type of precipitation occurring. If precipIntensity is greater than zero this property will have one of the following values: rain, snow, or sleet. For requests with version>1, ice and mixed are also possible values. If precipIntensity is zero, the value will be none. sleet is defined as any precipitation which is neither rain nor snow. For the daily block, the following process is used to assess a type when multiple precipitation types are expected:

  1. If more than 1 mm of ice is forecast, then ice. Otherwise:
  2. If there is more than 5 cm of snow, then snow. Otherwise:
  3. If there is more than 10 mm of rain, then rain Otherwise:
  4. Use the most common precipitation type.

If querying the API with version>1 then the precipitation types are expanded to include ice and mixed. The ice precipitation type is defined as freezing rain and mixed is defined as rain, snow and ice precipitation occurring.

See this issue for additional discussion.

pressure

The sea-level pressure represented in hectopascals or millibars depending on the requested units.

rainIntensity

Only on hourly, day_night and daily. The intensity of rain precipitation expected to fall over an hour or a day expressed in milimetres or inches depending on the requested units.

rainIntensityMax

Only on day_night and daily. The UNIX time the maximum rain intensity occurs.

snowAccumulation

Only on hourly, day_night and daily. The amount of snow precipitation expected to fall over an hour or a day expressed in centimetres or inches depending on the requested units.

snowIntensity

Only on hourly, day_night and daily. The intensity of snow precipitation expected to fall over an hour or a day expressed in centimetres or inches depending on the requested units.

snowIntensityMax

Only on day_night and daily. The UNIX time the maximum snow intensity occurs.

smoke

Only on currently, hourly and day_night. Only available for the US and parts of Canada. Only returns data for the next 36-hours. If there is no data this will return -999. The amount of near-surface (8 m) smoke represented in µg/m3.

smokeMax

Only on daily. The maximum smoke for the given day.

smokeMaxTime

Only on daily. the time in which the maximum smoke occurs represented in UNIX time.

solar

The Downward Short-Wave Radiation Flux measured in W/m^2.

solarMax

Only on daily. the time in which the maximum solar occurs represented in UNIX time.

stationPressure

Hidden by default behind the extraVars=stationPressure queryparam. The station pressure represented in hectopascals or millibars depending on the requested units.

summary

A human-readable summary describing the weather conditions for a given data point. The daily summary is calculated between 4:00 am and 4:00 am local time. For a full list of possible summary values you can view Appendex A in the translations repository.

sunriseTime

Only on daily. The time when the sun rises for a given day represented in UNIX time.

sunsetTime

Only on daily. The time when the sun sets for a given day represented in UNIX time.

temperature

The air temperature in degrees Celsius or degrees Fahrenheit depending on the requested units

temperatureHigh

Only on daily. The daytime high temperature calculated between 6:01 am and 6:00 pm local time.

temperatureHighTime

Only on daily. The time in which the high temperature occurs represented in UNIX time.

temperatureLow

Only on daily. The overnight low temperature calculated between 6:01 pm and 6:00 am local time.

temperatureLowTime

Only on daily. The time in which the low temperature occurs represented in UNIX time.

temperatureMax

Only on daily. The maximum temperature calculated between 12:00 am and 11:59 pm local time.

temperatureMaxTime

Only on daily. The time in which the maximum temperature occurs represented in UNIX time.

temperatureMin

Only on daily. The minimum temperature calculated between 12:00 am and 11:59 pm local time.

temperatureMinTime

Only on daily. The time in which the minimum temperature occurs represented in UNIX time.

time

The time in which the data point begins represented in UNIX time. The currently block represents the current time, the minutely block is aligned to the top of the minute, the hourly block the top of the hour and the daily block to midnight of the current day in the current time zone.

uvIndex

The measure of UV radiation as represented as an index starting from 0. 0 to 2 is Low, 3 to 5 is Moderate, 6 and 7 is High, 8 to 10 is Very High and 11+ is considered extreme. See this resource for more information.

uvIndexTime

Only on daily. The time in which the maximum uvIndex occurs during the day.

visibility

The visibility in kilometres or miles depending on the requested units. In the daily block the visibility is the average visibility for the day. This value is capped at 16 kilometres or 10 miles depending on the requested units.

windBearing

The direction in which the wind is blowing in degrees with 0° representing true north. To convert degrees to a cardinal direction you can refer to this table.

windGust

The wind gust in kilometres per hour or miles per hour depending on the requested units.

windGustTime

Only on daily. The time in which the maximum wind gust occurs during the day represented in UNIX time.

windSpeed

The current wind speed in kilometres per hour or miles per hour depending on the requested units.

Alerts

title

A brief description of the alert.

regions

An array of strings containing all regions included in the weather alert.

severity

Indicates how severe the weather alert is. Possible values are:

  • Extreme - Extraordinary threat to life or property
  • Severe - Significant threat to life or property
  • Moderate - Possible threat to life or property
  • Minor - Minimal threat to life or property
  • Unknown

time

The time in which the alert was issued represented in UNIX time. From the effective time.

expires

The time in which the alert expires represented in UNIX time. Note: -999 will be returned for alerts without an expires time.

description

A detailed description of the alert.

uri

A HTTP(S) url in which you can visit for more information about the alert.

Flags

sources

The models used to generate the forecast.

sourceTimes

The time in UTC when the model was last updated.

sourceIDX

The X,Y coordinate and the lat, lon coordinate for the grid cell used for each model used to generate the forecast.

nearest-station

Distance to the closest DWD MOSMIX station to your location in kilometres or miles depending on the units. If there are no stations for your location this will return -999.

units

Indicates which units were used in the forecasts.

version

The version of Pirate Weather used to generate the forecast.

processTime

The time taken to process the request in milliseconds.

ingestVersion

The ingest version of Pirate Weather used to generate the forecast.

nearestCity

The name of the closest city to your location.

nearestCountry

The name of the closest country to your location.

nearestSubNational

The name of the closest state or province to your location.

Response Headers

Cache-Control

The directive on how the response data can be cached.

Ratelimit-Limit

The number of API calls you can do per month.

Ratelimit-Remaining

The number of API calls remaining for the month.

Ratelimit-Reset

The time in seconds until your rate limit resets.

X-Forecast-API-Calls

The number of API calls your key has done for the month.

X-Node-Id

Shows which node processed your API call.

X-Response-Time

The time taken to process the request in milliseconds.

Error Codes

400 Bad Request

You may encounter this error if you query the API using an invalid latitude or longitude.

401 Unauthorized

You may encounter this error if you try to query an endpoint your API key does not have access to or if you did not include an API key in your request.

404 Not Found

You may encounter this error if query the API using an invalid route or if you do not supply a latitude or longitude in your request.

429 Too Many Requests

You may encounter this error if your API key has hit the quota for the month.

500 Internal Server Error

If the API returns a 500 error you can retry the request to see if the API will return a 500 error again. If the issue persists please check the GitHub issues to see if the issue has been reported otherwise create a bug report and the issue will be investigated.