Space Weather API

API specification

Overview

This API provides access to near real-time Space Weather Services data from the Australian Bureau of Meteorology.

Use of the API requires registration. Upon successful registration, an API key will be provided. This key needs to be included in requests for data.

The API request methods are as follows.

get-k-index
Requests the current K index from a specified location (Australian region or several observing sites).
get-mag-alert
Requests details of any magnetic alert current for the Australian region.
get-mag-warning
Requests details of any geophysical warning currently active for the Australian region.
get-aurora-alert
Requests details of any aurora alert current for the Australian region.
get-aurora-watch
Requests details of any aurora watch current for the Australian region.
get-aurora-outlook
Requests details of any aurora outlook current for the Australian region.

Each API method URL includes the prefix:

http://sws-data.sws.bom.gov.au/api/v1/

Data can be obtained using an HTTP POST request to the appropriate URL. An API key and any relevant options must be included in the request body. The request body and the response are in JSON. The character encoding is UTF-8.

All dates and times are in UTC, using the following formats. Times use a 24-hour clock.

date
yyyy-mm-dd
time
yyyy-mm-dd hh:mm:ss

Examples of successful and unsuccessful requests are included with the API method descriptions below. For more examples, please see the demo page.

Error codes

When a request fails, the HTTP status will indicate the reason. As well (where possible) the response body will include one or more error codes and corresponding messages, as follows. (Although error codes will remain constant, the corresponding messages might change.)

01
Unsupported HTTP request method: {method-name}
11
Unrecognised API request: {request}
12
Unsupported API version: {version}
13
Unsupported API request method: {method-name}
14
Request body cannot be parsed
21
Missing API key
22
Unsupported API key: {api_key}
23
Requested data not permitted to the API key provided
31
Missing field: {field-name}
32
Unsupported field: {field-name}
41
Missing option: {option-name}
42
Unsupported option name: {option-name}
43
Unsupported option value: {option-name}={option-value}

HTTP status

HTTP status values returned include the following.

200 OK Success.
400 Bad request The request body is missing, cannot be parsed, or has missing or invalid content.
403 Forbidden The API key specified does not have permission to access the requested data.
405 Method not allowed An unsupported request method (GET, PUT, etc) was used (when POST, for example, was expected).
500 Internal server error An unexpected error has occurred on the server.
503 Service unavailable Some part of the server infrastructure is overloaded, or unavailable.
API Methods

get-k-index

Requests the current K index from a specific location.

Request body

Fields
api_key
String
This is the API key assigned either when registering to use the API, or as subsequently advised.
Example: 3f723484-5188-475d-bd35-d969324a4926
options
Object
Options specifying the data required.
location
String
The location for which the K index data is required. Australian region, or an Australian region observing site: Alice Springs, Canberra, Cocos Island, Narrabri, Darwin, Hobart, Launceston, Learmonth, Melbourne, Norfolk Island, Perth, Sydney, Townsville, or an Antartic region observing site: Casey, Davis, Macquarie Island, Mawson.
Example: Hobart

Response body

Fields
data
[Object]
If the request succeeds, an array of the requested data. By default, there will be one array element, representing the latest data. An empty array indicates that no data is available.
valid_time
String
The start of the 3-hour period to which the K index pertains. All times are in UTC.
Example: 2015-02-27 15:00:00
analysis_time
String
The time at the K index calculation was made. All times are in UTC.
Example: 2015-02-27 16:24:05
value
Number
The K index value: an integer from 0 to 9.
Example: 4
errors
If the request fails, the reason(s) will be indicated (where possible), by including this field in the reponse body (in addition to using an HTTP status indicating failure).

Examples

Successful request

This is an example of a successful request for the latest K index data for Hobart. The valid_time field indicates that the index value pertains to the 3-hour period starting 2015-02-27 15:00:00 and was calculated at the analysis_time of 2015-02-27 16:24:05. All times are in UTC.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-k-index

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926",
      "options": {
          "location": "Hobart"
      }
  }

  HTTP status: 200

  Response body
  {
      "data": [
          {
              "valid_time": "2015-02-27 15:00:00",
              "analysis_time": "2015-02-27 16:24:05",
              "value": 4
          },
      ]
  }
  
