API info

Conditions of use

Use of the API is restricted to non-commercial purposes. Use in paid-for or ad-supported applications is not permitted at this time.

Please do not describe your app as an “official” AuroraWatch UK app. This term is reserved for apps which have been (or may be) commisioned by AuroraWatch UK. If you wish to use the term “in association with AuroraWatch UK” please contact us for prior approval.

The app or its web site must not imply that the app or web site is endorsed by AuroraWatch UK.

Name and acknowledgements

The name of the site is “AuroraWatch UK” and our official URL is http://aurorawatch.lancs.ac.uk/.

The data used by AuroraWatch UK has specific data acknowledgement requirements which should be made available to the user, and which should reflect the data source in use at that time. In addition, it must be made clear that the alert status is generated by AuroraWatch UK, ideally with a link or button which enables the user to visit the AuroraWatch UK web site.

AuroraWatch UK logo

You may use the AuroraWatch UK logo to indicate that the app uses data from AuroraWatch UK. The normal logo features green arcs with the text “AuroraWatch UK” below. We have a version with black text for use on light backgrounds and an inverted version with white text for use on dark backgrounds. Condensed, square versions with the text “AW UK” are available for avatars and where space is limited (e.g., Twitter feeds). Logos of any reasonable size can be generated from the SVG master. Contact us for details.

Client identification

We wish to be able to identify all apps which use the API. For public web applications the HTTP Referer header is sufficient; thus clients can use XMLHttpRequest directly to access the API. For smartphone apps please set the HTTP User-Agent header to match the name of your app, or if that is not possible then set the Referer to the public page associated with your app. In case of difficulties we can arrange for an alternative URL which is used just by your app.

Interval between requests

If each client contacts the AuroraWatch UK server individually please ensure the interval between requests is 3 minutes or longer. If you are using push notifications and are pulling the data to a central server to support many clients then you may make one request per minute.

Project and site naming conventions

Within the API (and also the Python auroraplot processing library) we refer to sites firstly by a project abbreviation, and then by the site abbreviation. All supported projects must have a unique abbreviation. Within a given project all sites must be identified by a unique abbreviation. However, there is no requirement that site abbreviations are unique across all projects. It is therefore essential that users of the API refer to sites firstly by project and then by site. We use the convention of writing the project and site abbreviations in upper case, separating them with a (forward) slash, e.g., SAMNET/CRK2.

Definition of alerts levels and colours

Our alerts are colour-coded, please ensure you use the correct colour and name when displaying the alert status. Do not adjust the thresholds, status information should be consistent across all platforms and applications.

API details

We maintain a current version of the API and one or more legacy versions. New applications should use the most recent API version. Older versions are subject to removal, see the relevant page for the date when we intend to completely remove a given version.

The following API versions are available:

Version 0.1
Legacy version which we intend to remove; a removal date has not been decided. It lacks the metadata needed to properly acknowledge the data source(s) and other new features such as messages.
Version 0.2.x
This is our current version. It makes available all appropriate metadata for each site and is used by ourselves for the site plots and iframe content.
Version 0.3
This is our development version. It follows almost the same format as the v0.2 API but adds information about stack plots, and later will include the location of the activity and status files.
Using our site | Privacy & Cookies | Contact us