NSF SAGE Facility IRISWS nrl Web Service Documentation

Description

The nrl web service returns instrument response information from the current Nominal Response Library (NRL) database using the following service query methods:

/catalog

Returns information about types, manufacturers, models and configuration parameters of instruments whose responses are available in the nrl web service.

  • Output formats:
    • xml (XML .xml)
    • json (JSON .json)
    • text (plain text .txt)

Alternatively, you can browse NRL contents using the new NRL web page.

/combine

Returns fully formed instrument responses in FDSN StationXML, RESP, or StationXML-Response formats. It can also return a full version of the Library for local use.

  • Output formats:
    • stationxml or stationxml.zip (StationXML as .xml or .zip archive)
    • stationxml-resp or stationxml-resp.zip (StationXML-Response as .xml or .zip archive)
    • resp or resp.zip (RESP as plain text or .zip archive)

/prefix-lookup

Returns a prefix table of instrument configuration prefixes with their names and associated logic tree questions.

  • Output formats:
    • xml (XML .xml)
    • json (JSON .json)
    • text (plain text .txt)

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

Query Usage

/catalog

/catalog? [selection-options] [reference-options] [format-options] [nodata-options]

where

selection-options  ::  [element=<text>] [manufacturer=<text>] [model=<text>] [level=<text>][updatedsince=<date>]
format-options     ::  [format=<json|xml|text>]
nodata-options     ::  [nodata=204|404]

Query parameters are joined by ampersands ”&”, without blank space.

/combine

/combine? (selection-options) [epoch-options] [format-options] [nodata-options] [administrative-options]

where

selection-options      ::  [instconfig=<text>] [element=<text>] [manufacturer=<text>] [model=<text>] --[updatedsince=<date>]
epoch-options          ::  [channel-options] [time-options]
  channel-options          ::  [net=<network>] [sta=<station>] [loc=<location>] [cha=<channel>]
  time-options             ::  [starttime=<date>] [endtime=<date>] 
format-options         ::  [format=<resp|resp.zip|stationxml|stationxml.zip|stationxml-resp|stationxml-resp.zip>]
nodata-options         ::  [nodata=204|404]
administrative-options ::  [admin]

Query parameters are joined by ampersands &, without blank space. For the instconfig parameter, a colon : separates instrument identifiers in a cascade; a comma , separates instrument identifiers in a list.

In the context of the irisws-nrl service, selection options refer to parameters that filter the results returned by the service based on the value(s) of the parameter(s). Epoch options allow the requestor to submit optional network, station, location and channel codes to be written into the returned responses, as well as the epoch start and end times (stationxml and resp formats only).

/prefix-lookup

/prefix-lookup? [format-options] [nodata-options]

where

format-options     ::  [format=<json|xml|text>]
nodata-options     ::  [nodata=204|404]

Query parameters are joined by ampersands &, without blank space.

POST Usage

Alternately, instead of providing parameter-value pairs in the URL, a file containing a selection list can be POSTed to this service. For additional details, including an example selection file, visit the Help section.

Post submissions may use these parameters:

instconfig=<text>
man[ufacturer]=<text>
model=<text>
updatedsince=<date>
network=<text>
station=<text>
location=<text>
channel=<text>
startTime=<date>
endTime=<date>

Comma-separated lists are allowed for type, manufacturer, model, and instconfig but not for network, station, location, and channel. Wildcards are also allowed for type, manufacturer and model. Click here for time format details.

Sample Queries

Return the available response information, in JSON format, for all sensors or dataloggers manufactured by EQMet:
…/catalog?nodata=404&manufacturer=EQMet&format=json

List all response element types that have instrument responses in the NRL; use text format:
…/catalog?&level=element&format=text&nodata=404

List all instrument manufacturers who have instrument responses in the NRL; use text format:
…/catalog?&level=manufacturer&format=text&nodata=404

List instrument models and configurations for manufacturer CEADASE that are available in the NRL; use xml format:
…/catalog?&manufacturer=CEADASE&level=configuration&format=xml&nodata=404

Return the response file for a sensor in StationXML-Response format:
…/combine?instconfig=sensor_CEADASE_CPHM-500_LP1_PG8_SG2250_STgroundVel&format=stationxml-resp&nodata=404

