Using the Spire Weather API
      Back to home
      1. Help Center
      2. Spire Weather & Climate
      3. Using the Spire Weather API

      Downloading multiple forecast files

      Using the forecast file API endpoints to download multiple files

      Understanding Forecast Issuance Times

      Before following the examples in this article, it is recommended that the reader understands Spire Weather's forecast update schedule and forecast ranges, as described here.

      /forecast/file/    API Endpoint

      The /forecast/file/ API endpoint is used for downloading forecast files from 3 days in the past up until the most recent forecast issuance.

      Usage typically begins with listing which files are currently available.

      The first call can be used to list specific issuance times or forecast ranges per bundle:

      https://api.wx.spire.com/forecast/file

      The second call can be used to list the latest issuances per bundle, regardless of the forecast range:

      https://api.wx.spire.com/forecast/latest/file

      Standard Short-Range Forecast

      Standard short-range forecasts (hourly updates for 24 hours)  can be requested using the format specified in the following example. The important curl syntax to note which specifies more than one forecast file is: f[000-024:1] This tells curl to increment the forecast lead times from 000 to 024 with a step of 1 for each subsequent request. Therefore, the first request will be formatted with 000, the second request will be formatted with 001, the third request will be formatted with 002, and so on until the final request is formatted with 024. The issuance date 20200505 and the issuance time 00z (00:00 UTC) will remain the same for each request.

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f[000-024:1].grib2" -H "spire-api-key: TOKEN"

      Unpacking the syntax here, curl will expand the example above into the following, thus downloading all 25 files for a standard short-range forecast:

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"

      ...

      ...

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f024.grib2" -H "spire-api-key: TOKEN"

      Standard Medium-Range Forecast

      Standard medium-range forecasts (6-hourly updates for 7 days)  can be requested using the format specified in the following example. The important curl syntax to note which specifies more than one forecast file is: f[000-168:6] This tells curl to increment the forecast lead times from 000 to 168 with a step of 6 for each subsequent request. Therefore, the first request will be formatted with 000, the second request will be formatted with 006, the third request will be formatted with 012, and so on until the final request is formatted with 168. The issuance date 20200505 and the issuance time 00z (00:00 UTC) will remain the same for each request.

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f[000-168:6].grib2" -H "spire-api-key: TOKEN"

      Unpacking the syntax here, curl will expand the example above into the following, thus downloading all 29 files for a standard medium-range forecast:

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f006.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f012.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f018.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f024.grib2" -H "spire-api-key: TOKEN"

      ...

      ...

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f168.grib2" -H "spire-api-key: TOKEN"

      Medium-Range, High-Frequency Forecast

      Medium-range, high-frequency forecasts (hourly for 24 hours, and 6-hourly for following 6 days)  can be requested using the format specified in the following example. The important curl syntax to note which specifies more than one forecast file is: f[000-168:1] This tells curl to increment the forecast lead times from 000 to 168 with a step of 1 for each subsequent request. Therefore, the first request will be formatted with 000, the second request will be formatted with 001, the third request will be formatted with 002, and so on until the final request is formatted with 168. The issuance date 20200505 and the issuance time 00z (00:00 UTC) will remain the same for each request.

      Note: requests for lead times between 024 and 168 which are not divisible by 6 will result in empty files being returned, since forecast lead times are only provided for every 6 hours after the first day. Therefore, the user will need to perform some garbage collection after the following call to delete those files.

      curl -OJL -X GET "https://api.wx.spire.com/forecast/file/sof-d.20200505.t00z.0p125.basic.global.f[000-168:1].grib2" -H "spire-api-key: TOKEN"

      /sample/file/    API Endpoint

      The /sample/file/ API endpoint is used for downloading specific historical forecast files from more than 3 days in the past. Historical forecast files available at this endpoint represent manual selections that have been restored from Spire Weather's complete data archives, and are not representative of the complete archive's contents.

      Users who would like to access specific historical forecasts through this API endpoint can ask their sales representative to open an archive-restore request with Spire Weather's science team. The archive-restore process takes some time, but is generally finished within one work week or less. Given that number of forecast issuances and lead times generated each day (detailed here), there are many possible configurations of "historical forecast data". Here are some examples:

      • Analysis times (one every 6 hours)
      • The best guess for each hour of the day (analysis plus 01:00 to 05:00 forecasts),
      • Analysis plus the next 24h (hourly data)
      • Analysis plus the next 48h (hourly data, 3-hourly, etc.)
      • Analysis every 6 hours
      • 3 days of forecast twice/day
      • etc.

      Analysis times (one every 6 hours)

      The "analysis time" is the first lead time of a forecast issuance. To use the syntax from previous examples, it is the lead time specified as f000. The analysis file represents the current state of Spire Weather's global forecast model at the time that any forecast is made. Just as we have done in the previous examples, we can use curl syntax to specify the analysis times for a certain range of dates. In this case, the lead time will always be f000, but we specify a range of issuance dates using: [20200401-20200415:1]. We also specify all 4 daily issuance times using: t[00-18:6]z . This tells curl to increment the issuance date from 20200401 to 20200402 to 20200403, and so on until 20200407. For each of these issuance dates, the issuance time will be incremented from t00z to t06z to t12z to t18z.

      In other words, there will be 4 files downloaded per day of the specified date range.

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.[20200401-20200407:1].t[00-18:6]z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"

      Unpacking the syntax here, curl will expand the example above into the following:

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t00z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t06z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t12z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t18z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t00z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t06z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t12z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t18z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200403.t00z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200403.t06z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200403.t12z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200403.t18z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"

      ...
      ...
      ...

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t00z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t06z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t12z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t18z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"

      Each hour of every day (0h analysis plus 01:00 - 05:00 forecasts)

      This example is quite popular, and represents the closest to "observed weather" that Spire NWP data can currently offer. It provides one forecast file for each hour within the specified date range.

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.[20200401-20200407:1].t[00-18:6]z.0p125.basic.global.f[000-005:1].grib2" -H "spire-api-key: TOKEN"

      Unpacking the syntax here, curl will expand the example above into the following:

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t00z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t00z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t00z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t00z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t00z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t00z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t06z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t06z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t06z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t06z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t06z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t06z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t12z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t12z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t12z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t12z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t12z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t12z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t18z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t18z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t18z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t18z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t18z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200401.t18z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"



      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t00z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t00z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t00z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t00z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t00z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t00z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t06z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t06z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t06z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t06z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t06z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t06z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t12z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t12z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t12z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t12z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t12z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t12z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t18z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t18z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t18z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t18z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t18z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200402.t18z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      ...

      ...

      ...

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t00z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t00z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t00z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t00z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t00z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t00z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t06z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t06z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t06z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t06z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t06z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t06z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t12z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t12z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t12z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t12z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t12z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t12z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t18z.0p125.basic.global.f000.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t18z.0p125.basic.global.f001.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t18z.0p125.basic.global.f002.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t18z.0p125.basic.global.f003.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t18z.0p125.basic.global.f004.grib2" -H "spire-api-key: TOKEN"
      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.20200407.t18z.0p125.basic.global.f005.grib2" -H "spire-api-key: TOKEN"

      Analysis plus the next 24h (hourly data)

      Another way to describe this example is: "the short-range forecasts for all issuance times in a given date range". Unlike the previous example which only requests one file for each hour, this example will have significant overlap, resulting in several distinct files for a single specific time (from different forecast issuances). The previous example specifies f[000-005:1] for the lead times while this example specifies f[000-024:1].

      curl -OJL -X GET "https://api.wx.spire.com/sample/file/sof-d.[20200401-20200407:1].t[00-18:6]z.0p125.basic.global.f[000-024:1].grib2" -H "spire-api-key: TOKEN"