Description
The NRL web service returns instrument response information from the Nominal Response Library 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, similar to that used by the original Nominal Response Library. Differences in convention used by the nrl web service to describe responses using RESP files are detailed in the document Nominal Response Library Versions.
- 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’ |
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.
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:
[email protected]
We will address your issue as soon as possible.