Unsuccessful request

This is an example of an unsuccessful request for K index data. It fails because the requested location is not supported.

The HTTP status code is 400 (Bad Request). The response body indicates the reason for the failure.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-k-index

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926",
      "options": {
          "location": "fantasy-land"
      }
  }

  HTTP status: 400

  Response body
  {
      "errors": [
          {
              "message": "Unsupported option value: location=fantasy-land",
              "code": 43
          }
      ]
  }
  

get-mag-alert

Requests details of any magnetic alert current for the Australian region.

Request body

Fields
api_key
String
This is the API key assigned either when registering to use the API, or as subsequently advised.
Example: 3f723484-5188-475d-bd35-d969324a4926

Response body

Fields
data
[Object]
If the request succeeds, an array of the requested data. By default, there will be one array element, representing the current magnetic alert. An empty array indicates that no magnetic alert is current.
start_time
String
The time at which the alert became active. All times are in UTC.
Example: 2015-01-07 08:45:00
valid_until
String
The time until which the alert is valid. All times are in UTC.
Example: 2015-01-07 20:45:00
g_scale
Number
The level of the alert, according to the NOAA Geomagnetic Storm scale (G1-G5).
Example: 1
description
String
The level of the alert. One of: minor, major, severe.
Example: minor
errors
If the request fails, the reason(s) will be indicated (where possible), by including this field in the reponse body (in addition to using an HTTP status indicating failure).

Examples

Alert is current

This is a successful request for details of any magnetic alert current for the Australian region.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-mag-alert

  HTTP status: 200

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  Response body
  {
      "data": [
          {
              "start_time": "2015-02-07 08:45:",
              "valid_until": "2015-02-07 20:45:00",
              "g_scale": 1,
              "description": "minor"
          }
      ]
  }
  
No alert current

If no alert is current, the returned data array will be empty.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-mag-alert

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  HTTP status: 200

  Response body
  {
      "data": []
  }
  

get-mag-warning

Requests details of any geophysical warning currently active for the Australian region.

Request body

Fields
api_key
String
This is the API key assigned either when registering to use the API, or as subsequently advised.
Example: 3f723484-5188-475d-bd35-d969324a4926

Response body

Fields
data
[Object]
If the request succeeds, an array of the requested data. By default, there will be one array element, representing the current geophysical warning. An empty array indicates that no geophysical warning is current.
issue_time
String
The time at which the warning was issued. All times are in UTC.
Example: 2015-03-01 23:18:00
start_date
String
The first day to which the warning applies. All dates are in UTC.
Example: 2015-03-02
end_date
String
The last day to which the warning applies. All dates are in UTC.
Example: 2015-03-03
cause
String
The cause, if known, of the expected geomagnetic activity. One of: coronal hole, coronal mass ejection, disappearing filament, flare.
Example: coronal hole
activity
[Object]
Forecast geomagnetic activity levels for each day of the warning period.
date
String
A date in the warning period. All dates are in UTC.
Example: 2015-03-02
forecast
String
The forecast activity level for that date.
Example: Unsettled to minor storm
comments
String
Comments, if any, provided by the duty forecaster.
Example: The effect of the high speed solar wind stream from a coronal hole may keep the geomagnetic activity enhanced to unsettled to active levels on 2 and 3 March with the possibility of some minor storm periods on these days.
errors
If the request fails, the reason(s) will be indicated (where possible), by including this field in the reponse body (in addition to using an HTTP status indicating failure).

Examples

Warning is current

