International Federation of Digital Seismograph Networks
Sign in

Help

Contents

The FDSN data center registry contains a listing of data centers, which (web) services are offered, and which data sets are available from each.

Data centers maintain their own entries after completing the data center registration (login required).

In addition to the human-readable data center listings, a web service is available for querying and retrieving registry entries in a machine-readable format.

Registry entries are exchanged in a JSON-based FDSN datacenter-registry schema.

Web Service API

A web service API is allows for programmatic search and access to registry entries. Registry entries are returned in a JSON-based FDSN datacenter-registry schema.

The default query returns high-level details of the complete registry:
https://www.fdsn.org/ws/datacenters/1/query

This API accepts a few query parameters:

The name parameter limits results to the named data center, default is all data centers:
https://www.fdsn.org/ws/datacenters/1/query?name=IRISDMC

The services parameter limits results to entries with services that match the given glob-style pattern, default is all services:
https://www.fdsn.org/ws/datacenters/1/query?services=*-dataselect-1

The includedatasets parameter controls whether the results include detailed information about the data sets offered by each center, default is false:
https://www.fdsn.org/ws/datacenters/1/query?includedatasets=true

Network operators

Network operators need to coordinate with data centers that offer their data if they wish see changes in priority, etc. Contact information for each data center is available from the data center listings.

Registry Management

Each data center is responsible for maintaining its own entry in the registry. One or more administrators (login account required) may be designated by a data center as authorized to update their entry.

There are three different methods for updating a center’s entry, but each data center can use only one of these at a time. This update method is set (and can be changed) as part of the data center registration (login required). Trying to update the registry through a different method will produce an error.

Entries can only be updated by those logged in with accounts that have been identified as administrators of the data center entry.

The three methods of updating an entry are described below:

Web Form

The simplest method, suitable for most data centers, is a web form through which you enter high level details, which of the FDSN web services are offered, and which data sets are available at the network level. This form can be found by data center administrators on the detail page for a center’s entry as an “Edit” button at the top of the page.

The main limitations are:

  • Data sets available can only be defined at the whole network-level
  • All data set priorities are set to 1 — this must be the primary data center for all listed networks
  • Only the standardized FDSN web services can be specified

Harvest

With this mechanism, the data center generates its own registry JSON file, and makes this available at a URL. The FDSN website collects this URL daily and updates its own version if there are any changes.

Because it may take several hours for changes to be reflected here, data center administrators also have the option to manually trigger an update from the data center detail page.

Push (POST)

As with the harvest method, the data center builds its own registry JSON. This registry data is then submitted via HTTP POST to the registry.

For example, using curl:

curl -L --data-binary @data.json https://www.fdsn.org/ws/datacenters/1/update?token=TOKEN
  • data.json is a file containing the registry JSON
  • TOKEN is a security token set by the data center administrator

On success, this returns an HTTP 200 status code. Otherwise, it returns a 400 status code, with a description of the error in the body of the response.

The security token is set as part of the data center registration. This can be any sequence of characters; there is an auto-generate option which generates a random character sequence. The token should be kept private.

For flexibility, the request can be structured in 2 different ways:

  1. The registry data is sent as the POST body, with the token provided as a GET parameter
    This is for the case where the registry is stored in a file, and a tool like curl is used to post it, as in the example above.
  2. Both registry and token are sent as POST parameters
    This is a more straightforward method, but it doesn’t allow the registry data to be piped straight from a file. Instead both registry and token must be encoded into a standard POST format (eg. application/x-www-form-urlencoded or multipart/form-data) as “registry” and “token” respectively.

Data set priorities

Data centers may declare a priority for each data set entry. These priorities are to be used to determine the primary, secondary, etc. data center for specific data.

Each data set entry may specify a network, station, location, channel, start time, end time and priority. Each of these are optional. In the case of identifiers and time range, when missing should be interpreted as “all”, i.e. inclusively. In the case of priority, when missing should be interpreted as “unknown” and less than any explicitly specified priority.

The same priority cannot be declared for the same data set by more than one center. The registry includes conflict detection to avoid the case where the same priority is claimed by multiple data centers for the same data.

NOTE: data centers that do not include priority designations for data they own, or are otherwise delegated to serve, must understand that users of the registry will use their own logic to determine from which data center to request the data. This only applies to cases where the same data exist at multiple data centers.

Service names

A registry entry allows the designation of web services for repositories. Each service entry requires a concise, but descriptive, name for the service that will be used to uniquely identify the service within the repository. The name can only contain ASCII alphanumeric characters, dash and underscore. Service names starting with fdsnws are reserved for FDSN-standardized services.

These names are recommended to be the service name with the major version of the API they offer appended in the following pattern:

<name>-<majorversion>

For example: fdsnws-dataselect-1, fdsnws-station-1, fdsnws-event-1, fdsnws-availability-1 are the names for FDSN 1.x web service implementations.

This allows users of the registry to potentially identify the baseline API expectations for entries. For full version details and support of optional features, the services themselves must be consulted as the authoritative source. The major version numbers are optional, in which case the service must be consulted for that information.

These service names are also used in the service entry’s compatible-with field, in particular for services that are compatible with FDSN-standardized services.