Description
The fdsnws-station web service returns station metadata in FDSN StationXML format v1.1 (schema here) or as derivative text formats. Results are available at multiple levels of granularity: network, station, channel and response.
Metadata 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.
This service is an implementation of the FDSN web service specification version 1.
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.
Recommended direct use of service.earthscope.org
While the legacy URL will work (with redirection) we recommend direct use of the https://service.earthscope.org/fdsnws/station/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
- The following parameters are permanently retired:
includeavailability– Include time series data availability in the responsematchtimeseries– Limit results to those with available data
- The following output formats provide new capability:
format=resp– return “RESP” formatted responses as needed for evalresp and other programsformat=sacpz– return “SAC Poles and Zeros” formatted responses as needed by sac and other programs
For both of these new output formats the level must be “response”, i.e. level=response.
- 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/station/1
- 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
To retrieve data from the station service, submit a request by either of the methods below:
- via HTTP GET: Provide a series of parameter-value pairs in the URL that specify the start-time and end-time, along with the desired network(s), station(s), location(s) and channel(s). Please refer to the table below titled “Detailed Descriptions of each Query Parameter” for usage details. Each parameter-value pair should be separated by an ampersand
&, and with no space. A GET request may take the following general form:
/query? [channel-options] [time-constraints] [geographic-constraints] [miscellaneous] [nodata=404]
- via HTTP POST: Submit an arbitrary selection list to the service. Please note that all parameters listed under the rectangular geographic constraints, radial geographic constraints, and miscellaneous sections of the Detailed Descriptions of each Query Parameter table on the main service documentation page may be submitted using either GET or POST methods. For additional details on constructing and submitting POST selection files, visit the POST Examples in the Help section.
- via web service clients: Dedicated clients that use the fdsnws-station service can be found on the Client list. In particular, the FetchMetadata script will request metadata from fdsnws-station, parse the returned XML and print or save simple ASCII information; this script can be used as a starting point for creating customized metadata requests.
Sample Queries
- radial geographic
https://service.earthscope.org/fdsnws/station/1/query?latitude=-56.1&longitude=-26.7&maxradius=15&nodata=404
- rectangular geographic with time windows
…/query?startafter=2003-01-07&endbefore=2011-02-07&minlatitude=15&maxlatitude=55&minlongitude=170&maxlongitude=-170
- text output, with network level exclusion
…/query?network=S*,-SY&level=network&format=text
- horizontal channels for subsetted TA data
…/query?network=TA&station=A*&channel=BH?,-BHZ&level=channel&format=text
Detailed Descriptions of each Query Parameter
| parameter | examples | discussion | default | type |
|---|---|---|---|---|
| channel options | ||||
| Empty/No parameters | submitting an empty query (e.g. .../query?) will return ALL stations at the default level. |
|||
| Exclusion parameters | each parameter listed under “channel options” can be prefixed with a - (minus) sign to exclude certain metadata from a request. |
|||
| net[work] | IU | Select one or more network codes. Can be SEED codes or data center defined codes. Accepts wildcards and lists. | 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. Use -- for “Blank” location IDs (ID’s containing 2 spaces). Accepts wildcards and lists. |
any | string |
| cha[nnel] | BH1 | Select one or more SEED channel codes. Accepts wildcards and lists. | any | string |
| time constraints | ||||
| start[time] | 2001-12-19T00:00:00 | Limit to metadata describing channels operating on or after the specified start time. | any | day/time |
| end[time] | 2012-12-31T23:59:59 | Limit to metadata describing channels operating on or before the specified end time. | any | day/time |
| startbefore | 2001-12-31T00:00:00 | Limit to metadata epochs starting before specified time. Applied to channel epochs. | any | day/time |
| startafter | 2005-12-31T00:00:00 | Limit to metadata epochs starting after specified time. Applied to channel epochs. | any | day/time |
| endbefore | 2005-12-31T00:00:00 | Limit to metadata epochs ending before specified time. Applied to channel epochs. | any | day/time |
| endafter | 2005-12-31T00:00:00 | Limit to metadata epochs ending after specified time. Applied to channel epochs. | any | day/time |
| rectangular geographic constraints | ||||
| minlat[itude] | 15.5 | Southern boundary. | -90° | degrees |
| maxlat[itude] | 25.0 | Northern boundary. | 90° | degrees |
| minlon[gitude] | -170.0 | Western boundary. | -180° | degrees |
| maxlon[gitude] | 170.0 | Eastern boundary. | 180° | degrees |
| radial geographic constraints | ||||
| lat[itude] | 35.0 | Specify the central latitude point1. | 0 | degrees |
| lon[gitude] | 170.0 | Specify the central longitude point1. | 0 | degrees |
| maxradius | 20.0 | Specify maximum distance from the geographic point defined by latitude and longitude1. |
degrees | |
| minradius | 19.0 | Specify minimum distance from the geographic point defined by latitude and longitude1. |
0 | degrees |
| miscellaneous | ||||
| sensor | STS-2 | Select matching sensor descriptions. Sub-string match is case-insensitive and may be specified with wildcards and lists. The match is made to compare any string value in the Sensor schema location. | any | string |
| level | channel | Specify level of detail using network, station, channel,or response2. |
station | level |
| includerestricted | TRUE | Specify whether results should include information relating to restricted channels. | true | Boolean |
| includecomments | FALSE | Specify if results should include station and channel comments. | true | Boolean |
| updatedafter | 2012-01-01 | Limit to metadata updated after specified UTC date; updates are data center specific. | any | day/time |
| format | text | Specify output format. Valid formats include xml, text, geocsv, resp, and sacpz. |
xml | format |
| nodata | 404 | Specify which HTTP status code is returned when no data is found.3 | 204 | 204 or 404 |
1 latitude, longitude, maxradius and minradius work together to define a radial boundary.
2 When level=response only 120,000 channel entries may be requested.
3 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.
Output Format
Output may be text or xml. If format=xml or format is not specified, then the results will be returned in FDSN StationXML format. When format=text or format=geocsv, then a simple | separated table is returned. Note, format=text is not available for level=response
NOTE: In the 1.1 version of this service, networks, stations, and channels without an explicit EndTime are represented in the following way:
format=xml: the EndTime is OMITTED from the element- for all other formats the EndTime field is EMPTY
In the future, clients should be prepared for omitted or blank field entries where they do not apply. Currently, such fields known to possibly have blank entries are: - StartTime
- Instrument (description)
- Scale, ScaleFreq, ScaleUnits, SampleRate
Level
Level specifies the level of detail returned within the returned XML. ‘network’ is the highest level, followed by ‘station’. To see channels within stations, level=‘channel’ is used. The most detailed level is ‘response’, which provides details to permit signal processing and proper conversion of digital readings to physical measurement.
WADL
Retrieve the WADL associated with this service:
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
Exclusions
A single dash ‘-’ may be prefixed to a single element to designate exclusion of that element from a selected set. The following example would remove all BHZ channels along with all 00 and 10 locations: channel=B*,-BHZ&location=-00,-10
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.