This API provides access to near real-time Australian Space Weather Forecasting Centre 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.
Each API method URL includes the prefix:
https://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 use JSON. The character encoding is UTF-8.
All dates and times are in UTC, using the following formats. Times use a 24-hour clock.
Examples of successful and unsuccessful requests are included with the API method descriptions below. For more examples, please see the demo and examples pages.
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.)
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. |
Requests the most recent A index for the Australian region, or historical values.
|
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.
|
||||||
|
|||||||
|
data
[Object]
|
If the request succeeds, an array of the requested data (ordered by valid_time, with corresponding data for the most recent analysis_time). If neither start nor end is specified, there will be one array element with the latest data (if sufficiently recent). An empty array indicates that the requested data is not available. Large historical data responses are limited to 10,000 elements; responses are truncated, with following items just omitted. |
||||
|
|||||
|
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).
|
||||
This is an example of a successful request for the latest A index data for the Australian region. The valid_time field indicates that the index value pertains to the day starting 2021-12-12 00:00:00. All times are in UTC.
POST https://sws-data.sws.bom.gov.au/api/v1/get-a-index
Request body
{
"api_key": "3f723484-5188-475d-bd35-d969324a4926",
"options": {
"location": "Australian region"
}
}
HTTP status: 200
Response body
{
"data": [
{
"valid_time": "2021-12-12 00:00:00",
"index": 3
},
]
}
This is an example of a successful request for historical A index data for the Australian region.
POST https://sws-data.sws.bom.gov.au/api/v1/get-a-index
Request body
{
"api_key": "3f723484-5188-475d-bd35-d969324a4926",
"options": {
"location": "Australian region",
"start": "2021-12-04 00:00:00",
"end": "2021-12-07 00:00:00"
}
}
HTTP status: 200
Response body
{
"data": [
{
"index": 5,
"valid_time": "2021-12-04 00:00:00"
},
{
"index": 6,
"valid_time": "2021-12-05 00:00:00"
},
{
"index": 6,
"valid_time": "2021-12-06 00:00:00"
}
]
}
This is an example of an unsuccessful request for A 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 https://sws-data.sws.bom.gov.au/api/v1/get-a-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
}
]
}
Requests the most recent K index from a specific location, or historical values.
|
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.
|
||||||
|
|||||||
|
data
[Object]
|
If the request succeeds, an array of the requested data (ordered by valid_time, with corresponding data for the most recent analysis_time). If neither start nor end is specified, there will be one array element with the latest data (if sufficiently recent). An empty array indicates that the requested data is not available. Large historical data responses are limited to 10,000 elements; responses are truncated, with following items just omitted. |
||||||
|
|||||||
|
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).
|
||||||
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 https://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",
"index": 4
},
]
}
This is an example of a successful request for historical K index data for Hobart.
POST https://sws-data.sws.bom.gov.au/api/v1/get-k-index
Request body
{
"api_key": "3f723484-5188-475d-bd35-d969324a4926",
"options": {
"location": "Hobart",
"start": "2021-11-21 00:00:00",
"end": "2021-11-22 00:00:00"
}
}
HTTP status: 200
Response body
{
"data": [
{
"index": 2,
"valid_time": "2021-11-21 00:00:00",
"analysis_time": "2021-11-22 00:07:36"
},
{
"index": 2,
"valid_time": "2021-11-21 03:00:00",
"analysis_time": "2021-11-22 00:07:36"
},
...
{
"index": 1,
"valid_time": "2021-11-21 18:00:00",
"analysis_time": "2021-11-22 00:07:36"
},
{
"index": 2,
"valid_time": "2021-11-21 21:00:00",
"analysis_time": "2021-11-22 00:07:36"
}
]
}
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 https://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
}
]
}
Requests the most recent Dst index for the Australian region, or historical values.
|
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.
|
||||||
|
|||||||
|
data
[Object]
|
If the request succeeds, an array of the requested data (ordered by valid_time). If neither start nor end is specified, there will be one array element with the latest data (if sufficiently recent). An empty array indicates that the requested data is not available. Large historical data responses are limited to 10,000 elements; responses are truncated, with following items just omitted. |
||||
|
|||||
|
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).
|
||||
This is an example of a successful request for the latest Dst index data for the Australian region. The valid_time field indicates that the index value was observed at 2016-10-24 15:10:00. All times are in UTC.
POST https://sws-data.sws.bom.gov.au/api/v1/get-dst-index
Request body
{
"api_key": "3f723484-5188-475d-bd35-d969324a4926",
"options": {
"location": "Australian region"
}
}
HTTP status: 200
Response body
{
"data": [
{
"valid_time": "2015-11-30 13:05:00",
"index": -44
},
]
}
This is an example of a successful request for the historical Dst index data for the Australian region.
POST https://sws-data.sws.bom.gov.au/api/v1/get-dst-index
Request body
{
"api_key": "3f723484-5188-475d-bd35-d969324a4926",
"options": {
"location": "Australian region",
"start": "2021-11-21 00:00:00",
"end": "2021-11-22 00:00:00"
}
}
HTTP status: 200
Response body
{
"data": [
{
"index": "6",
"valid_time": "2021-11-21 00:05:00"
},
{
"index": "3",
"valid_time": "2021-11-21 00:15:00"
},
{
"index": "4",
"valid_time": "2021-11-21 00:25:00"
},
...
{
"index": "-5",
"valid_time": "2021-11-21 23:35:00"
},
{
"index": "-9",
"valid_time": "2021-11-21 23:45:00"
},
{
"index": "-7",
"valid_time": "2021-11-21 23:55:00"
}
]
}
This is an example of an unsuccessful request for Dst 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 https://sws-data.sws.bom.gov.au/api/v1/get-dst-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
}
]
}
Requests details of any magnetic alert current for the Australian region.
|
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
|
|
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.
|
||||||||
|
|||||||||
|
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).
|
||||||||
This is a successful request for details of any magnetic alert current for the Australian region.
POST https://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"
}
]
}
If no alert is current, the returned data array will be empty.
POST https://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": []
}
Requests details of any geophysical warning currently active for the Australian region.
|
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
|
|
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.
|
||||||||||||||||||
|
|||||||||||||||||||
|
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).
|
||||||||||||||||||
This is a successful request for the details of the current geophysical warning for the Australian region.
POST https://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."
}
]
}
If no warning is current, the returned data array will be empty.
POST https://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": []
}
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.
|
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
|
|
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.
|
||||||||||
|
|||||||||||
|
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).
|
||||||||||
This is a successful request for details of any aurora alert current for the Australian region.
POST https://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."
}
]
}
If no alert is current, the returned data array will be empty.
POST https://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": []
}
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.
|
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
|
|
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.
|
||||||||||||||
|
|||||||||||||||
|
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).
|
||||||||||||||
This is a successful request for details of any aurora watch current for the Australian region.
POST https://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."
}
]
}
If no aurora watch is current, the returned data array will be empty.
POST https://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": []
}
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.
|
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
|
|
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.
|
||||||||||||||
|
|||||||||||||||
|
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).
|
||||||||||||||
This is a successful request for details of any aurora outlook current for the Australian region.
POST https://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."
}
]
}
If no aurora outlook is current, the returned data array will be empty.
POST https://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": []
}
An array of these is included (where possible) in the response, if errors have occurred.
Used in: get-a-index, get-k-index, get-dst-index, get-mag-alert, get-mag-warning, get-aurora-alert, get-aurora-watch, get-aurora-outlook .
|
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
|