Help: mars-event v.1

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.

Contents

Introduction

The NASA InSight mission installed a single seismic station on the surface of Mars in 2019. Known as SEIS, the instrument was designed and produced by the French Space Agency (CNES), the Institut de physique du globe de Paris, and SEIS international partners and is key to the mission’s investigation of the planet’s interior.

The Mars Seismic Catalog comprises information from seismic events recorded during this two year mission and includes the first marsquake ever located on the planet. It is created and curated by the Marsquake Service (MQS), a collaborative ground service operation led by Eidgenössische Technische Hochschule (ETH) Zürich that includes seismologists from across the InSight team. The list of on-duty seismologists can be found at the DOI landing page for each release. Waveforms of these events and all other SEIS waveform data have been generated by the InSight Mars SEIS Data Service with acknowledgement reference to be found at the corresponding DOI landing page (see References).

Service Overview

The mars-event web service provides an interface to the Mars Seismic Catalog. It is an implementation of the FDSNWS-event version 1.2 specification adapted for Martian seismic events known as marsquakes.

The catalog is provided in XML format, although a text representation may also be requested. It validates against the QuakeML (BED) version 1.2 schema and includes Mars-specific data under the namespace prefix mars:.

Summary of mars-event Web Service Endpoints

Endpoint URL Description of Purpose Query Parameters Accepts (MIME-Type)
/query Returns events from the catalog and offers filtering and response customization see: Query Usage application/xml, text/plain
/version Returns the current full service version: major.minor.implementation text/plain
/catalogs Returns a list of DOIs for the catalog versions available from service application/xml
/contributors Returns a list of agencies identified in the catalog as publisher of an event1 application/xml
/application.wadl Returns a WADL for the service interface application/xml

1 The only contributor listed in the catalog is the Marsquake Service whose organizational identifier is mqs. This value is found in the agencyID element in the creationInfo of a QuakeML event.

Specifying the catalog version

The catalog will be updated every three-months, with a three-month lag behind real-time, for the duration of the mission in-sync with waveform data releases. New versions are provided by MQS and may include revisions to previous content as well as newly detected events.

The service is updated concurrently to make the latest version of the catalog available by default. However, any version may be accessed by specifying the version parameter.

Available Versions of the Mars Seismic Catalog

Version Release date Last record date DOI Example query
1 02-01-2020 09-30-2019 / Sol 299 doi:10.12686/a6 …/query?version=1
2 04-01-2020 12-31-2019 / Sol 389 doi:10.12686/a7 …/query?version=2
3 07-01-2020 03-31-2020 / Sol 478 doi:10.12686/a8 …/query?version=3
4 10-01-2020 06-28-2020 / Sol 567 doi:10.12686/a9 …/query?version=4
5 01-04-2021 10-12-2020 / Sol 668 doi:10.12686/a10 …/query?version=5
6 04-01-2021 12-31-2020 / Sol 746 doi:10.12686/a11 …/query?version=6
7 07-01-2021 03-31-2021 / Sol 833 doi:10.12686/a12 …/query?version=7
8 10-01-2021 06-30-2021 / Sol 922 doi:10.12686/a13 …/query?version=8
9 01-01-2022 09-30-2021 / Sol 1011 doi:10.12686/a14 …/query?version=9
10 04-01-2022 12-31-2021 / Sol 1101 doi:10.12686/a16 …/query?version=10
11 07-01-2022 03-31-2022 / Sol 1189 doi:10.12686/a17 …/query?version=11
12 10-01-2022 06-30-2022 / Sol 1277 doi:10.12686/a18 …/query?version=12
13 01-01-2023 09-30-2022 / Sol 1367 doi:10.12686/a19 …/query?version=13
141 04-01-2023 12-31-2021 / Sol 1456 doi:10.12686/a21 …/query

1 default – current data release

Querying and filtering events

The /query? endpoint returns the entire catalog of events.

