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
- Service Overview
- Specifying the catalog version
- Querying and filtering events
- Customizing the HTTP response
- References
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.
- To include pick and arrival information with an event, set includearrivals=true
- To limit to preferred origin estimates, set includeallorigins=false
- To limit to preferred magnitude estimates, set includeallmagnitudes=false
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.