Proposal for a Simple Time-range Access Protocol (STAP)

Version 0.1 Working Draft 2007 August 2

Working Group: n/a

Author(s): SilviaDalla, KevinBenson

Abstract

We propose a Simple Time-range Access Protocol (STAP) for accessing data from archives in which the main coordinate identifying data is time. This proposal arises from the need to provide simple access to a variety of Solar System datasets. The proposed protocol is modelled upon the Simple Image Access Protocol (SIAP) specification. A query defining the time range of interest is constructed to search for data. The STAP service returns a VOTable listing data available in the time range. The protocol is intended for both time-series data and images: if only data of a specified format is required, this can be specified in the query using the FORMAT parameter.

Status of this Document

This is an IVOA Working Draft for review by IVOA members and other interested parties.

A list of current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.

Acknowledgments

Introduction

The Simple Image Access Protocol (SIAP) is a very useful means for querying repositories of Astronomical images and allowing image retrieval. This protocol has POS and SIZE (POS = ra, dec ; SIZE = size of the search box) as mandatory parameters for the query.

A variety of Solar System datasets exist and are being integrated into the Virtual Observatory. SIAP is however not suitable for Solar System observations. In Solar System datasets, the most important coordinate is time.

Solar System datasets typically include images, for example solar images, and time series, for example measurements of the interplanetary magnetic field taken by a spacecraft.

The protocol we propose is for simple access to data, and does not attempt to capture the complexity and wide variety of data products and their metadata that characterise Solar System datasets. The SPASE data model is currently being developed with that objective.

The implementation of the protocol is URL based.

Parameters

Mandatory parameters

A STAP service MUST support the following parameters: (Note that parameter names are shown in uppercase in this document for clarity, but should be case insensitive).

START = start time of the interval. This should be specified in IS0-8601 format, eg. '2006-02-08T00:00:00'. Times are expressed in UTC. Although this is not a particularly astronomy-friendly time format, it is typically the one used to time-stamp data in archives.

END = end time of the interval, in the same format as START.

FORMAT = the desired format of the data. The value is a comma-delimited list, where each element can be either a recognised MIME type (eg "image/fits"), or one of the following special values: "ALL" -- to indicate that any format is ok; "GRAPHIC" -- to restrict the search to FITS images, JPEG, PNG, GIF formats; "GRAPHIC-FITS" for FITS images; "TIME_SERIES", to restrict the search to time series data. Allowed formats for time series are: "TIME_SERIES-ASCII", "TIME_SERIES-CDF", "TIME_SERIES-VOT". In cases where no FORMAT is specified in the STAP request, "ALL" will be assumed.

Optional parameters

A STAP service MAY support the following optional parameters:

INSTRUMENT_ID = ID of instrument to be retrieved. A query that sets this parameter and not the DATA_ID (see below) will return all data products found for the required instrument. Examples of INSTRUMENT_ID strings are: SOHO_EIT, Ulysses_MAG etc. It is recommended that matching of instrument IDs by services should be case insensitive.

DATA_ID = ID of data product to be retrieved. This identifies a data product for a particular instrument (that is it describes the instrument AND the specific data product required).

TIME_RESOLUTION = for time series data, the resolution at which data are required. The way in which time resolution is specified needs to be agreed upon. Within the SPASE data model, developed to describe space physics data, time resolutions are expressed as eg '00:01:00' for 1 minute resolution, but this seems hardly general enough.

POS = position ra, dec. This and the next parameter aim at allowing usage of this protocol also for astronomy objects for which time is an important coordinate.

SIZE = size of search box around POS

BAND = for data that has wavelength information, for example solar images, this parameter can be used to constrain the wavelength range. The syntax for specifying the wavelength range should be the same as for the IVOA SSAP. Wavelengths are specified in meters and a wavelength band is described as follows: BAND=1.7E-8/1.8E-8

Querying a STAP service

The query input is transmitted as an HTTP GET request represented by a URL with two parts:

• A base URL of the form:

  http://server-address/path?[extra GET arg &[...]]

  • Examples:

    http://www.solarimg.org/cgi-bin/VOstapq?

    http://www.mytimeseries.org/VOstapquery?resolv&mission=ace& 

Note that when it contains extra GET arguments, the base URL ends in an ampersand, &; if there are no extra arguments, then it ends in a question mark, ?.

Every query to a given STAP service uses the same base URL.

• Constraints expressed as a list of ampersand-delimited GET arguments, each of the form:

  name=value 

• • Examples: START=2005-07-28T00:00:00&END=2005-07-28T12:00:00

The constraints represent the query parameters which can vary for each successive query.

The baseURL and constraint list are concatenated to form the query.

• • Example: http://www.solarimg.org/cgi-bin/VOstapq?START=2005-07-28T00:00:00&END=2005-07-28T12:00:00&FORMAT=GRAPHIC-FITS

Output of a STAP query

The data archive receives a STAP request and returns a Votable describing data files that match the query. This Votable can have multiple TABLE elements, to allow for results from several instruments on the same mission to be returned within a single votable.

The RESOURCE element in the Votable SHOULD contain an INFO with name="QUERY_STATUS". Its value attribute should set to "OK" if the query executed successfully, regardless of whether any matching files were found.

Each table row represents a different data file available.

The Votable MUST contain the following fields (all strings of datatype="char", arraysize="*"):

Suggested name of VOT field	UCD (mandatory)	Description	Comments
"PROVIDER"	'meta.curation'	The archive (STAP service) providing the data
"DATA_ID"	'meta.title'	Short description of the measurement	Eg: 'ACE Solar Wind Experiment 5-Minute Key Parameters [PRELIM]'
"INSTRUMENT_ID"	'INST_ID'	A string specifiying the mission and instrument	Eg: 'ACE_SWE' for ACE/SWEPAM
"TIME_START"	'time.obs.start'	Start time of data in the file	In UTC
"TIME_END"	'time.obs.end'	End time of data in the file	In UTC
"ACCESS_URL"	'VOX:AccessReference'	Url pointing to data file	See example URLs below
"FORMAT"	'VOX:Format'	Format of the data file	This is to allow discriminating between time series and images
"DESCRIPTION"	'meta'	A string containing supplemental information on the data file
"DESCRIPTION_URL"	'meta.ref.url'	A URL pointing to information on the data product	Typically a web site for the specific instrument

Notes:

• DESCRIPTION_URL = This is different from the reference URL of the data archive (STAP service) supplying the data, as specified in the registry.
• The DESCRIPTION item is intended to provide a free format string containing the most essential metadata for the file. For solar images, it should contain the wavelength of the measurements. For time series data, a brief description of the data product and time resolution. We do not want to prescribe a strict format for how the metadata should be specified, to be able to accomodate different Solar System data products.
• Since the ACCESS_URL will often contain metacharacters the URL is normally enclosed in an XML CDATA section (<![CDATA[...]]>) or otherwise encoded to escape any embedded metacharacters.

Examples:

<![CDATA[http://www.solarimg.org/cgi-bin/extract?img=2se22eesx3.fts]]> <![CDATA[http://www.mytimeseries.org/cgi-bin/extract?timeseries=acemag0233.cdf]]>

Optional fields for the Votable output of a STAP query are as follows (all strings of datatype="char", arraysize="*"):

Suggested name of VOT field	UCD (mandatory)	Description	Comments
"RA"	'pos.eq.ra'	Right Ascension
"DEC"	'pos.eq.dec'	Declination

Appendix A: ...

If you have an appendix, put content here

References