Note the inclueall* parameters are unavailable for text format, which can only represent preferred magnitude and origin estimates (see Text for more information).

Type Selection

Events are classified based on the nature of their seismic signal.

Event Type

A seismic signal is assigned an event type according to its frequency content. These types belong to one of three families: the low frequency family (those dominated by long periods), the high frequency family (those dominated by high frequencies), and the recently identified super high frequency family.

The service allows one to select events by type using the eventtype parameter. It works case-insensitively and accepts a comma-separated list of event types.

Example Retrieve all events in the Low Frequency family whose signals are predominately characterized by energies below 2.4Hz:
…/query?eventtype=LF,BB&format=text

Event types in the latest catalog version

Label Type Description Example query
Low Frequency family: event energy generally at long period
LF Low frequency Energy in 3 components all below 2.4Hz. …/query?eventtype=LF
BB Broadband Energy in 3 components predominantly below 2.4Hz though also includes excitement at and possibly above 2.4Hz. …/query?eventtype=BB
High Frequency family: event energy generally at high frequency
HF High frequency Energy in 3 components predominantly at 2.4Hz and above.
‘Predominantly’ indicates some energy below 2.4Hz is possible.
…/query?eventtype=HF
2.4Hz 2.4 Hz Energy in 3 components centered around 2.4Hz resonance, with very limited excitation above or below. (It is likely these are small amplitude HF events.) …/query?eventtype=2.4Hz
VF Very High frequency Special case of high frequency events that show clear differences in energy between vertical and horizontal components. Horizontal energy is significantly larger than vertical energy at higher frequencies …/query?eventtype=VF
Other signals
SF Super High frequency Very short duration high frequency events that do not include energy at 2.4Hz or below. Frequency (SF) Typically between 5-10Hz, and horizontal energy is significantly larger than vertical energy. …/query?eventtype=SF

Location Quality

An event is assigned a quality based on the strength of its seismic signal and the ability to identify and interpret its phase arrivals.

The service allows one to filter events by this characterization using the locationquality parameter. It matches case-insensitively against a comma-separated list of these values.

Example Query for events with clearly identifiable phases (e.g., A and B quality events):
…/query?locationquality=A,B

Location qualities in the latest catalog version

Label Quality summary Key features Example query
A High Multiple clear and identifiable phases and clear polarization (i.e. a reliable location is provided using well constrained distance and back-azimuth) …/query?locationquality=A
B Medium Multiple clear and identifiable phases but no or poorly constrained polarization OR well constrained polarization, but not enough clear phase picks for a well constrained
distance estimate (i.e. location is missing or very poor)
…/query?locationquality=B
C Low Signal is clearly observed but phase picking is challenging:
- (HF/2.4Hz/VF) Pg and Sg pickable, but speculative OR large uncertainty OR low SNR
- (LF/BB) no clear phases can be identified OR only a single phase is clearly identifiable OR multiple phases are identifiable, but no clear picks can be attributed to P and S phases
- (SF) peak signal amplitude of data with 7.9Hz filter is above 2×10-9 m/s
…/query?locationquality=C
D Suspicious – Signal only weakly observed OR
- Signal may not be attributable to a seismic event OR
- (HF/2.4/VF) impossible to pick both Pg and Sg OR
- (SF) peak signal amplitude of data with 7.9Hz filter is below 2×10-9 m/s
…/query?locationquality=D

Magnitude Type

Magnitude scales used in the latest catalog version, V7, are described in Bose et al (2021). These were initially developed in Böse et al (2018) before the landing with synthetic waveforms in the absence of a priori seismic data and were recalibrated in Giardini et al (2020). Descriptions of scales used since the third catalog version can found in Clinton et al. (2021). It is possible these will continue to be revised as new events are observed and more is learned about the specific transmission properties of Mars.

The service allows one to filter events by associated magnitude type with the magnitudetype parameter. It accepts a comma-separated list of these values and works case-insensitively.