Combine a sensor and datalogger in a cascade and return a single RESP format file:
…/combine?instconfig=sensor_CEADASE_CPHM-500_LP1_PG8_SG2250_STgroundVel:datalogger_EQMet_SMA_FR50&format=resp&nodata=404

Return separate response files for a sensor and datalogger in as StationXML, zipped:
…/combine?instconfig=sensor_CEADASE_CPHM-500_LP1_PG8_SG2250_STgroundVel,datalogger_EQMet_SMA_FR50&format=stationxml.zip&nodata=404

Return separate response files for all Guralp CMG-3T sensors as StationXML-Response, zipped:
…/combine?element=sensor&manufacturer=Guralp&model=CMG-3T&format=stationxml-resp.zip&nodata=404

Return a text table of instrument configuration prefixes, their names and associated logic tree questions for locating a desired instrument response.
…/prefix-lookup?&format=text&nodata=404

Detailed Descriptions of each Query Parameter

parameter examples notes default element
Common options (/catalog, /combine and /prefix-lookup query methods)
nodata 404 Specify which HTTP status code is returned when no data is found.1 204 204 or 404
/catalog options (also takes Common options as described above)
element sensor Filter by element type. Current elements include sensor, datalogger, integrated and soh. Accepts wildcards and lists. None string
man[ufacturer] EQMet Filter by manufacturer. Accepts wildcards and lists. None string
model CMG* Filter by model. Accepts wildcards and lists. None string
level model Specify the level of desired detail. Accepted values are element, manufacturer, model and configuration. configuration string
updatedsince 2021-01-01 Filter for information updated on or since the beginning day boundary of this date (UTC). None date
format xml Specify output format. Accepted values are json, xml, and text. More Help json string
/combine options (also takes Common options)
instconfig sensor_CEADASE_CPHM-500_LP1_PG8_SG2250_STgroundVel:
datalogger_EQMet_SMA_PG1_FR50
Specify the instrument configuration(s) for the response file(s) requested. Separating two instrument configuration strings with a comma (,) returns individual responses for each instrument in the list. Joining multiple instrument configuration strings with a colon (:) returns a single response file that cascades each joined instrument in order.
Accepts lists when format is specified as a .zip file, but not wildcards.

NOTE: To receive a zip archive of the full NRL in a directory structure similar to the original NRL, specify full_NRL_v2_zip for this parameter and choose either resp.zip or stationxml.zip as the format:
curl -JLO ‘http://service.iris.edu/irisws/nrl/1/combine?nodata=404&instconfig=full_NRL_v2_zip&format=resp.zip’ More Help
None string
element sensor Filter by element type. Current elements include sensor, datalogger, integrated and soh. Accepts wildcards and lists. None string
man[ufacturer] EQMet Filter by manufacturer. Accepts wildcards and lists. None string
model CMG* Filter by model. Accepts wildcards and lists. None string
updatedsince 2021-01-01 Filter for information updated on or since the beginning day boundary of this date (UTC). None date
net[work] IU Specify a network code to include in the response file. XX string
sta[tion] ANMO Specify a station code to include in the response file. YY string
loc[ation] 00 Specify a location code to include in the response file. 00 string
cha[nnel] BHZ Specify a channel code to include in the response file. ZZZ string
starttime 2020-01-01[T00:00:00.000000] Specify an epoch start date to include in the response file. 1970-01-01T00:00:00Z date/time
endtime 2021-01-01[T00:00:00.000000] Specify an epoch end date to include in the response file. None date/time
format stationxml-resp Specify output format. Accepted values are stationxml, stationxml-resp, resp, stationxml.zip, stationxml-resp.zip, resp.zip. More Help stationxml string
admin For internal use during testing. None string
/prefix-lookup options (also takes Common options)
format xml Specify output format. Accepted values are json, xml, and text. More Help json string

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.


Can't find your instrument?

If you cannot find the instrument you’re looking for, please send a note with its manufacturer, model and element type (sensor, datalogger, etc.) to:
data-help@earthscope.org
If it isn’t in the Library, we’ll try to add it.

Lists

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

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:
data-help@earthscope.org
We will address your issue as soon as possible.

IRISWS nrl web service