FDSN webservice

The International Federation of Digital Seismograph Networks (FDSN) has defined web services for accessing waveform, station and event information. Data centres adopting these, such as GeoNet and IRIS, will be able to offer their data in a consistent way.

The FDSN specification defines an internationally recognized, standard interface. Programs that access data via these FDSN web services should also be compatible with any other data centre implementing FDSN interfaces.

New webservice coming!


GeoNet is currently in the process of upgrading our FDSN webservices. Our current service at service.geonet.org.nz is only supporting station and waveform requests.

Our new service is in beta and can be tested using beta-service.geonet.org.nz. It will include all three services and will be more robust. If you test our beta please provide us with feedback, especially if you can break it! Please include an example of your request with your feedback. Please provide feedback by raising an issue in our github repository.

Where is the beta FDSN webservice at now:

Service Comment Return format
station Full station service, including historical stations xml or text
event Full event service QuakeML
dataselect Full waveform data is available miniseed

General Information


GeoNet uses the following address to support our implementation service.geonet.org.nz

The syntax of the queries can be displayed at:

The following parameters are available for the GeoNet FDSN webservices.

Station Service

Parameter Default/Units/Example Description
start[time] 2016-06-02T12:00:00.000 station metadata returned on or after start time
end[time] 2016-06-03T12:00:00.000 station metadata returned on or before end time
startbefore 2016-06-02T12:00:00.000 station metadata starting before this time
startafter 2016-06-02T12:00:00.000 station metadata starting after this time
endbefore 2016-06-02T12:00:00.000 station metadata ending before this time
endafter 2016-06-02T12:00:00.000 station metadata ending after this time
net[work] NZ Network code
sta[tion] OPZ Specify one or more station codes. For multiple stations use comma separated list or use wildcards
loc[ation] 10 Specify one or more location identifiers. For multiple identifiers use comma separated list or wildcards
channel HHZ Specify one or more channel codes. For multiple channels use a comma separated list or wildcards
minlat[itude] Degrees Southern boundary for rectangular search
maxlat[itude] Degrees Northern boundary for rectangular search
minlon[gitude] Degrees Western boundary for rectangular search
maxlon[gitude] Degrees Eastern boundary for rectangular search
lat[itude] Degrees latitude of centre point for circular search
lon[gitude] Degrees longitude of centre point for circular search
minradius Degrees minimum distance for circular search
maxradius Degrees maximum distance for circular search
level channel Specify level of detail, options include: "network", "station", "channel" or "response"
includerestricted FALSE There is no restricted data in webservice
nodata 204 Specify which HTTP status code is returned when no data is found, "204 or"404"
format xml Specify the output format, "xml" or "text"

Event Service

Parameter Default/Units/Example Description
start[time] 2016-06-02T12:00:00.000 events returned on or after start time
end[time] 2016-06-03T12:00:00.000 events metadata returned on or before end time
minlat[itude] Degrees Southern boundary for rectangular search
maxlat[itude] Degrees Northern boundary for rectangular search
minlon[gitude] Degrees Western boundary for rectangular search
maxlon[gitude] Degrees Eastern boundary for rectangular search
lat[itude] Degrees latitude of centre point for circular search
lon[gitude] Degrees longitude of centre point for circular search
minradius Degrees minimum distance for circular search
maxradius Degrees maximum distance for circular search
mindepth Kilometres events will be returned if they are deeper than depth specified
maxdepth Kilmometres events will be returned if they are shallower than depth specified
minmag[nitude] 5.6 events will be returned if they are larger than magnitude specified
maxmag[nitude] 7.5 events will be returned if they are smaller than magnitude specified
orderby time output will have events sorted by any of the following options: "time", "time-asc", "magnitude" or "magnitude-asc"
eventid 2016p858000 Unique event identifier set by GeoNet
nodata 204 Specify which HTTP status code is returned when no data is found, "204 or"404"
updateafter 2016-06-02-12:00:00.000 Limit events to those updated after the specified time

Data Select Service

Parameter Default/Units/Example Description
start[time] 2016-06-02T12:00:00.000 waveforms will begin on or slightly before* starttime
end[time] 2016-06-03T12:00:00.000 waveforms will end on or slightly after* endtime
net[work] NZ Network code
sta[tion] OPZ Specify one or more station codes. For multiple stations use comma separated list or use wildcards
loc[ation] 10 Specify one or more location identifiers. For multiple identifiers use comma separated list or wildcards
channel HHZ Specify one or more channel codes. For multiple channels use a comma separated list or wildcards
format miniseed Service only returns miniseed format. For converters to other formats see IRIS SeisCode
nodata 204 Specify which HTTP status code is returned when no data is found, "204 or"404"

