Updated October 30, 2026: includes station and channel metadata retrieval with seisFetch.Stations. If you encounter any issues, please submit a GitHub issue and/or contact Lkeen@mathworks.com.

Fetch Files from Earthscope's Seismic Data Website

Retrieve seismic waveforms and station metadata from EarthScope directly in MATLAB®. Use seisFetch.Timeseries for waveform data and seisFetch.Stations to discover stations, inspect channels, and retrieve instrument-response metadata without manually constructing service URLs.

A workflow for automatically accessing data from the NSF National Geophysical Facilities Web Services (operated by Earthscope) seismic data services via their FDSNWS interface.

This workflow allows you to:

• Specify network, station, location, channel, and time filters as method inputs.
• Programmatically build a standards-compliant URL.
• Retrieve and parse seismic traces (MiniSEED or SAC) directly into MATLAB®.
• Retrieve station locations, channel orientations, and sample rates as MATLAB tables.
• Search stations by geographic bounds or distance in angular degrees.
• Retrieve instrument responses as StationXML, RESP, or SAC poles and zeros.

Examples on how to plot and process the data provided.

The code centers around the seisFetch class in seisFetch.m. Its methods are static, so no object construction is needed.

Method	Purpose	Example live script
seisFetch.Timeseries	Retrieve seismic waveform samples	seisfetchExample.m
seisFetch.Stations	Retrieve network, station, channel, or instrument-response metadata	seisFetchStationsExample.m

SAC archives

seisFetch.Timeseries(...,'fileFormat','sac') reads every SAC file in the downloaded ZIP, including files in subfolders. It returns one structure per file: S(k).D contains that trace's samples, S(k).T0 is its first sample time (MATLAB datenum), and the remaining fields contain its SAC header. Trace lengths, sample intervals, and start times may differ. Single-file requests retain the previous scalar structure output.

For local ZIP archives, X = seisFetch.rdsaczip(filename) returns a structure array with t, d, and HEADER fields. With [D,T0,H] outputs, a single-file archive still returns a single-precision vector, scalar time, and header; a multi-file archive returns a cell array of data vectors, a vector of start times, and a header structure array. Missing optional header fields are empty in H. The 'enumerated' option and automatic byte-order detection apply to each file. Extracted directories are skipped; unreadable files raise an error.

With saveFiles=true, each SAC trace is sent separately to mksac, using numbered filenames for multi-file requests. The standalone third-party rdsac function is not modified.

Station metadata with seisFetch.Stations

Open seisFetchStationsExample.m in the MATLAB Live Editor for a guided example: retrieve station metadata, map locations, inspect channel sample rates, select vertical channels, and search nearby stations. The plain-text live script requires MATLAB R2025a or newer.

Stations uses the same six positional inputs as Timeseries, followed by optional name-value pairs. It queries the EarthScope FDSN station service. No third-party waveform reader is needed for metadata.

Migrating from irisFetch: irisFetch.Resp(...) → seisFetch.Stations(...,'level','response','fileFormat','resp'), which returns RESP-formatted text.

S = seisFetch.Stations(network,station,location,channel,startDate,endDate, ...
    'level','station','fileFormat','text');

Pass character vectors or string scalars for the six positional inputs. Use empty text for a filter you do not need. For example:

% Station locations and descriptions, returned as a MATLAB table.
S = seisFetch.Stations('IU','ANMO','','','','');
disp(S(:,{'Network','Station','Latitude','Longitude','Elevation'}));

% Channel metadata for a time window, including sample rate and orientation.
C = seisFetch.Stations('IU','ANMO','*','BH?', ...
    '2025-07-29 22:00:00','2025-07-30 04:00:00','level','channel');
disp(C(:,{'Location','Channel','SampleRate','Azimuth','Dip'}));

% Stations within 5 degrees of a point.
nearby = seisFetch.Stations('','','','','','', ...
    'latitude',34.95,'longitude',-106.46,'maxradius',5);

% Full instrument responses as StationXML, optionally saved locally.
[xmlText,filename] = seisFetch.Stations('IU','ANMO','00','BHZ', ...
    '2025-07-29','2025-07-30','level','response', ...
    'fileFormat','xml','saveFiles',true);

Empty inputs omit filters; use '--' to select blank location codes. Code filters support wildcards, comma-separated lists, and minus-prefixed exclusions. Date inputs are UTC text. Metadata epochs describe operation, not guaranteed waveform availability. Each row describes a metadata epoch; a station or channel can appear in multiple rows. Latitude, longitude, azimuth, and dip are in degrees; elevation and depth are in metres; sample rate is in samples per second.

Option	Values / behavior
level	station (default), network, channel, response
fileFormat	text (default table output); xml, geocsv, resp, sacpz return raw text
Geographic filters	minlatitude, maxlatitude, minlongitude, maxlongitude, latitude, longitude, minradius, maxradius, in degrees
Epoch filters	startbefore, startafter, endbefore, endafter, updatedafter
Metadata flags	includerestricted, includecomments: logical scalars; service defaults to true
saveFiles	False by default; true saves the original response to a unique filename in the current folder, returned as the second output
Timeout	Positive number of seconds, default 60

Response level requires xml, resp, or sacpz; resp and sacpz require response level. Text tables retain codes and dates as strings, preserving leading zeros and open-ended epochs. Measurement columns are numeric, with empty numeric fields represented by NaN. No matches returns an empty table for text output, or empty text for other formats. HTTP failures propagate. The retired includeavailability and matchtimeseries options are not supported.

Run the offline tests with runtests('tests'). The transport fixture is added only while tests run; do not add tests/fixtures or tests/sacFixtures permanently to the MATLAB path.

Prerequisites

• MATLAB® (R2019b or newer)
• MATLAB R2025a or newer to view the example .m live scripts with rich formatting.
• An internet connection to access EarthScope services.
• Keep seisFetch.m in the current folder or on the MATLAB path.

seisFetch.Stations uses built-in MATLAB functionality and does not require third-party waveform readers.

For waveform retrieval with seisFetch.Timeseries, install the appropriate MATLAB File Exchange utility by François Beauducel on your MATLAB path:

• rdmseed (for MiniSEED)

• rdsac (for SAC)

• rdmseed/mkmseed: https://www.mathworks.com/matlabcentral/fileexchange/28803-rdmseed-and-mkmseed-read-and-write-miniseed-files

• rdsac/mksac: https://www.mathworks.com/matlabcentral/fileexchange/46356-rdsac-and-mksac-read-and-write-sac-seismic-data-file

Note: These third-party utilities are not included with this repository and must be installed separately.

General Troubleshooting

Station metadata

• If seisFetch.Stations returns an empty table, broaden the time window or remove a station, channel, or geographic filter.
• Use 'level','channel' to retrieve sample rate and orientation columns.
• For response metadata, specify 'level','response','fileFormat','xml' (or use resp or sacpz).
• Empty EndTime values represent metadata epochs without a specified end date.

No data returned / 404

• Verify network, station, channel, and time window.
• Try broadening the time range or removing optional filters (e.g., quality).

Decoding errors

• Ensure rdmseed is installed for MiniSEED and rdsac for SAC.
• Confirm that the selected file_format aligns with the parser you have.

Timestamp issues

• Use datetime(..., 'ConvertFrom','datenum') as shown to visualize real time.
• Check for timezone assumptions in headers if times look shifted.

Authentication

• If using useAuth = true, make sure you have valid credentials