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.
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
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,
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.
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.