Example Query for only those events with P and S body phase amplitude magnitude estimates, MbS and MbP:
…/query?magnitudetype=mbp,mbs

Magnitude types in latest catalog version

Label Scale (MMai) Description Example query
MW MMaW preferred1 …/query?magnitudetype=MW
M2.4 MMa2.4Hz 2.4Hz resonance …/query?magnitudetype=M2.4
MWspec MMaWspec spectral fitting …/query?magnitudetype=MWspec
MbS mMabS S body-wave …/query?magnitudetype=MbS
MbP mMab P body-wave …/query?magnitudetype=MbP

1 Assigned to all events

1 The preferred magnitude, when available

Unique Identifiers

There are two ways with which to uniquely identify events: event name and publicID, using the parameters eventname and eventid respectively.

Event Name

Event names are unique across catalog versions and encode information about when the event occurred. They are generated during event creation, using the following format: [y][xxxx][z], where [y] indicates the family to which the event belongs (‘S’ = Low and High Frequency families and ‘T’ = Super High Frequency family), [xxxx] is the sol (Martian day) on which the event begins (starting from sol 0, when InSight landed on Mars), and [z] is a letter used to ensure uniqueness if multiple events occur on a single Sol.

The eventname parameter performs a case-insensitive search for events with names matching the given value. The following glob-style wildcard characters can be used in the expression to select sets of events with similar names:

Wildcard Meaning Example query
* Any set of characters Retrieve events whose names begin with ‘S’ (i.e. those belonging to Low or High Frequency families):
…/query?eventname=S*&format=text
? Any single character Retrieve all events beginning on the lander’s 299th sol (Martian day) on Mars:1
…/query?eventname=?0299?&format=text

1 Note that the question-mark (?) must be URL-encoded as ASCII (%3F) when entered directly into search bar.

Public ID

Public identifiers are used as a resource reference to an event and updated when information about that event changes. In the QuakeML formulation, the identifier follows the first forward slash in the “publicID” attribute of an event tag, after the authority ID. This service uses identifiers assigned by the insight.mqs authority.

Example Find an event by its publicID:
…/query?version=3&eventid=Event/20200626-143806/f90a7e36&format=text

Time Bounds

The service offers the ability to select events occurring between a starttime and endtime, inclusive. The parameters accept a date and time; if only the former is given, a time of 00:00:00 (“start of day”) is assumed.

All values are interpreted as Coordinated Universal Time (UTC) with a zero timezone offset, according to the ISO 8601 standard. The timezone designator (‘Z’) should be omitted. The representation can be summarized as follows: YYYY-MM-DD[Thh:mm:ss], where [..] is optional.

Example The following queries retrieve equivalent results:
…/query?starttime=2019-09-30T00:00:00
…/query?starttime=2019-09-30

Location Search

Single seismic stations pose unique challenges to location estimation, and these determinations are typically associated with great uncertainties. Only events with distance and back-azimuth calculations have location estimates. MQS notes that:

Only a handful of events in the catalog include a computed latitude/longitude location. A location is required for a valid QuakeML origin, so by default all other events are assigned the location of the lander at, lat=4.5024, long=135.6234.

The service provides two methods to select events by location: bounding box or bounding radius; parameters from these methods should not be mixed in any single request.

Orientation values used are consistent with IAU (International Astronomical Union) standards for Mars. Longitude increases to the East, and latitude is planetocentric. Coordinate values are expressed in decimal degrees, and referenced to the Martian Equator at 0° and Prime Meridian at ±90°.

Bounding Box

The four parameters – minlatitude, maxlatitude, minlongitude, and maxlongitude – work together to specify a latitude-longitude bounding rectangle on the surface of Mars using decimal degrees. By definition, an event is contained within the selection if, 1) sweeping north (increasing latitude) from minlat to maxlat traverses the event’s latitude, and 2) sweeping east (increasing longitude, possibly crossing antemeridian at ±180°) from the minlong to maxlong traverses event’s longitude.

