EditAttachPrintable
r6 - 19 Sep 2007 - 08:07:11 - PhillipWarnerYou are here: TWiki >  Astrogrid Web  > SimpleEventAccessProtocol

Simple Event Access Protocol (SEAP)

Version 0.2 Working Draft 2007 September 19

Working Group: IVOA VOEvent

Author(s): Matthew Graham, ElizabethAuden, PhillipWarner

Abstract

The Simple Event Access Protocol (SEAP) will provide a mechanism to query services containing VOEvent packets. SEAP will be analogous to the Simple Time-range Access Protocol (STAP) and Simple Image Access Protocol (SIAP). Currently, VOEvents are provided through RSS feeds published by organizations such as eSTAR and CalTech?. In addition, six VOEvent feeds have been wrapped in a STAP web service for a searchable event interface prototyped with VOExplorer.

The SEAP protocol should be able to incorporate astronomical, solar and STP events. Use cases include both users searching for event data through VOExplorer as well as telescope operators searching for followup events.

Status of this Document

This document is a working draft prompted by the VOEvent / Heterogeneous Telescope Network workshop in Tucson, Arizon during June 2007.

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

Acknowledgments

Table of Contents

Introduction

SEAP Metadata Model

The

Response Metadata
UTYPE Data Type Possible Values Default Value Status
seap:response.content string ivorn, full, custom ivorn MUST

Constraint Metadata
UTYPE Data Type Possible Values Default Value Status
seap:constraint.authorivorn string     MUST
seap:constraint.contactname string     MUST
seap:constraint.how string     MUST
seap:constraint.position.ra.start float     MUST
seap:constraint.position.ra.end float     MUST
seap:constraint.position.dec.start float     MUST
seap:constraint.position.dec.end float     MUST
seap:constraint.position.size float     MUST
seap:constraint.datetime.start ISO-8601 compliant (string)     MUST
seap:constraint.datetime.end ISO-8601 compliant (string)     MUST
seap:constraint.datetime.reference string isotime, pubtime   MUST
seap:constraint.param.name string     MUST
seap:constraint.param.min float     MUST
seap:constraint.param.max float     MUST
seap:constraint.param.unit string     MUST
seap:constraint.concept string     MUST
seap:constraint.citation.cited boolean true, false false MUST
seap:constriant.citation.role string followup, supersedes, retraction   MUST

Response Metadata

seap:response.content

Represents the supported content of the VOTable as the return data.

A fully compliant SEAP service must support this utype as a parameter.

This data type for this utype is a string.

