API v0.2

Introduction

The v0.2 API is provided in XML format only. The elements used in the XML documents, their attributes, and permitted child elements or contents are defined by a document type definition (DTD). The DTD is located at http://aurorawatch-api.lancs.ac.uk/0.2/aurorawatch-api.dtd.

The API provides the current status and the activity values from the past 24 hours for each site in use. Alerts are generated from only one site (the “alerting site”). In the case of data loss the alerting site is automatically changed to another operational site. The API also provides various metadata about AuroraWatch UK alerts, such as projects and sites used (providing metadata such as location name, geographic coordinates, attribution, copyright), and alert levels (providing descriptions, colours).

HTTPS

The API is available with either HTTP or HTTPS protocols. Currently we are outputting HTTP links in the XML documents. If your application uses HTTPS then you must rewrite the links. In the future we may reverse the situation so all users should rewrite the links to match their desired protocol.

Project and site meta data

The project and site metadata are essentially static and are served with long expiry times (typically 10 days). Use the expiry time as an indication of how long an application may cache this information.

Project list

The project list, (http://aurorawatch-api.lancs.ac.uk/0.2/project-list.xml) indicates the projects included in the AuroraWatch UK API. For brevity the site information of each project is omitted.

Project information

The project information (e.g., http://aurorawatch-api.lancs.ac.uk/0.2/project/samnet.xml) provides the complete metadata about a single project, including information for all of its supported sites. Note that the project may contain other sites for which the data is not available from this API. If that is the case the other sites will not be listed.

For more information about the project-specific elements see the project list section above. For information about sites-specific elements see the site information secxtion below.

Site information

The information for just a single site (e.g., http://aurorawatch-api.lancs.ac.uk/0.2/project/samnet/crk2.xml) is also available. The information given is therefore a subset of that for all sites.

Status descriptions

The descriptions of the status levels (e.g., http://aurorawatch-api.lancs.ac.uk/0.2/status-descriptions.xml) provide metadata about possible status values. The descriptions are essentially static and is served with a long expiry time.

Activity data

The activity and status level information is updated frequently, typically every 3 minutes. The files should be cached for short periods only, use the expiry time as an indication of how long an application may cache this information.

Site activity

Recent geomagnetic activity for a single site. This includes the lower thresholds for the specific site. Note that the thresholds may vary between sites and may be adjusted in future.

Current status

Current status for all sites. This file only provides the alert status for each site, combining or comparing activity levels between sites is not meaningful. This file indicates the “alerting site” to be used for alerts, i.e., the one that AuroraWatch UK will use to issue alerts via social media and email. For operational reasons this site can change automatically.

Descriptions of the elements used

abbreviation: The abbreviation used to identify a project or site, context is given by its parent element. Project abbreviations are unique within the AuroraWatch UK API, site abbreviations may not be. The abbreviation should normally be printed in upper-case, for URLs the lower case form may be used.
activity: AuroraWatch UK hourly activity. The mandatory status_id attribute refers to the status ID and indicates the status level (green, yellow, amber or red). Child elements indicate the date and time of the start of the hour, and also the activity value.
altitude: The altitude of a site, in metres. May not be present.
attribution: The data attribution to be used for data a specific site. The mandatory lang attribute indicates the language.
color: RGB color code, in hex, and of the form #RRGGBB where RR, GG and BB are the 16 bit red, green and blue values respectively.
copyright: The copyright declation for data originating from a specific site. The mandatory lang attribute indicates the language.
current_status: Contains the current site_status values for all operational, supported sites.
data_type: A distinct type of data from a given site. The id attribute is a unique ID by which the data type can be referenced. The child description element provides a human-readable description.
datetime: The date and time, given in Coordinated Universal Time (UTC). The format is always <YYYY>-<MM>-<DD>T<hh><mm><ss>+0000 where <YYYY> is the four-digit year, <MM> the two digit month, <DD> the two-digit day of month, <hh> the two-digit hour of day (24 hour clock), <mm> the two-digit minutes and <ss> the number of seconds, also as two digits. The parent element indicates the context.
description: The description for a project, site, data type or message. The mandatory lang attribute indicates the language used for the description. Multiple descriptions (for multiple languages) could be present.
end_datetime: The exclusive end date and time.
expires: Message expiry date and time. After this time the message should not be shown and any information about it may be discarded to recover the memory used.
latitude: Geographic latitude as degrees and fractional degrees, North is positive.
license: License information for data. The mandatory lang attribute indicates the language.
location: Standard name for a site location.
longitude: Geographic longitude as degrees and fractional degrees, East is positive.
lower_threshold: The lower threshold of an AuroraWatch UK status level. The mandatory status_id attribute indicates the name by which the status level is known (green, yellow, amber or red).
meaning: The meaning or interpretation for a given status level. The mandatory lang attribute indicates the language.
message: A message containing information to be passed onto a user. The mandatory and unique id attribute provides an ID by which the message can be referred to. The id can be used to distinguish between read and unread messages. The mandatory priority attribute indicates the priority of a message: high is used for messages for which a foreground notification or alert is appropriate (e.g., “Aurora now being seen from Scotland.“), low is used for messages which are relevant but not urgent (e.g., “The website will not be available on 1st May due to software upgrades”). The test priority is for system and developer testing, production apps should not display test messages to users.
name: The non-abbreviated name of a project.
project: A supported project. Data from different organisations are arranged into different projects. Within a project site names and abbreviations must be unique, the project hierarchy enables sites with the same name or abbreviation to be identified. The mandatory id attribute defines a unique identifier for the project element. The url attribute (not to be confused with the url element) provides the API URL from which the full project information, including site details, can be obtained. The default attribute, if present, indicates that this project should be taken as the default for display or other user selection.
project_list: Parent element for a list fo projects.
start_datetime: The inclusive start date and time.
site: The location at which a magnetometer is sited. The mandatory id attribute defines a unique identifier for the site element. The url attribute (not to be confused with the url element) provides the API URL from which the full site information can be obtained. The default attribute, if present, indicates that this site should be taken as the default for display or other user selection.
site_activity: A container for activity values for a specific site. The project_id and site_id attributes refer to the project and site IDs. The site_url attribute provides the API URL from which the full site information can be obtained.
site_status: The current status level for a specific site. The project_id and site_id attributes refer to the project and site IDs. The site_url attribute provides the API URL from which the full site information can be obtained. The status_id refers to the status ID.
status: Containder for a specific activity status. The child elements provide the description, meaning and RGB color values.
summary_plot: Container for summary plot information.
Updated: Date and time when last updated.
url: A URL from which the user can obtain more information about the project.
url_fstr: A URL format string. The string should be treated as a strftime format string which should be expanded with the appropriate date and time. The mandatory type attribute indicates whether this is a daily summary plot (daily) (starting and ending at UTC midnight) or a rolling 24 hour plot (rolling).
value: AuroraWatch UK activity value. The activity value, expressed in nanotesla (nT) is the maximum hourly disturbance, or the maximum hourly range (whichever is larger) of the horizontal components of the magnetic field.

Notes for language pedants

The use of American English spelling for colour (color) is unfortunately almost unavoidable in most computer programming languages. To avoid further confusion we have deliberately chosen the American spelling.

Using our site | Privacy & Cookies | About us

In production use