Example
…/query?minlatitude=2&maxlatitude=60&minlongitude=-150&maxlongitude=160

Example The following query retrieves a list of the events in the catalog without a computed latitude/longitude (i.e. those assigned to the location of the lander):
…/query?minlatitude=4.5024&maxlatitude=4.5024&minlongitude=135.6234&maxlongitude=135.6234

Bounding Radius

The four parameters – latitude, longitude, maxradius and minradius – allow one to select a circular or donut-shaped area on the surface of the planet. The latitude and longitude parameters represent a location on Mars in spherical coordinates. The minradius and maxradius parameters set minimum and maximum great circle distances between the location defined by latitude and longitude and that of an event. All values should be given in decimal degrees. The calculation presumes a spherical Mars with an equatorial radius of 3306.2 km. The Haversine formula is used for great circle distance determinations, and results are rounded to the picometer (1012) before comparison.

Example
…/query?latitude=40.0&longitude=-100.0&minradius=18.0&maxradius=180

Customizing the HTTP response

Format

The format of the data returned can be specified using the format parameter or by setting the Accept header of the request. The value of the query parameter is favored when both are provided.

Data formats supported by the mars-event service

Format MIME-Type and Encoding Example query
xml1 application/xml; charset=UTF-8 …/query?format=xml
…/query
text text/plain; charset=UTF-8 …/query?format=text

1 default

XML

By default, the service returns QuakeML, an XML representation of seismological data originally created at ETH Zurich and collaboratively developed with international partners. Specifically, it validates against a variant of the QuakeML 1.2 Basic Event Description (BED) schema with mars-specific extensions. These tags are prefixed with the mars namespace.

Sample output: …/query?format=xml&eventid=mqs2019onhx


<q:quakeml xmlns=“http://quakeml.org/xmlns/bed/1.2” xmlns:q=“http://quakeml.org/xmlns/quakeml/1.2” xmlns:mars=“http://quakeml.org/xmlns/bed/1.2/mars”>
    <eventParameters publicID=“smi:insight.mqs/EventParameters”>
        <event publicID=“smi:insight.mqs/mqs2019onhx”>
            <description>
                <text>S0235b</text>
                <type>earthquake name</type>
            </description>
            <description>
                <text>Elysium Southeast</text>
                <type>region name</type>
            </description>
            <typeCertainty>suspected</typeCertainty>
            <creationInfo>
                <agencyID>mqs</agencyID>
                <author>scevent@sc3mars-op</author>
                <creationTime>2019-10-28T14:45:42.361542Z</creationTime>
            </creationInfo>
            <origin publicID=“smi:insight.mqs/origin/20201007-202124/e21efa19”>
                …
                <mars:locationQuality>http://quakeml.org/vocab/marsquake/1.0/MarsLocationQualityType#A</mars:locationQuality>
                <mars:distance>
                    <mars:value>27.85</mars:value>
                    <mars:upperUncertainty>14.77</mars:upperUncertainty>
                    <mars:lowerUncertainty>14.77</mars:lowerUncertainty>
                </mars:distance>
                <mars:azimuth>
                    <mars:value>74.0</mars:value>
                </mars:distance>
            </origin>
            <origin publicID=“smi:insight.mqs/origin/20210326-123537/62af9073”> … </origin>
            …
            <magnitude publicID=“smi:insight.mqs/Magnitude/20210326-123541/9f26b049”>
                <mag>
                    <value>3.5</value>
                </mag>
                <type>MFB</type>
                …
            </magnitude>
            <magnitude publicID=“smi:insight.mqs/Magnitude/20201007-202127/6b1384d0”> … </magnitude>
            <preferredOriginID>smi:insight.mqs/origin/20201007-202124/e21efa19</preferredOriginID>
            <preferredMagnitudeID>ami:insight.mqs/Magnitude/20210326-123541/9f26b049</preferredMagnitudeID>
            <type>other event</type>
            <mars:type>http://quakeml.org/vocab/marsquake/1.0/MarsEventType#BROADBAND</mars:type>
            <mars:typeCertainty>suspected</mars:typeCertainty>
            <mars:snr snrMQS=“12.6” snrPressure=“22.93” snrWind=“18.87”/>
        </event>
    </eventParameters>
