NSF SAGE Facility IRISWS mars-event Web Service Documentation

Description

The mars-event web service returns Martian seismic event (marsquake) information detected from data recorded by SEIS (Seismic Experiment for Internal Structure) for the NASA InSight (Interior Exploration using Seismic Investigations, Geodesy and Heat Transport) mission to Mars.

For a full list of acknowledgements, see References.

Below is a full list of service parameters and their usage.

Query Usage

/query?	[time-bounds] [areographic-bounds] [magnitude-bounds] [event-identifiers] [type-constraints] [data-options] 
        [snr-bounds] [http-options]

Where:

time-bounds         ::  [starttime=<datetime>] [endtime=<datetime>]
areographic-bounds  ::  [minlatitude=<degrees>] [maxlatitude=<degrees>] [minlongitude=<degrees>] [maxlongitude=<degrees>]
                        [latitude=<degrees>] [longitude=<degrees>] [minradius=<degrees>] [maxradius=<degrees>]
magnitude-bounds    ::  [minmagnitude=<double>] [maxmagnitude=<double>] 
event-identifiers   ::  [eventname=<text>] [eventid=<text>]                              
type-constraints    ::  [magnitudetype=<comma-separated_list>]
                        [eventtype=<comma-separated_list>]
                        [locationquality=<comma-separated_list>]
snr-bounds          ::  [minsnrwind=<double>] [maxsnrwind=<double>] 
                        [minsnrmqs=<double>] [maxsnrmqs=<double>]
                        [minsnrpressure=<double>] [maxsnrpressure=<double>]                                   
data-options        ::  [includeallorigins=<boolean>] [includeallmagnitudes=<boolean>] [includearrivals=<boolean>]  
                        [version=<integer>] [contributor=<text>] [orderby=<time|time-asc|magnitude|magnitude-asc>]                               
http-options        ::  [format=<xml|text>]
                        [nodata=<204|404|200>]

(..) required parameter
[..] optional parameter

Parameters in the query string should be delineated by ampersands (&) as demonstrated below.

Sample Queries

Retrieve the latest catalog of events:
…/query

Retrieve all events from the second version of the catalog:
…/query?version=2

Additionally, include arrival and associated pick information:
…/query?includearrivals=true

Retrieve all events whose signals have clearly identifiable phases:
…/query?locationquality=A,B

Retrieve only those events with P and S body phase amplitude magnitude estimates, MbS and MbP:
…/query?magnitudetype=MbS,MbP

Retrieve a tabular summary of events that began on the lander’s 299th sol (Martian day) on Mars:
…/query?eventname=?0299?&format=text

Retrieve all events located at least 1° or more from the location of the lander (lat = 4.5024, long = 135.6234):
…/query?longitude=135.6234&latitude=4.5024&minradius=1

Detailed Descriptions of each Query Parameter

parameter examples discussion default type allowed values
start[time] 2019-06-25T00:00:00 Limit to events occurring on or after the specified start time. datetime see: Time Bounds
end[time] 2019-06-28T00:00:00 Limit to events occurring on or before the specified end time. datetime see: Time Bounds
BOX search terms incompatible with radial search
minlat[itude] 5.1 Southern boundary latitude -90° degrees [-90,90]
maxlat[itude] 3.9 Northern boundary latitude 90° degrees [-90,90]
minlon[gitude] -122 Western boundary longitude -180° degrees [-180,180]
maxlon[gitude] 136 Eastern boundary longitude 180° degrees [-180,180]
RADIAL search terms incompatible with the box search
lat[itude] 40.0 Specify the central latitude point. 0.0 degrees [-90,90]
lon[gitude] 100.0 Specify the central longitude point. 0.0 degrees [-180,180]
minradius 1.0 Specify minimum distance from the geographic point defined by latitude and longitude 0.0 degrees [0,180]
maxradius 5.0 Specify maximum distance from the geographic point defined by latitude and longitude 180.0 degrees [0,180]
minmag[nitude] 3.2 Limit to events with a magnitude larger than or equal to the specified minimum. float any
maxmag[nitude] 4 Limit to events with a magnitude smaller than or equal to the specified maximum. float any
eventid mqs2019uyyu Retrieve an event based on its unique resource identifier. Case-insensitive. text any
eventname ?0299? Retrieve events whose name matches the given glob-style expression. Case-insensitive. Accepts wildcards * and ?. glob pattern any
mag[nitude]type M2.4,MW,MWspec,MbS,MbP Limit events to those with an associated magnitude whose type matches one of the comma-separated list of types. Case-insensitive. list see: Magnitude Types
eventtype LF,BB,2.4Hz Limit events to those whose type matches one of the comma-separated list of types. Case-insensitive. list see: Event Type
locationquality A,B,C,D Limit events to those with an associated origin whose location quality matches one of the comma-separated list of types. Case-insensitive. list see: Location Quality
minsnrwind 3.2 Limit to events with SNR wind values larger than or equal to the specified minimum. float any
maxsnrwind 4 Limit to events with SNR wind values smaller than or equal to the specified maximum. float any
minsnrmqs 100.2 Limit to events with SNR mqs values larger than or equal to the specified minimum. float any
maxsnrmqs 10.1 Limit to events with SNR mqs values smaller than or equal to the specified maximum. float any
minsnrpressure 0.9 Limit to events with SNR pressure values larger than or equal to the specified minimum. float any
maxsnrpressure 2.3 Limit to events with SNR pressure values smaller than or equal to the specified maximum. float any
INCLUDEALL* search terms incompatible with text format
includeallmagnitudes true If true, includes all magnitudes associated with the returned events; if false, includes only the preferred magnitudes true boolean true or false
includeallorigins true If true, includes all origins associated with the returned events; if false, includes only the preferred origins true boolean true or false
includearrivals true If true, additionally includes arrival and associated pick information with the origins returned; if false, does not return this information false boolean true or false
version 2 Specify the version of the catalog from which events will be retrieved. latest2 integer see: Versions
contributor MQS Limit to events created by a contributor1 with the specified agencyID. Case-insensitive. text any
orderby magnitude Specify the criteria by which returned events are ordered time text time,
time–asc,
magnitude,
or magnitude–asc
format text Specify the media-type of the HTTP response xml text xml or text
nodata 404 Specify the status code of the HTTP response when when no data is found3 204 text 204, 404 or 200

1 Currently, the only contributor to this catalog is The Marsquake Service, whose identifier is mqs.

2 By default, the latest (most current) version available is served, corresponding to the numerically highest ranked version value available. Values start at 1, and increment positively with subsequent versions.

3 By default, when no events match the request, the service returns a response with no content and an HTTP status code of 204. To have the service return an empty response (with content-length 0) and a different HTTP status code, specify either 404 or 200 instead.

Datetime Format

YYYY-MM-DD[Thh:mm:ss] ex. 2020-01-31 and a time of 00:00:00 is assumed, or 2020-01-31T03:02:11

Where:

YYYY	:: four-digit year
MM	:: two-digit month (01=January, etc.)
DD	:: two-digit day of month (01 through 31)
T	:: date-time separator
hh	:: two digits of hour (00 through 23)
mm	:: two digits of minute (00 through 59)
ss	:: two digits of second (00 through 59)

[..] optional


WADL

Retrieve the WADL associated with this service:

application.wadl


Wildcards

Wildcards
The question mark ? represents any single character (exactly one), while the asterisk * represents zero or more characters.


Problems with this service?

Please send an email report of which service you were using, your URL query, and any error feedback to:
[email protected]
We will address your issue as soon as possible.

IRISWS mars-event web service