SpotWx API Documentation

This page documents SpotWx API services. For the regular SpotWx site visit spotwx.com.

What We Offer

SpotWx provides API access to the same numerical forecast model data featured on spotwx.com. If you need access to the raw data behind the graphs, the SpotWx API may be your solution.

There are currently CSV and JSON versions of the API. Which one you prefer will depend on your needs, whether you are incorporating the data into an internal business process or using the data in an app or dashboard.

What We Don't Offer

The API does not not include the SCRIBE/UMOS or Meteocode forecast data that is shown on SpotWx, mainly because nobody has asked.

To keep costs (and fees) down and manage timelines, the API is a DIY, "roll your own" affair. There's no fancy client SDKs, just the basics so far.

CSV API Details

Note: The API is frequently updated with new weather elements. Always parse the CSV data using the headers to ensure future updates don't break your code. Old elements will retain their names for backward compatibility.

Base URL: https://spotwx.io/api.php

URL Parameters

  • key [required] - your API key provided by SpotWx

  • lat [required] - latitude in decimal degrees

  • lon [required] - longitude in decimal degrees

  • model [required] - weather model. Options are:
    • hrdps_1km_west
    • hrdps_continental
    • rdps
    • gdps
    • hrrr
    • rap
    • nam
    • gfs
    • geps
    • inventory - returns a list of available models for your lat/lon

  • tz [optional] - Integer timezone offset in hours from UTC (i.e. for EST enter -5). Timezone defaults to 0 for UTC time.

  • format [optional] - Options are:

    • csv - default
    • prometheus - formatted for Prometheus fire growth model
    • cipra - formatted for CIPRA agricultural model.

  • output [optional] - Options are:
    • forecast - default
    • metadata - returns model metadata for your lat/lon
    • archive - returns a list of available archived model runs for your model
    • data dictionary - returns data dictionary of model parameters

  • modelrun [optional] - If omitted the most recent forecast is returned. Other options are:
    • HHZ - Zulu hour of the requested model run (i.e. 06Z)
    • YYYYMMDD_HHZ - Year, month, day and zulu hour of the requested model run (i.e. 20230401_06Z)

  • ens_val [optional] - This applies only to the GEPS model. Options are:
    • median [default] - return median ensemble values
    • mean - return mean values
    • max - return max values
    • min - return min values
    • p - return a percentile value (i.e. p75)
    • members - return each individual member's value

  • station [optional] - This applies only to the CIPRA format. Enter your desired station name (i.e. SiteA)

Examples

  • using coordinates 49.7016, -123.1558:

Get the latest RDPS forecast, in UTC time:

https://spotwx.io/api.php?key=<your API key>&lat=49.7016&lon=-123.1558&model=rdps

Get the latest HRDPS Continental forecast, in UTC -8 hrs time:

https://spotwx.io/api.php?key=<your API key>&lat=49.7016&lon=-123.1558&model=hrdps_continental&tz=-8

Get a list of available models for those coordinates:

https://spotwx.io/api.php?key=<your API key>&lat=49.7016&lon=-123.1558&model=inventory

Get a list of archived HRRR models:

https://spotwx.io/api.php?key=<your API key>&lat=49.7016&lon=-123.1558&model=hrrr&output=archive

Get an archived HRRR model for 20230320 18Z:

https://spotwx.io/api.php?key=<your API key>&lat=49.7016&lon=-123.1558&model=hrrr&modelrun=20230320_18Z

Get the metadata for the GDPS model (metadata returns central grid cell coordinates, model height, and land proportion):

https://spotwx.io/api.php?key=<your API key>&lat=49.7016&lon=-123.1558&model=gdps&output=metadata

Get a data dictionary explaining all the weather parameters for the RDPS model:

https://spotwx.io/api.php?key=<your API key>&lat=49.7016&lon=-123.1558&model=rdps&output=data_dictionary

Get the latest GEPS forecast, all individual ensemble members, in UTC time:

https://spotwx.io/api.php?key=<your API key>&lat=49.7016&lon=-123.1558&model=geps&ens_val=members

Get the latest NAM forecast using the Prometheus format:

https://spotwx.io/api.php?key=<your API key>&lat=49.7016&lon=-123.1558&model=nam&format=prometheus


Current models and weather elements available in the CSV API:

X = available, blank = not available

(See the Data Dictionary section for details about each element.)

HRDPS 1km West HRDPS Continental RDPS GDPS HRRR RAP NAM GFS GEPS
TMP X X X X X X X X X
TMP_925MB X X X X X X X X
TMP_850MB X X X X X X X X
TMP_700MB X X X X X X X X
TMP_500MB X X X X X X X
DP X X X X X X X X X
RH X X X X X X X X X
WB X X X X X X X X
WSPD X X X X X X X X X
WDIR X X X X X X X X X
GUST X X X X X X X X
GUST_MAX X X X
PRECIP_ttl X X X X X X X X X
PRECIP_int X X X X X X X X
RQP X X X X X X X X X
SQP X X X X X X X X X
FQP X X X X X X X X X
IQP X X X X X X X X X
CLOUD X X X X X X X X X
LCDC X X
MCDC X X
HCDC X X
HGT_CLOUDCEILING
HGT_CLOUDTOP X X
HGT_CLOUDBASE X X
HGT_CONVECTIVECLOUDTOP X
SLP X X X X X X X X X
WSPD_20M X
WSPD_30M X
WSPD_40M X X X X X
WSPD_50M X
WSPD_60M
WSPD_80M X X X X X X X X
WSPD_90M
WSPD_1000M X
WSPD_120M X X X X
WDIR_20M X
WDIR_30M X
WDIR_40M X X X X X
WDIR_50M X
WDIR_60M
WDIR_80M X X X X X X X X
WDIR_90M
WDIR_100M X
WDIR_120M X X X X X
WSPD_925MB X X X X X X X X
WDIR_925MB X X X X X X X X
WSPD_850MB X X X X X X X X
WDIR_850MB X X X X X X X X
WSPD_700MB X X X X X X X X
WDIR_700MB X X X X X X X X
HGT_DRYBULB_0C X X X
HGT_WETBULB_0C X X
DSWRF X X X X X X X
4LFTX X X X X X X X X
LFTX X X X X
PLI X
CAPE X X X X X X X X
CAPE_90MB X X
CAPE_180MB X X X X
CAPE_255MB X X
CIN X X X X X X X
CIN_90MB X X
CIN_180MB X X X X
CIN_255MB X X
SHWINX X X X X
TOTALX X X
KX X X
1000_500MB_THICKNESS X X X X X X X X
HLCY_3K X X X X X X X
HLCY_1K X X
PWAT X X X X X X X X
VIS X X X
HPBL X X X X X X X X
WSPD_PBL X X
WDIR_PBL X X
VRATE_PBL X X
LTNG_DEN X
LTNG X X
HGT_EQUILIBRIUM X X
SNOD
TMAX
TMIN
HAINESX X X X
HAINESX_LOW X X X X
HAINESX_MID X X X X
HAINESX_HIGH X X X X
CHAINESX_MID X X X X
HGT_SNOWLVL X
HRDPS 1km West HRDPS Continental RDPS GDPS HRRR RAP NAM GFS GEPS

Data Dictionary

element description units
MODEL name of forecast weather model n/a
LAT latitude of requested forecast spot decimal degrees
LON longitude of requested forecast spot decimal degrees
ISSUEDATE issue date/time of forecast model YYYY-MM-DD hh:mm in selected UTC offset
UTC_OFFSET offset from UTC time hours
DATETIME effective date/time of forecast data YYYY-MM-DD hh:mm in selected UTC offset
TMP temperature at 2 meters above ground celsius
TMP_925MB temperature at the 925 millibar pressure level celsius
TMP_850MB temperature at the 850 millibar pressure level celsius
TMP_700MB temperature at the 700 millibar pressure level celsius
TMP_500MB temperature at the 500 millibar pressure level celsius
FL FeelsLike temperature at 2 meters above ground level celsius (though technically it's unitless)
DP dew point at 2 meters above ground celsius
RH relative humidity at 2 meters above ground percent
WB web bulb temperature at 2 meters above ground celsius
WSPD wind speed at 10 meters above ground km/h
WDIR wind direction at 10 meters above ground degrees true
GUST wind gust speed km/h
GUST_MAX maximum theoretical gust speed km/h
PRECIP_ttl accumulated precipitation at surface millimeters
PRECIP_int precipitation in the forecast interval millimeters
RQP accumulated rain at surface millimeters
SQP accumulated snow water equivalent at surface millimeters
FQP accumulated freezing rain at surface millimeters
IQP accumulated ice pellets at surface millimeters
CLOUD total cloud coverage in all levels percent
LCDC total low level cloud coverage percent
MCDC total mid level cloud coverage percent
HCDC total high level cloud coverage percent
HGT_CLOUDCEILING height of cloud ceiling m
HGT_CLOUDTOP height of cloud tops m
HGT_CLOUDBASE height of cloud base m
SLP sea level pressure millibars
WSPD_20M wind speed at 20 meters above ground km/h
WSPD_30M wind speed at 30 meters above ground km/h
WSPD_40M wind speed at 40 meters above ground km/h
WSPD_50M wind speed at 50 meters above ground km/h
WSPD_60M wind speed at 60 meters above ground km/h
WSPD_80M wind speed at 80 meters above ground km/h
WSPD_90M wind speed at 90 meters above ground km/h
WSPD_1000M wind speed at 100 meters above ground km/h
WSPD_120M wind speed at 120 meters above ground km/h
WDIR_20M wind direction at 20 meters above ground degrees true
WDIR_30M wind direction at 30 meters above ground degrees true
WDIR_40M wind direction at 40 meters above ground degrees true
WDIR_50M wind direction at 50 meters above ground degrees true
WDIR_60M wind direction at 60 meters above ground degrees true
WDIR_80M wind direction at 80 meters above ground degrees true
WDIR_90M wind direction at 90 meters above ground degrees true
WDIR_100M wind direction at 100 meters above ground degrees true
WDIR_120M wind direction at 120 meters above ground degrees true
WSPD_925MB wind speed at 925 millibar pressure level km/h
WSPD_850MB wind speed at 850 millibar pressure level km/h
WDIR_850MB wind direction at 850 millibar pressure level degrees true
WSPD_700MB wind speed at 700 millibar pressure level km/h
WDIR_700MB wind direction at 700 millibar pressure level degrees true
WSPD_500MB wind speed at 500 millibar pressure level km/h
WDIR_500MB wind direction at 500 millibar pressure level degrees true
VRATE_PBL planetary boundary layer ventilation rate m*m/s
WSPD_PBL planetary boundary layer wind speed km/h
WDIR_PBL planetary boundary layer wind direction degrees true
HGT_DRYBULB_0C dry bulb freezing level geopotential height m
HGT_WETBULB_0C wet bulb freezing level geopotential height m
DSWRF downward short-wave radiation flux watts/m^2
4LFTX best 4-layer lifted index kelvin
LFTX lifted index kelvin
PLI precel lifted index kelvin
CAPE convective available potential energy from surface J/kg
CAPE_90MB convective available potential energy from 90-0 mb above ground J/kg
CAPE_180MB convective available potential energy from 180-0 mb above ground J/kg
CAPE_255MB convective available potential energy from 255-0 mb above ground J/kg
CIN convective inhibition from surface J/kg
CIN_90MB convective inhibition from 90-0 mb above ground J/kg
CIN_180MB convective inhibition from 180-0 mb above ground J/kg
CIN_255MB convective inhibition from 255-0 mb above ground J/kg
SHWINX Showalter Index kelvin
TOTALX Total-Totals Index kelvin
KX K-Index kelvin
1000_500MB_THICKNESS height difference between 1000 mb and 500 mb pressure levels decameters
HLCY_3K helicity to 3000 m m^2/s^2
HLCY_1K helicity to 1000 m m^2/s^2
PWAT precipitable water mm
VIS visibility at surface km
HPBL height of planetary boundary layer meters above ground
WSPD_PBL wind speed in planetary boudary layer kph
WDIR_PBL wind direction in planetary boundary layer degrees true
VRATE_PBL ventilation rate in planetary boundary layer m^2/s
LTNG_DEN lightning flash density rate flashes/km^2/5 min
LTNG prescence of lightning boolean
HGT_EQUILIBRIUM height of equilibrium level m
SNOD snow depth m
TMAX maximum temperature in the forecast interval celsius
TMIN minimum temperature in the forecast interval celsius
HAINESX Haines Index (provided by NCEP) n/a
HAINESX_LOW Haines Index for low elevations (calculated by SpotWx) n/a
HAINESX_MID Haines Index for mid elevations (calculated by SpotWx) n/a
HAINESX_HIGH Haines Index for high elevations (calculated by SpotWx) n/a
CHAINESX_MID Continuous Haines Index for mid elevations (calculated by SpotWx) n/a
HGT_SNOWLVL Snow level height above sea level (-1 = wet snow at surface, -2 = dry snow at surface) m
element_n the nth ensemble member of the respective element as above per weather element
element_CONTROL ensemble control forecast of the respective element as above per weather element

JSON API Details

Please ask if interested in the current beta JSON API.

Access and Pricing

Please contact Garth at SpotWx to arrange for an API key and discuss pricing. Automation of the signup process is pending.