This is a successful request for the details of the current geophysical warning for the Australian region.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-mag-warning

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  HTTP status: 200

  Response body
  {
      "data": [
          {
              "issue_time": "2015-03-01 23:18:00",
              "start_date": "2015-03-02",
              "end_date": "2015-03-03",
              "cause": "coronal hole",
              "activity": [
                  { "date": "2015-03-02", "forecast": "Unsettled to minor storm" },
                  { "date": "2015-03-03", "forecast": "Unsettled to minor storm" }
              ],
              "comments": "The effect of the high speed solar wind stream from a coronal hole may keep the geomagnetic activity enhanced to unsettled to active levels on 2 and 3 March with the possibility of some minor storm periods on these days."
          }
      ]
  }
  
No warning current

If no warning is current, the returned data array will be empty.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-mag-warning

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  HTTP status: 200

  Response body
  {
      "data": []
  }
  

get-aurora-alert

Requests details of any aurora alert current for the Australian region. Aurora alerts are used to report geomagnetic activity currently in progress and favourable for auroras.

Request body

Fields
api_key
String
This is the API key assigned either when registering to use the API, or as subsequently advised.
Example: 3f723484-5188-475d-bd35-d969324a4926

Response body

Fields
data
[Object]
If the request succeeds, an array of the requested data. By default, there will be one array element, representing the current aurora alert. An empty array indicates that no aurora alert is current.
start_time
String
The time at which the alert became active. All times are in UTC.
Example: 2015-01-07 08:45:00
valid_until
String
The time until which the alert is valid. All times are in UTC.
Example: 2015-01-07 20:45:00
k_aus
Number
The level of the alert, according to the Australian region K index (0-9).
Example: 6
lat_band
String
The latitude band from which auroral activity is likely to be visible, based on the value of k_aus. One of: high, mid, low, equatorial.
Example: high
description
String
A description of the alert, based on the value of k_aus.
Example: Geomagnetic storm in progress. Aurora may be observed during local night time hours in good observing conditions at high latitudes.
errors
If the request fails, the reason(s) will be indicated (where possible), by including this field in the reponse body (in addition to using an HTTP status indicating failure).

Examples

Alert is current

This is a successful request for details of any aurora alert current for the Australian region.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-aurora-alert

  HTTP status: 200

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  Response body
  {
      "data": [
          {
              "start_time": "2015-02-07 08:45:",
              "valid_until": "2015-02-07 20:45:00",
              "k_aus": 6,
              "lat_band": "high"
              "description": "Geomagnetic storm in progress. Aurora may be observed during local night time hours in good observing conditions at high latitudes."
          }
      ]
  }
  
No alert current

If no alert is current, the returned data array will be empty.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-aurora-alert

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  HTTP status: 200

  Response body
  {
      "data": []
  }
  

get-aurora-watch

Requests details of any aurora watch current for the Australian region. Aurora watches are used to warn of likely auroral activity in the next 48 hours.

Request body

Fields
api_key
String
This is the API key assigned either when registering to use the API, or as subsequently advised.
Example: 3f723484-5188-475d-bd35-d969324a4926

Response body

Fields
data
[Object]
If the request succeeds, an array of the requested data. By default, there will be one array element, representing the current aurora watch. An empty array indicates that no aurora watch is current.
issue_time
String
The time at which the watch was issued. All times are in UTC.
Example: 2015-01-06 23:18:00
start_date
String
The first day to which the watch applies. All dates are in UTC.
Example: 2015-01-07
end_date
String
The last day to which the watch applies. All dates are in UTC.
Example: 2015-01-08
cause
String
The dominant cause of the likely auroral activity. One of: coronal hole, coronal mass ejection.
Example: coronal hole
k_aus
Number
The expected level of the auroral activity, according to the Australian region K index (0-9).
Example: 6
lat_band
String
The latitude band from which auroral activity is likely to be visible, based on the value of k_aus. One of: high, mid, low, equatorial.
Example: high
comments
String
Comments provided by the duty forecaster.
Example: Effects of a coronal hole are expected to impact the Earth within the next 48 hours, possibly resulting in significant geomagnetic activity and visible auroras during local nighttime hours. Aurora alerts will follow if significant geomagnetic activity actually occurs.
errors
If the request fails, the reason(s) will be indicated (where possible), by including this field in the reponse body (in addition to using an HTTP status indicating failure).