* This is a minor deviation from the FDSN specification to return more data than is required if the record length does not start at the starttime or end at the endtime exactly. We do not reprocess, trim or pad the data for performance reasons. You can easily trim the data in your processing to get the record the exact length required.

Service Limits and known issues

We have done our best to make this service fast and scalable. However, it is still best not to ask for too much data in a single request. The larger the request the longer it will take to complete. If a large request fails, it will have to be resubmitted. To avoid resubmitting large requests you can break up them into smaller ones, then if a failure occurs you just resubmit the small request.

Webservice connections can break if no data is transmitted after 5-10 minutes. The HTTP return code for large requests can return a false positive code (200) because of the time it can take for the webservice to start returning data. Therefore the codes can not be relied on for large requests that could take more than 5-10 minutes to begin returning data.

It is also best not to make lots of very small data requests as every time a request is made a new connection is established and that can effect performance. Best practice is to combine selections from the same stations and put them in the same request or for selections over the same time period.

Webservice compatibility with SeisComP3

A bug has been identified in SeisComP3 that causes problems when trying to use GeoNet's FDSN webservice as a data source. The bug has been fixed in the latest code available from the SeisComP3 Github repo.

Examples

Data Select:

Request waveforms from a strong motion sensor (location 20) at station TDHS for all channels and sample rates (channel ?N?) for the period starting from 2016-09-01 at 16:37 for 300 seconds.

https://service.geonet.org.nz/fdsnws/dataselect/1/query?station=TDHS&location=20&channel=?N?&starttime=2016-09-01T16:37:00.000&endtime=2016-09-01T16:42:00.000

This example uses Curl to download data from a single query to the file test.mseed:

curl "http://service.geonet.org.nz/fdsnws/dataselect/1/query?network=NZ&station=CHST&location=01&channel=LOG&starttime=2017-01-09T00:00:00&endtime=2017-01-09T23:00:00" -o test.mseed
This example uses **multiple queries** using POST, in this case saving to test_post.mseed:
curl -v --data-binary @post_input.txt http://service.geonet.org.nz/fdsnws/dataselect/1/query -o test_post.mseed
The contents of post_input.txt:
NZ ALRZ 10 EHN 2017-01-09T00:00:00 2017-01-09T02:00:00
NZ ALRZ 10 AC\* 2017-01-02T00:00:00 2017-01-10T00:00:00
NZ ALRZ 10 B?  2017-01-09T00:00:00 2017-01-10T00:00:00

Event:

Request event information for the Kaikoura earthquake. This is a single event request using the Public ID of the earthquake.

https://service.geonet.org.nz/fdsnws/event/1/query?eventid=2016p858000

Request information about aftershocks from the first 24-hours afterwards above M6. This searches the catalogue and retrieves all available events.

https://service.geonet.org.nz/fdsnws/event/1/query?minmagnitude=6&starttime=2016-11-13T11:05:00&endtime=2016-11-14T11:05:00

Note: Event is currently only available at beta-service.geonet.org.nz

Station

Request station metadata for stations within a 0.5 degree radius from the Kaikoura earthquake epicentre.

https//service.geonet.org.nz/fdsnws/station/1/query?latitude=-42.693&longitude=173.022&maxradius=0.5

Examples using Python and the Obspy module

Python and the Obspy module are commonly used in the scientific community. Below are the equivalent python examples to the URL-based ones above. Outputs are the trace, catalogue and inventory objects, they can be exported as files in various formats if needed. See Obspy documentation and Obspy tutorial for more examples and information.

In Obspy you don't need to specify the full address of GeoNet's service, i.e. service.geonet.org.nz you can simply use the FDSN client shortcut "GEONET".

Note if you want to use test the beta version replace "GEONET" with "http://beta-service.geonet.org.nz"

Requesting Waveforms:

from obspy import UTCDateTime
from obspy.clients.fdsn import Client as FDSN_Client
client = FDSN_Client("GEONET") t = UTCDateTime("2016-09-01T16:37:00.000") st = client.get_waveforms("NZ", "TDHS","20", "?N?", t, t + 300) st.plot()

Requesting Earthquake Information:

Request information for a single earthquake using it's Public ID, this example uses the M7.8 Kaikoura earthquake

cat = client.get_events(eventid="2016p858000")

Add to this the earthquakes of magnitude 6 for 24 hours following the earthquake

cat += client.get_events(starttime="2016-11-13 11:05:00.000", endtime="2016-11-14 11:00:00.000", minmagnitude=6)

Requesting Station Information

This request is for station information, down to the channel level, for stations within a 0.5 degree radius around the epicentre of the Kaikoura earthquake

inventory = client.get_stations(latitude=-42.693,longitude=173.022,maxradius=0.5, level="station")