NSF National Geophysical Facility FDSNWS dataselect Web Service Documentation

Service interface URL builder Help Revisions

Description

URL Builder

The fdsnws-dataselect service provides access to time series data for specified channels and time ranges.

Time series data are selected using FDSN Source Identifiers: (network, station, location & channel) and time ranges. The channel value should be a 3-character SEED compliant code; the extended-channel is not yet supported. Data are returned in miniSEED and GeoCSV format.

This service is an implementation of the FDSN web service specification version 1.

 

NOTE: polling for real-time continuous data is not allowed. For continuous, near real-time data please use our streaming service.

 

service.iris.edu service redirects to service.earthscope.org

If you are using this service through the service.iris.edu domain the connections will be redirected using an HTTP 307 to our new service at service.earthscope.org. All known clients will automatically follow this redirect, making it seamless for users.

Redirecting with curl is enabled by adding the -L or --location command line option.

 

While the legacy URL will work (with redirection) we recommend direct use of the https://service.earthscope.org/fdsnws/dataselect/1 location whenever possible.

Many data access frameworks and tools allow specification of the services used. For example, using ObsPy 1.5+ the service can be used by specifying the client as EARTHSCOPE:

 

from obspy.clients.fdsn import Client
client = Client("EARTHSCOPE")

 

Using earlier versions of ObsPy the service can be used by specifying the client as https://service.earthscope.org:

 

from obspy.clients.fdsn import Client
client = Client("https://service.earthscope.org/")

 

Important changes for the service transition to earthscope.org

 

  • Action required for restricted data users

    You will need new credentials. Visit https://www.earthscope.org/user, create an account (if you do not already have one), then:
    • navigate to the Credentials tab
    • click “REVEAL MY CREDENTIALS,” and “CREATE FDSNWS CREDENTIALS” if none exist

 

  • Some output formats are not yet supported: SAC and text. These will be added in the future.

 

  • The service now requires secure HTTPS, specifically TLS 1.2 or later. Requests to the unencrypted HTTP endpoint will be redirected to the HTTPS endpoint according to current best practices.

Some older software may not follow redirects from unencrypted HTTP to secure HTTPS. Configure the software, if possible, to use the direct URL to the service https://service.earthscope.org/fdsnws/dataselect/1

 

  • The following parameters are permanently retired:
    • quality – Select data based on miniSEED data quality indicator
    • minimumlength – Limit results to continuous data segments of a minimum length
    • longestonly – Limit results to the longest continuous segment per channel
    • repository – Limit results to specified repositories
    • szsrecs – Skip data records with zero samples, such as event detection records

 

  • With the removal of the szsrecs parameter the service will not remove zero-sample records by default, which matches the behavior of all other data center implementations.

 

  • The service now limits the volume of miniSEED data that will be returned with a single query. We recommend limiting requests to one station for a 24-hour period at the most.

 

  • The service now returns version 2 miniSEED data records without modification of the quality code. Previously data were marked with an M quality regardless of modification to indicate it had been through a merging process. Now users will see the quality codes of the data as they were submitted to the archive. In some cases this may result in a time series that is composed of data records of more than one quality.

 

  • Some HTTP response codes for errors have changed to be more precise, but they remain broadly recognized codes.

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

Query Usage

/query? (date-range-options) [channel-options] [quality-options] [misc-options] [format-options] [nodata=404]

where

date-range-options	:: 	(start=<time>) (end=<time>)
channel-options		:: 	[net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>]
quality-options		:: 	[quality=<M>]
misc-options		::	[repository=<repository_name>] [szsrecs=<true|false>] [scale=AUTO] [minimumlength=<seconds>]* [longestonly=<true|false>]*
format-options          ::      [format=<miniseed|sac.zip|geocsv>]

(..) required
[..] optional
* deprecated

Query parameters are joined by ampersands ”&”, without blank space (see the sample queries).

POST Usage

Alternately, instead of providing parameter-value pairs in the URL, a file containing a selection list can be POSTed to this service. This is the same method used with the fdsnws-station webservice. For additional details, including an example selection file, visit this page’s help section.

quality=<M>
format=<miniseed|sac.zip|geocsv>
<Network> <Station> <Location> <Channel> <StartTime> <EndTime>
...

Quality and format are optional. Minimumlength and longestonly are options being deprecated. Wildcards are acceptable for Network, Station, Location, and Channel. Click here for time format details.

Sample Queries

Detailed Descriptions of each Query Parameter

parameters examples discussion default type
FDSN options
start[time] 2010-02-27T06:30:00 Specifies the desired start-time for miniSEED data day/time
end[time] 2010-02-27T10:30:00 Specify the end-time for the miniSEED data day/time
net[work] IU Select one or more network codes. Accepts wildcards and lists. Can be SEED codes or data center defined codes. any string
sta[tion] ANMO Select one or more SEED station codes. Accepts wildcards and lists. any string
loc[ation] 00 Select one or more SEED location identifier. Accepts wildcards and lists. Use -- for “Blank” location IDs (ID’s containing 2 spaces). any string
cha[nnel] BH1 Select one or more SEED channel codes. Accepts wildcards and lists. any string
scale auto Scale the timeseries values by the instrument sensitivity. The scaling is only applied to GeoCSV formatted output and the only valid input for this parameter is scale=AUTO. no scaling string
nodata 404 Specify which HTML Status code is returned when no data is found.1 204 204 or 404
format geocsv Specify the format of the data returned:
miniseed — miniSEED data format
geocsv — GeoCSV format in time-sample pair, 2 column format
geocsv.<modifiers> — GeoCSV with the following additional modifiers:
    * .inline — return as text/plain with disposition inline, else returned as text/csv with disposition attachment
    * .zip — return as a ZIP archive, each segment as a file in the archive, without this .inline is assumed
    * .tspair — return in time-sample pair, 2 column format. The default.
    * .slist — return as sample list, 1 column format, without this .tspair is assumed. 		miniseed

1 By default, the service returns a HTTP response code 204, which means the request was successful, but no data (no content) was retrieved. However, because there was no “error”, no error message is generated and it may appear that the browser did nothing. To force an empty query response to display an error message, add nodata=404 to the URL.

WADL

Retrieve the WADL associated with this service:

application.wadl

Date and Time Formats

Year, Month, Day in Month — Time:

YYYY-MM-DDThh:mm:ss[.ssssss] ex. 1997-01-31T12:04:32.123

YYYY-MM-DD ex. 1997-01-31 a time of 00:00:00 is assumed

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) (AM/PM NOT allowed)
mm	:: two digits of minute (00 through 59)
ss	:: two digits of second (00 through 59)
ssssss	:: one to six digits representing decimal fractions of a second, down to microseconds

Wildcards and Lists

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

Lists
Multiple items may also be retrieved using a comma separated list. Wildcards may be included in the list. For example, with channel codes: channel=EH?,BHZ,BHE

Problems with this service?

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

FDSNWS dataselect web service