Examples

Watch is current

This is a successful request for details of any aurora watch current for the Australian region.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-aurora-watch

  HTTP status: 200

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  Response body
  {
      "data": [
          {
              "issue_time": "2015-01-06 23:18:00",
              "start_date": "2015-01-07",
              "end_date": "2015-01-08",
              "cause": "coronal hole",
              "k_aus": 6,
              "lat_band": "high",
              "comments": "Effects of a coronal hole are expected to impact the Earth within the next 48 hours, possibly resulting in significant geomagnetic activity and visible auroras during local nighttime hours. Aurora alerts will follow if significant geomagnetic activity actually occurs."
          }
      ]
  }
  
No watch current

If no aurora watch is current, the returned data array will be empty.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-aurora-watch

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  HTTP status: 200

  Response body
  {
      "data": []
  }
  

get-aurora-outlook

Requests details of any aurora outlook current for the Australian region. Aurora outlooks are used to warn of likely auroral activity 3-7 days hence.

Request body

Fields
api_key
String
This is the API key assigned either when registering to use the API, or as subsequently advised.
Example: 3f723484-5188-475d-bd35-d969324a4926

Response body

Fields
data
[Object]
If the request succeeds, an array of the requested data. By default, there will be one array element, representing the current aurora outlook. An empty array indicates that no aurora outlook is current.
issue_time
String
The time at which the outlook was issued. All times are in UTC.
Example: 2015-01-12 23:18:00
start_date
String
The first day to which the outlook applies. All dates are in UTC.
Example: 2015-01-15
end_date
String
The last day to which the outlook applies. All dates are in UTC.
Example: 2015-01-17
cause
String
The dominant cause of the likely auroral activity. One of: coronal hole, coronal mass ejection.
Example: coronal mass ejection
k_aus
Number
If available, the expected level of the auroral activity, according to the Australian region K index (0-9).
Example: 7
lat_band
String
If available, the latitude band from which auroral activity is likely to be visible, based on the value of k_aus. One of: high, mid, low, equatorial.
Example: mid
comments
String
Comments provided by the duty forecaster.
Example: A large active solar region is rotating into a position that is favourable for geoeffective coronal mass ejections (CMEs) and possible auroral activity. There is an increased chance of auroral activity during the period 3-7 days hence. Warnings and/or alerts will follow if a geoeffective CME is observed and/or significant geomagnetic activity actually occurs.
errors
If the request fails, the reason(s) will be indicated (where possible), by including this field in the reponse body (in addition to using an HTTP status indicating failure).

Examples

Outlook is current

This is a successful request for details of any aurora outlook current for the Australian region.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-aurora-outlook

  HTTP status: 200

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  Response body
  {
      "data": [
          {
              "issue_time": "2015-01-12 23:18:00",
              "start_date": "2015-01-15",
              "end_date": "2015-01-17",
              "cause": "coronal mass ejection",
              "k_aus": 7,
              "lat_band": "mid",
              "comments": "A large active solar region is rotating into a position that is favourable for geoeffective coronal mass ejections (CMEs) and possible auroral activity. There is an increased chance of auroral activity during the period 3-7 days hence. Warnings and/or alerts will follow if a geoeffective CME is observed and/or significant geomagnetic activity actually occurs."
          }
      ]
  }
  
No outlook current

If no aurora outlook is current, the returned data array will be empty.

  POST http://sws-data.sws.bom.gov.au/api/v1/get-aurora-outlook

  Request body
  {
      "api_key": "3f723484-5188-475d-bd35-d969324a4926"
  }

  HTTP status: 200

  Response body
  {
      "data": []
  }
  
Types

ResponseError

An array of these is included (where possible) in the reponse, if errors have occurred.

Used in: get-k-index, get-mag-alert, get-mag-warning. get-aurora-alert. get-aurora-watch. get-aurora-outlook.

Fields

code
Number
A code indicating the reason for failure. See the table of error codes.
Example: 43
message
String
A message indicating a reason for failure.
Example: Unsupported option value: location=fantasy-land