Possible return values associated with this utype are as follows:

  • ivorn (default) - a VOTable of IVORNs ([[#IvoRn][]) for each VOEvent packet matchin the query
  • full - a VOTable of VOEvent packets
  • custom - a VOTable of selected VOEvent packet metadata * * (specification TBD)

Constraint (Query) Metadata

seap:constraint.authorivorn

Represents the IVORN (1) of the feed publisher from which the VOEvent packet originated. It is expected that the feed publisher has previously registered with the VO registry (ref?).

A fully compliant SEAP service must support this utype as a parameter.

The data type for this utype is a string, but must conform to the IVO Identifier specification (2).

seap:constraint.contactname

Represents the contact name, or subset thereof, of the person who created the VOEvent packet.

A fully compliant SEAP service must support this utype as a parameter.

The data type for this utype is a string.

seap:constraint.how

Represents how the observation that resulted in VOEvent publication was performed. The VOEvent ([[#VoEvent][2]) specification presents the "How" element as the instrument configuration.

A fully compliant SEAP service must support this utype as a parameter, and must include all sub-elements of "How" in the query execution.

seap:constraint.position

NOTE: Shall we support general spatial coordinates, i.e., maybe something like;

  • alpha - the 'x' coordinate; e.g., ra in equatorial coordinates
  • beta - the 'y' coordinate; e.g., dec in equatorial coordinates
  • gamma - the 'z' coordinate; e.g., z as redshift

Positional metadata must support range queries. The subtypes of this utype allow for range specification using the following:

  • specification of the center ra/dec position and a size
  • specification of the start and end ra/dec positions

seap:constraint.position.ra.center

Represents the center of the region to be queried, in hours of right ascension. This utype is used in conjunction with the following utypes:

The data type for this utype is a float.

The range of possible values is from 0.0 to 24.0.

seap:constraint.position.ra.start

Represents the starting position of the region to be queried, in hours of right ascension. This utype is used in conjunction with the following utypes:

A fully compliant SEAP service must support this utype as a parameter.

The data type for this utype is a float.

The range of possible values is from 0.0 to 24.0.

seap:constraint.position.ra.end

Represents the ending position of the region to be queried, in hours of right ascension. This utype is used in conjunction with the following utypes:

A fully compliant SEAP service must support this utype as a parameter.

The data type for this utype is a float.

The range of possible values are 0.0 to 24.0.

seap:constraint.position.dec.center

Represents the center of the region to be queried, in degrees of declination. This utype is used in conjunction with the following utypes:

The data type for this utype is a float.

The range of possible values is from -90.0 to +90.0.

seap:constraint.position.dec.start

Represents the starting position of the region to be queried, in degrees of declination. This utype is used in conjunction with the following utypes:

A fully compliant SEAP service must support this utype as a parameter.

The data type for this utype is a float.

The range of possible values is from -90.0 to +90.0.

seap:constraint.position.dec.end

Represents the starting position of the region to be queried, in degrees of declination. This utype is used in conjunction with the following utypes:

A fully compliant SEAP service must support this utype as a parameter.

The data type for this utype is a float.

The range of possible values is from -90.0 to +90.0.

seap:constraint.position.size

Represents the size of the region to be queried. This utype is used in conjunction with the following utypes:

seap:constraint.datetime.start

Represents the start date for searching. This utype is used in conjunction with:

and is further constrained by the value of the following utype:

A fully compliant SEAP service must support this utype as a parameter.

The data type of this utype if an ISO-8601 DateTime?.

seap:constraint.datetime.end

Represents the end date for searching. This utype is used in conjunction with:

and is further constrained by the value of the following utype:

A fully compliant SEAP service must support this utype as a parameter.

The data type of this utype if an ISO-8601 DateTime?.

seap:constraint.datetime.reference

Represents the DateTime? reference as detailed in the VOEvent standard 2.

A fully compliant SEAP service must support this utype as a parameter.

The data type of this utype is a string.

Possible values are:

  • isotime - (NOTE: need description)
  • pubtime - (NOTE: need description)

seap:constraint.param

Param names and values (repeating parameter group). If a param has been specified in the query and no events contain that param, do not return any events.

seap:constraint.param.name

Represents the name of a "Param" element specified in the VOEvent packet. This utype is used in conjunction with the following utypes:

A fully compliant SEAP service must support this utype as one or more parameters.

The data type for this utype is a string.

seap:constraint.param.min

Represents the minimum value of the matching "Param" element specified in the VOEvent packet. This utype is used in conjunction with the following utypes:

A fully compliant SEAP service must support this utype as one or more parameters.

The data type for this utype is a float.

seap:constraint.param.max

Represents the maximum value of the matching "Param" element specified in the VOEvent packet. This utype is used in conjunction with the following utypes:

A fully compliant SEAP service must support this utype as one or more parameters.

The data type for this utype is a float.

seap:constraint.param.unit

Represents the minimum value of the matching "Param" element specified in the VOEvent packet. This utype is used in conjunction with the following utypes:

A fully compliant SEAP service must support this utype as one or more parameters.

The data type for this utype is a string.

seap:constraint.concept

Represents the "Concept" element as specified in the VOEvent packet. A concept is represented by a utype from the standard vocabulary (ref?).

A fully compliant SEAP service must support this utype as one or more parameters.

The data type for this utype is a string.

seap:constraint.citation.cited

Represents whether the VOEvent packet has been cited.

A fully compliant SEAP service must support this utype as one or more parameters.

The data type for this utype is a boolean.

The default value is false.

seap:constriant.citation.role

Represents the role of any follow-up citation.

A fully compliant SEAP service must support this utype as one or more parameters.

The data type for this utype is a string.

Possible values are:

  • followup
  • supersedes
  • retraction

SEAP Query Model Serializations

Previous

(Needs filling in - format taken from STAP page)

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:

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

Latest

HTTP

(Needs plenty of work here...; this is directly from an email)

In order of appearance (above); parameters with no specification assumes free-from strings:

responsecontent authorivorn contactname how pos=alpha1[:alpha2],delta1[:delta2];[size] datetime=start:end;reference paramname paramvalue=min:max;unit concept cited=[true|false] citerole=[followup|supersedes|retraction]

XML-RPC

TBD... (is email example too large?)

Output of a SEAP query

The data archive receives a SEAP request and returns a Votable describing VOEvent packets 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.-->

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

Notes:

  1. "format" - a value of "custom" would indicate VOTable contents specified
by the SEAP service provider. Is this too general, or too unwieldy to code against?

Examples:

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

  • VO standards:
1. ID: IVOA Identifiers http://www.ivoa.net/Documents/latest/IDs.html
2. Sky Event Reporting Metadata (VOEvent) http://www.ivoa.net/Documents/latest/VOEvent.html

-- PhillipWarner - 19 Sep 2007
-- ElizabethAuden - 09 Jan 2007

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r6 < r5 < r4 < r3 < r2 | More topic actions
 
AstroGrid Service Click here for the
AstroGrid Service Web		 This is the AstroGrid
Development Wiki
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback