Help: nrl v.1

Description

Overview of Service

The nrl web service provides access to the IRIS Nominal Response Library (NRL) – an “authoritative” set of manufacturers’ recommended nominal instrument responses for use in building metadata (Templeton, 2017).

The NRL is now in its second version. While the focus of the NRL has been on seismic instrumentation, this new version has the flexibility to include additional types of geophysical instrumentation. The original NRL (version 1) consisted of RESP files, accessible by HTTP, that observed certain conventions when describing responses. The nrl web service found here accesses a newer version of the Library (version 2) whose contents reside in a database as XML and use slightly different representation conventions. These differences are detailed in the document Nominal Response Library Versions.

The service has three query methods – /catalog for exploring NRL content, /combine for requesting response files, and /prefix-lookup for retrieving the descriptions and logic tree questions for two-letter instrument configuration prefixes. Responses can be requested in several formats and combinations that include the full NRL as a zipped directory structure similar to that used by the original Nominal Response Library.

Retrieving Responses

Retrieving individual instrument responses from the nrl web service is a two-step process:

1. retrieve a description of your instrument’s configuration from the NRL by querying the service’s /catalog query method or by using the NRL web page (https://ds.iris.edu/ds/nrl/)
2. pass the instrument configuration description to the /combine query method to receive an instrument response file.

Instrument configuration descriptions are strings containing your instrument’s response element type (e.g., sensor or datalogger), manufacturer, model and configuration parameters. For example, a Guralp CMG-3T sensor with sensitivity 1500 V/m/s and a passband of 30 seconds to 50 Hz has the instrument configuration sensor_Guralp_CMG-3T_LP30_HF50_SG1500_STgroundVel. See /catalog Options below for tips on querying for these descriptions by response element type, manufacturer, and/or model name.

Instrument configurations can be passed to the /combine query method as

• one configuration (one response file is returned)
• a comma-separated list of configurations (one response file is returned for each configuration and bundled as a .zip file)
• one colon-separated cascade of configurations (one response file is returned describing the full cascade)
• a comma-separated list of cascaded configurations (one response file is returned for each cascade and bundled as a .zip file)

Alternatively, responses can be retrieved by specifying element, manufacturer, and/or model. Querying in this manner will return response files for all matching configurations.

When a query returns multiple response files, the user must select the format from one of the .zip options.

Full NRL Download

The nrl web service provides a zipped directory structure containing the full NRL and auxiliary files for local use, similar that used by IRIS’s PDCC software and its NRLTool utility. It can be requested in either resp.zip or stationxml.zip formats. A RESP file for a sensor with instconfig sensor_Streckeisen_STS-3_LP120_SG1500_STgroundVel would unpack as NRL/sensor/Streckeisen/STS-3_LP120_SG1500_STgroundVel.resp

The standardization approach to representing responses differs somewhat from that used by the original NRL. Those differences are described in the document Nominal Response Library Versions. To request this download, query the /combine query method using instconfig=full_NRL_v2_zip:

http://service.iris.edu/irisws/nrl/1/combine?instconfig=full_NRL_v2_zip&format=resp.zip&nodata=404
or
http://service.iris.edu/irisws/nrl/1/combine?instconfig=full_NRL_v2_zip&format=stationxml.zip&nodata=404

These .zip files are cached and updated every 24 hours.

If the full NRL is requested using the updatedsince option, the zip file will contain only responses added or modified since the beginning of that date along with all auxiliary text files.

Query Usage

Common Options

The following query parameters are accepted by both the /catalog and /combine query methods.

nodata

Use nodata to choose which HTTP status code the service returns when the query is successful but there is no data to return. Although status code 204 is defined as describing this case, browsers receiving status code 204 do not refresh their previous contents, so it can be difficult to tell that the query completed successfully. Selecting status code 404 when there is no data to return causes the browsers to refresh and display a blank or nearly blank page. Note that the URL Builder appends &nodata=404 to each query that it builds.

• 204
  Do not refresh the browser window if no data is returned.
• 404
  Refresh the browser window, leaving a blank or nearly blank screen if no data is returned.

/catalog Options

The /catalog query method accepts these parameters in addition to common options.

element

The element filter returns only information matching the specified response element type(s). Wildcards (* and ?) and comma-separated lists are allowed. Omitting this filter is equivalent to specifying element=*. Results matching wildcards are returned as a comma-separated list.

This filter may be used in combination with the manufacturer and model filters. Element names are case sensitive; the following query will return a list of available element types:

http://service.iris.edu/irisws/nrl/1/catalog?level=element&format=text&nodata=404

manufacturer

The manufacturer filter returns only information matching the specified instrument manufacturer(s). Wildcards (* and ?) and comma-separated lists are allowed. Omitting this filter is equivalent to specifying manufacturer=*. Results matching wildcards are returned as a comma-separated list.

This filter may be used in combination with the element and model filters. Manufacturer names are case sensitive; the following query will return a list of available manufacturer names:

http://service.iris.edu/irisws/nrl/1/catalog?level=manufacturer&format=text&nodata=404

model

The model filter returns only information matching the specified instrument model(s). Wildcards (* and ?) and comma-separated lists are allowed. Omitting this filter is equivalent to specifying model=*. Results matching wildcards are returned as a comma-separated list.

This filter may be used in combination with the element and manufacturer filters. Model names are case sensitive; the following query will return a list of available model names for a given manufacturer (CEADASE in this case):

http://service.iris.edu/irisws/nrl/1/catalog?manufacturer=CEADASE&level=model&format=text&nodata=404

updatedsince

This parameter filters responses to include only those loaded into the NRL database since the beginning of the specified date.

level

Users can use level to request one of four levels of NRL content:

• element: the names (all formats) and details (json and xml) for each response element type requested
• manufacturer: element-level information plus the names (all formats) and details (json and xml) for each manufacturer/response element type combination requested
• model: manufacturer-level information plus the names (all formats) and details (json and xml) for each model/manufacturer/response element type combination requested
• configuration: model-level information plus instrument configuration strings, configuration parameters (all formats) and details (json and xml) for each configuration/model/manufacturer/response element type combination requested

Details refer to additional information a user may need in order to locate the correct response for their instrument. Details do not exist in all instances, but they are included when available.

format

The nrl service /catalog query method offers the following output formats for viewing or parsing NRL content. Each format lists the results from each of four available levels of detail for a sample query specifying element=datalogger, manufacturer=GeoDevice and model=EDAS-24IP.

• JSON
  JSON (JavaScript Object Notation) is a human readable data format frequently used in web service communication.
  • level=element lists all element types satisfying the filters in the query.
    

    {
      "NRLCatalog": {
        "formatversion": 1.0,
        "detail": "Descriptive text here.",
        "element": [
          {
            "name": "datalogger",
            "detail": "More descriptive text."
          }
        ]
      }
    }
    

  • level=manufacturer lists all manufacturers satisfying the filters in the query.
    

    {
      "NRLCatalog": {
        "formatversion": 1.0,
        "detail": "Descriptive text here.",
        "element": [
          {
            "name": "datalogger",
            "detail": "More descriptive text.",
            "manufacturer": [
              {
                "name": "GeoDevice",
                "detail": ""
              }
            ]
          }
        ]
      }
    }
    

  • level=model lists all models satisfying the filters in the query.
    

    {
      "NRLCatalog": {
        "formatversion": 1.0,
        "detail": "Descriptive text here.",
        "element": [
          {
            "name": "datalogger",
            "detail": "More descriptive text",
            "manufacturer": [
              {
                "name": "GeoDevice",
                "detail": "",
                "model": [
                  {
                    "name": "EDAS-24IP",
                    "detail": ""
                  }
                ]
              }
            ]
          }
        ]
      }
    }
    

  • level=configuration lists all configurations satisfying the filters in the query. This is an abridged list.
    

    {
      "NRLCatalog": {
        "formatversion": 1.0,
        "detail": "Descriptive text here.",
        "element": [
          {
            "name": "datalogger",
            "detail": "More descriptive text.",
            "manufacturer": [
              {
                "name": "GeoDevice",
                "detail": "",
                "model": [
                  {
                    "name": "EDAS-24IP",
                    "detail": "",
                    "configuration": [
                      {
                        "instconfig": "datalogger_GeoDevice_EDAS-24IP_FV2.5Vp_FR10_FPMixed",
                        "version": "2021-04-21T07:00:00",
                        "description": "GeoDevice; EDAS-24IP; Full-Scale_Voltage 2.5Vp; Final_Sample_Rate 10 Hz; Final_Filter_Phase Mixed",
                        "parameters": {
                          "Full-Scale_Voltage": "2.5Vp",
                          "Final_Sample_Rate": "10 Hz",
                          "Final_Filter_Phase": "Mixed"
                        }
                      },
                      {
                        "instconfig": "datalogger_GeoDevice_EDAS-24IP_FV2.5Vp_FR10_FPLinear",
                        "version": "2021-04-21T07:00:00",
                        "description": "GeoDevice; EDAS-24IP; Full-Scale_Voltage 2.5Vp; Final_Sample_Rate 10 Hz; Final_Filter_Phase Linear",
                        "parameters": {
                          "Full-Scale_Voltage": "2.5Vp",
                          "Final_Sample_Rate": "10 Hz",
                          "Final_Filter_Phase": "Linear"
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    }
    

• text
  A tabular comma-separated value (csv) listing with headers. Text output does not return all the information included in the JSON and XML output. It does not include the descriptive detail information.
  • level=element lists all element types satisfying the filters in the query.
    

    "Element"
    "datalogger"
    

  • level=manufacturer lists all manufacturers satisfying the filters in the query.
    

    "Element","Manufacturer"
    "datalogger","GeoDevice"
    

  • level=model lists all models satisfying the filters in the query.
    

    "Element","Manufacturer","Model"
    "datalogger","GeoDevice","EDAS-24IP"
    

  • level=configuration lists all configurations satisfying the filters in the query. (This is an abridged list.)
    

    "Element","Manufacturer","Model","Description","Instconfig"
    "datalogger","GeoDevice","EDAS-24IP","GeoDevice; EDAS-24IP; Full-Scale_Voltage 2.5Vp; Final_Sample_Rate 10 Hz; Final_Filter_Phase Mixed","datalogger_GeoDevice_EDAS-24IP_FV2.5Vp_FR10_FPMixed"
    "datalogger","GeoDevice","EDAS-24IP","GeoDevice; EDAS-24IP; Full-Scale_Voltage 2.5Vp; Final_Sample_Rate 10 Hz; Final_Filter_Phase Linear","datalogger_GeoDevice_EDAS-24IP_FV2.5Vp_FR10_FPLinear"
    

• XML
  XML (Extensible Markup Language) is a human- and machine-readable markup language.
  • level=element lists all element types satisfying the filters in the query.
    

    <NRLCatalog>
     <formatversion>1.0</formatversion>
     <detail>Descriptive text here. </detail>
     <element>
      <name>datalogger</name>
      <detail>More descriptive text. </detail>
     </element>
    </NRLCatalog>
    

  • level=manufacturer lists all manufacturers satisfying the filters in the query.
    

    <NRLCatalog>
     <formatversion>1.0</formatversion>
     <detail>Descriptive text here. </detail>
     <element>
      <name>datalogger</name>
      <detail>More descriptive text. </detail>
       <manufacturer>
        <name>GeoDevice</name>
        <detail/>
       </manufacturer>
     </element>
    </NRLCatalog>
    

  • level=model lists all models satisfying the filters in the query.
    

    <NRLCatalog>
     <formatversion>1.0</formatversion>
     <detail>Descriptive text here. </detail>
     <element>
      <name>datalogger</name>
      <detail>More descriptive text. </detail>
       <manufacturer>
        <name>GeoDevice</name>
        <model>
         <name>EDAS-24IP</name>
         <detail/>
        </model>
        <detail/>
       </manufacturer>
     </element>
    </NRLCatalog>
    

  • level=configuration lists all configurations satisfying the filters in the query. (This is an abridged list.)
    

    <NRLCatalog>
     <formatversion>1.0</formatversion>
     <detail>Descriptive text here. </detail>
     <element>
      <name>datalogger</name>
      <detail>More descriptive text. </detail>
       <manufacturer>
        <name>GeoDevice</name>
        <model>
         <configuration>
          <instconfig>datalogger_GeoDevice_EDAS-24IP_FV2.5Vp_FR10_FPMixed</instconfig>
          <description>GeoDevice; EDAS-24IP; Full-Scale_Voltage 2.5Vp; Final_Sample_Rate 10 Hz; Final_Filter_Phase Mixed</description>
          <version>2021-04-21T07:00:00</version>
          <parameters>
           <Full-Scale_Voltage>2.5Vp</Full-Scale_Voltage>
           <Final_Sample_Rate>10 Hz</Final_Sample_Rate>
           <Final_Filter_Phase>Mixed</Final_Filter_Phase>
          </parameters>
         </configuration>
         <configuration>
          <instconfig>datalogger_GeoDevice_EDAS-24IP_FV2.5Vp_FR10_FPLinear</instconfig>
          <description>GeoDevice; EDAS-24IP; Full-Scale_Voltage 2.5Vp; Final_Sample_Rate 10 Hz; Final_Filter_Phase Linear</description>
          <version>2021-04-21T07:00:00</version>
          <parameters>
           <Full-Scale_Voltage>2.5Vp</Full-Scale_Voltage>
           <Final_Sample_Rate>10 Hz</Final_Sample_Rate>
           <Final_Filter_Phase>Linear</Final_Filter_Phase>
          </parameters>
         </configuration>
         <name>EDAS-24IP</name>
         <detail/>
        </model>
        <detail/>
       </manufacturer>
     </element>
    </NRLCatalog>
    

/combine Options

instconfig

The instrument configuration string (instconfig) describes, in order, the

• response element type – currently sensor and datalogger, this category can expand to include integrated instruments, state of health channels, amplifiers, filters and more,
• manufacturer,
• model,
• configuration parameters – each parameter is preceded with a two-letter prefix (see below),
  of each instrument in the NRL.

Examples

• A Streckeisen STS-2 velocity sensor with a generation 3 electronics, a 1500 V/m/s sensitivity and a long-period corner of 120 seconds has instconfig string sensor_Streckeisen_STS-2_EG3_SG1500_LP120_STgroundVel
• A Lunitek ATLAS datalogger with a 0.625 peak-to-peak Voltage, final sample rate of 100 Hz and a linear final phase filter has instconfig string datalogger_Lunitek_ATLAS_FV0.625Vpp_FR100_FPLinear
• This special case instconfig will return a .zip file of the full NRL library: full_NRL_v2_zip

Joining multiple instrument configuration strings with a colon (:) returns a single response file that cascades each joined instrument in order.

element

The element filter returns only information matching the specified response element type(s). Wildcards (* and ?) and comma-separated lists are allowed. Omitting this filter is equivalent to specifying element=*. Results matching wildcards are returned as a comma-separated list.

This filter may be used in combination with the manufacturer and model filters. Element names are case sensitive; the following query will return a list of available element types:

http://service.iris.edu/irisws/nrl/1/catalog?level=element&format=text&nodata=404

manufacturer

The manufacturer filter returns only information matching the specified instrument manufacturer(s). Wildcards (* and ?) and comma-separated lists are allowed. Omitting this filter is equivalent to specifying manufacturer=*. Results matching wildcards are returned as a comma-separated list.

This filter may be used in combination with the element and model filters. Manufacturer names are case sensitive; the following query will return a list of available manufacturer names:

http://service.iris.edu/irisws/nrl/1/catalog?&level=manufacturer&format=text&nodata=404

model

The model filter returns only information matching the specified instrument model(s). Wildcards (* and ?) and comma-separated lists are allowed. Omitting this filter is equivalent to specifying model=*. Results matching wildcards are returned as a comma-separated list.

This filter may be used in combination with the element and manufacturer filters. Model names are case sensitive; the following query will return a list of available model names for a given manufacturer (CEADASE in this case):

http://service.earthscope.org/irisws/nrl/1/catalog?&manufacturer=CEADASE&level=model&format=text&nodata=404

updatedsince

This parameter filters responses to include only those loaded into the NRL database since the beginning of the specified date.

network, station, location, channel

These optional parameters allow the user to supply a network, station, location and/or channel code to be written into the returned response file if the output format is stationxml, stationxml.zip, resp or resp.zip. (Default is XX.YY.00.ZZZ)

starttime, endtime

These parameters allow the user to supply an epoch start and/or end time to be written into the returned response file when the output format is stationxml, stationxml.zip, resp or resp.zip. (Default start time is 1970-01-01T00:00:00; the end time defaults to unset)

format

The nrl service /combine query method offers these output formats for receiving instrument response information:

• stationxml
  FDSN stationXML 1.1. If requested in a browser, the file contents will display in the browser. Otherwise, a response file for instconfig sensor_Streckeisen_STS-3_LP120_SG1500_STgroundVel would download as irisws-nrl_YYYY-MM-DDTHH_MM_SSZ.stationxml, unless the download method overrides this default name.

• stationxml.zip
  One or more FDSN stationXML 1.1 files zipped and downloaded to the user. A response file for instconfig sensor_Streckeisen_STS-3_LP120_SG1500_STgroundVel would unpack as irisws-nrl_YYYY-MM-DDTHH-MM-SSZ/sensor/Streckeisen/STS-3_LP120_SG1500_STgroundVel.xml

• resp
  SEED-based RESP format. If requested in a browser, the file contents will display in the browser. Otherwise, a response file for instconfig sensor_Streckeisen_STS-3_LP120_SG1500_STgroundVel would download as irisws-nrl_YYYY-MM-DDTHH_MM_SSZ.resp, unless the download method overrides this default name.

• resp.zip
  One or more RESP files zipped and downloaded to the user. A response file for instconfig sensor_Streckeisen_STS-3_LP120_SG1500_STgroundVel would unpack as irisws-nrl_YYYY-MM-DDTHH-MM-SSZ/sensor/Streckeisen/STS-3_LP120_SG1500_STgroundVel.resp

• stationxml-resp
  StationXML-Response, a response-only subset of FDSN stationXML 1.1 (schema). If requested in a browser, the file contents will display in the browser. Otherwise, a response file for instconfig sensor_Streckeisen_STS-3_LP120_SG1500_STgroundVel would download as irisws-nrl_YYYY-MM-DDTHH_MM_SSZ.response.xml, unless the download method overrides this default name.

• stationxml-resp.zip
  One or more stationXML-Response files zipped and downloaded to the user. A response file for instconfig sensor_Streckeisen_STS-3_LP120_SG1500_STgroundVel would download as irisws-nrl_YYYY-MM-DDTHH-MM-SSZ/sensor/Streckeisen/STS-3_LP120_SG1500_STgroundVel.response.xml

When requesting multiple instrument responses, the service will zip each as a separate response file – you must select one of the three .zip formats in this case. Zip files will automatically download. Note that the full NRL library download option is only available as stationxml.zip and resp.zip.

/prefix-lookup Options

The /prefix-lookup query method accepts these parameters in addition to common options.

format

The nrl service /prefix-lookup can be displayed as json, text or xml.

• JSON
  JSON (JavaScript Object Notation) is a human readable data format frequently used in web service communication.
  

  [
    {
      "prefix": "AL",
      "description": "Approx Lower Bound",
      "question": "What is the input amplitude lower bound for this approximation?"
    },
    {
      "prefix": "AU",
      "description": "Approx Upper Bound",
      "question": "What is the input amplitude upper bound for this approximation?"
    },
  ]
  

• text
  A tabular comma-separated value (csv) listing with headers.
  

  prefix,description,question
  AL,"Approx Lower Bound","What is the input amplitude lower bound for this approximation?"
  AU,"Approx Upper Bound","What is the input amplitude upper bound for this approximation?"
  

• XML
  XML (Extensible Markup Language) is a human- and machine-readable markup language.
  

  <IdentifierCodes>
   <item>
    <prefix>AL</prefix>
    <description>Approx Lower Bound</description>
    <question>What is the input amplitude lower bound for this approximation?</question>
    </item>
    <item>
   <prefix>AU</prefix>
    <description>Approx Upper Bound</description>
    <question>What is the input amplitude upper bound for this approximation?</question>
   </item>
  </IdentifierCodes>
  

Post Examples

To submit a more complex request as a list of parameters, a request file may be POSTed to the nrl service combine query method (http://service.iris.edu/irisws/nrl/1/combine).

The following file (instconfig.request) requests responses for a list of instrument configuration parameters that are returned as zipped RESP files:

 
$ cat instconfig.request
format=resp.zip
nodata=404
instconfig=sensor_CEADASE_CPHM-500_LP1_PG1_SG2250_STgroundVel
instconfig=sensor_CEADASE_CPHM-500_LP2_PG1_SG2250_STgroundVel
instconfig=sensor_CEADASE_LPHA_FBAcceleration_LPDC_HF1_SG2533_STgroundAccel
instconfig=sensor_CEADASE_MB2000_LP50_HF4_SG0.02_STairPressure

You can submit this request using curl:

curl --data-binary @./instconfig.request -s -D - http://service.iris.edu/irisws/nrl/1/combine -JLO

We recommend always using the -L option to allow curl to follow HTTP redirections specified by our systems. The DMC uses HTTP redirection during maintenance to keep servicing requests.

This file (nrl_element.request) requests responses for all flavors of CEADASE’s CPHM-500 model sensor, again returned as zipped RESP files.

 
$ cat nrl_element.request
format=resp.zip
nodata=404
element=sensor
man=CEADASE
model=CPHM-500

Last, the file nrl_instconfig_cascaded.request uses a colon to request a cascaded sensor and datalogger response as stationxml with specified values for the network, station, location code, channel and start time included. In this case, the end time is left open (omitted).

$ cat nrl_element.request
format=stationxml
nodata=404
instconfig=sensor_CEADASE_CPHM-500_LP1_PG1_SG2250_STgroundVel:datalogger_Kinemetrics_Dolomite_PG2_FV40Vpp_FR50_FPNon-causal
network=XY
station=MYSTN
location=11
channel=SHZ
starttime=2021-06-01

Problems with this service?