</q:quakeml>

Text

The text format is originally defined in the FDSNWS-event specification. It provides a tabular summary of events and is especially useful to quickly reference the catalog or when viewing requests directly in-browser or from a command-line interface.

Sample output: …/query?format=text&eventname=S0235b

EventID|Time|Latitude|Longitude|Depth/km|Author|Catalog|Contributor|ContributorID|MagType|Magnitude|MagAuthor|EventLocationName|EventType
mqs2019onhx|2019-07-26T12:15:36.7000Z|11.1821|161.492||scevent@sc3mars-op||mqs|S0235b|MFB|3.5||Elysium Southeast|BROADBAND

Attributes in the text representation are delineated by pipe (|) characters; this is also known as pipe-separated values (PSV) format. Each row represents an event in the output – except for the first line (i.e. the header), which contains the column names in input order.

Columns in the text output of the mars-event web service

Column Description Related query parameters
EventID The publicID of the event as assigned by the insight.mqs authority during catalog creation. eventid
Time The event’s preferred origin time in UTC starttime endtime
Latitude The latitude of the event’s preferred origin in decimal degrees lat minlat maxlat
Longitude The longitude of the event’s preferred origin in decimal degrees longitude minlongitude maxlongitude
Depth/km Not included in this catalog
Author Name of the author of the event’s preferred origin
Catalog Identifier of the source catalog
Contributor Identifier of the agency who published the event (i.e. mqs) contributor
ContributorID Event Name as reported by the contributor eventname
MagType Magnitude sale identifier of the event’s preferred magnitude (e.g. M2.4, MW, MWspec, MbS, MbP) magtype
Magnitude The value of the event’s preferred magnitude mag
MagAuthor Name of the author of the event’s preferred magnitude
EventLocationName Aereographic description of event’s location
EventType The event’s type classification (e.g. LF, BB, HF, 2.4Hz, VF) eventtype

Note This format only encodes preferred origin and magnitude estimate and cannot display pick or arrival information. As such, when requesting format=text, the parameters includearrivals, includeallmagnitudes and includeallorigins cannot be used.

nodata Status Codes

By default, when no events match the request, the service returns a response with no content and an HTTP status code of 204. The page will not reload, because 204 messages do not have a response body. To receive a page update, use either 200 or 404. The 200 response body will always have a content-length of 0, while a 404 will provide a response body with an error message indicating not found.

No data HTTP status codes accepted by mars-event web service

Code HTTP Status Payload? Example HTTP response
204 No Content no
Url: ../query?eventid=cat&nodata=204&format=text
Protocol: HTTP/1.1 
Status: 204 NO CONTENT
404 Not Found yes
Url: ../query?eventid=cat&nodata=404&format=text
Protocol: HTTP/1.1 
Status: 404 NOT FOUND
Content-Type: text/plain;charset=UTF-8
Content-Length: 262
200 Ok yes
Url: ../query?eventid=cat&nodata=200&format=text
Protocol: HTTP/1.1 
Status: 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 0

References

Additional Resources

Computing Distances
FDSN (International Federation of Digital Seismograph Networks) Web Services
IETF RFC 7230 – HTTP: Message Syntax and Routing
IETF RFC 7231 – HTTP Semantics and Content
International System of Units
ISO 8601 C.1.3.2 Date and Time
QuakeML


Problems with this service?

Please send an email report of which service you were using, your URL query, and any error feedback to:
data-help@earthscope.org
We will address your issue as soon as possible.