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.

Current webservices


GeoNet FDSN webservices provide the dataselect, station and event queries options.

We have split our webservice in two separate services:

If you have any issues you can provide feedback by raising an issue in our github repository. Please include an example of your query so that we might replicate the problem.

General Information


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

The FDSN webservices have the following services available:

These services can be used either using a URL query or a Client tool (e.g.: ObsPy).

Data Select Service:

This service allows you to retrieve waveform time series in miniSEED format. The following parameters are available for the GeoNet FDSN webservices.

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.

To retrieve large volumes of waveform time series in miniSEED format, please use our GeoNet AWS Open Data access mechanism.

Examples


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?network=NZ&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 "https://service.geonet.org.nz/fdsnws/dataselect/1/query?network=NZ&station=TDHS&location=20&channel=?N?&starttime=2016-09-01T16:37:00.000&endtime=2016-09-01T16:42:00.000" -o test.mseed
format | **xml** | Specify the output format, "xml" or "text" 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 Service:

This service returns event information in QuakeML format or text. The following parameters are available for the GeoNet FDSN webservices.

Event service is now at version 1.2 of FDSN Specifications since an upgrade in early 2023. This added the eventtype optional parameter and EventType column in the text output format.

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
eventtype earthquake Limit events to specified eventType (single or comma separated list). Allowed values follow QuakeML eventType enumeration.
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
format QuakeML Specify the output format, "xml" or "text"

* eventType values for majority of events in GeoNet catalogue are earthquake, other event or unknown if eventType is not given.

Examples


Request event information for the Kaikōura 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

The same request can be fetched in text format output using format|text at the end of the URL query:

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

EventID | Time | Latitude | Longitude | Depth/km | Author | Catalog | Contributor | ContributorID | MagType | Magnitude | MagAuthor | EventLocationName | EventType
2016p858055|2016-11-13T11:32:07|-42.246|173.673|11.3|GNS|GNS|GNS|2016p858055|M|6.2|GNS|15 km north of Kaikōura|earthquake
2016p858007|2016-11-13T11:05:14|-41.969|173.701|4.9|GNS|GNS|GNS|2016p858007|M|6.0|GNS|45 km south-west of Seddon|earthquake
2016p858021|2016-11-13T11:12:35|-42.428|173.777|5.6|GNS|GNS|GNS|2016p858021|M|6.0|GNS|5 km east of Kaikōura|earthquake
2016p858094|2016-11-13T11:52:44|-42.201|173.603|9.0|GNS|GNS|GNS|2016p858094|Mw(mB)|6.1|GNS|20 km north of Kaikōura|earthquake
2016p859524|2016-11-14T00:34:23|-42.465|173.138|5.0|GNS|GNS|GNS|2016p859524|M|6.7|GNS|25 km east of Hanmer Springs|earthquake

Request event information between 1st and 4th of April 2022, in text format output, and only returning eventTypes classified as earthquake.

https://service.geonet.org.nz/fdsnws/event/1/query?starttime=2022-01-01T00:00:00&endtime=2022-04-28T22:00:00&format=text&eventtype=earthquake

Station Service:

This service will retrieve station metadata information in a FDSN StationXML format or text format. 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 StationXML Specify the output format, "xml" or "text"

Examples


The following example is a URL query to request station metadata for stations within a 0.5 degree radius from the Kaikōura earthquake epicentre.

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

Controling the level of detail:


The station web service can return station information at multiple levels of detail. The service response time and the volume of information returned are directly related to the requested level. The level parameter controls the amount of detail included in the FDSN StationXML results with the following hierarchy:

-Network: Network level information only, network description and station count.

-Station: Station description, coordinates, time ranges and channel count. The default level.

-Channel: Channel descriptions, coordinates, time ranges, instrument descriptions and channel sensitivity.

-Response: Complete channel response information.

In the network level output, the TotalStations value is the number of stations associated with the given network entry. The following example shows an URL query for the New Zealand network in text format.

https://service.geonet.org.nz/fdsnws/station/1/query?network=NZ&level=network&format=text

#Network | Description | StartTime | EndTime | TotalStations
NZ|New Zealand National Seismograph Network|1884-02-01T00:00:00||2199

Requesting metadata in simple text format for an specific station:

https://service.geonet.org.nz/fdsnws/station/1/query?network=NZ&station=CECS&level=station&format=text

#Network | Station | Latitude | Longitude | Elevation | SiteName | StartTime | EndTime
NZ|CECS|-42.813491|173.274868|69.000000|Cheviot Emergency Centre|2002-02-23T00:00:00|

Requestion metadata for all the channels in CECS station with no time limitations:

https://service.geonet.org.nz/fdsnws/station/1/query?network=NZ&station=CECS&level=channel&format=text

#Network | Station | Location | Channel | Latitude | Longitude | Elevation | Depth | Azimuth | Dip | SensorDescription | Scale | ScaleFreq | ScaleUnits | SampleRate | StartTime | EndTime
NZ|CECS|20|HN2|-42.813491|173.274868|69.000000|0.000000|96.000000|0.000000|Accelerometer|427336.117780|1.000000|m/s**2|200.000000|2002-02-23T05:30:00|2014-12-15T20:00:00
NZ|CECS|20|HN1|-42.813491|173.274868|69.000000|0.000000|6.000000|0.000000|Accelerometer|427336.117780|1.000000|m/s**2|200.000000|2002-02-23T05:30:00|2014-12-15T20:00:00
NZ|CECS|20|HNZ|-42.813491|173.274868|69.000000|0.000000|0.000000|-90.000000|Accelerometer|427336.117780|1.000000|m/s**2|200.000000|2002-02-23T05:30:00|2014-12-15T20:00:00
NZ|CECS|20|BNZ|-42.813491|173.274868|69.000000|0.000000|0.000000|-90.000000|Accelerometer|427336.117780|1.000000|m/s**2|50.000000|2014-12-16T00:30:00|
NZ|CECS|20|BN1|-42.813491|173.274868|69.000000|0.000000|6.000000|0.000000|Accelerometer|427336.117780|1.000000|m/s**2|50.000000|2014-12-16T00:30:00|
NZ|CECS|20|BN2|-42.813491|173.274868|69.000000|0.000000|96.000000|0.000000|Accelerometer|427336.117780|1.000000|m/s**2|50.000000|2014-12-16T00:30:00|
NZ|CECS|20|HNZ|-42.813491|173.274868|69.000000|0.000000|0.000000|-90.000000|Accelerometer|427336.117780|1.000000|m/s**2|200.000000|2014-12-16T00:30:00|
NZ|CECS|20|HN1|-42.813491|173.274868|69.000000|0.000000|6.000000|0.000000|Accelerometer|427336.117780|1.000000|m/s**2|200.000000|2014-12-16T00:30:00|
NZ|CECS|20|HN2|-42.813491|173.274868|69.000000|0.000000|96.000000|0.000000|Accelerometer|427336.117780|1.000000|m/s**2|200.000000|2014-12-16T00:30:00|

It is important to remember that when the extension format|text is not used the output will be by default FDSN StationXML. Also, text formats are only supported when level is not Response.

Python and the ObsPy module

Python and the ObsPy module are commonly used in the scientific community. 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 the Near-Real Time service replace "GEONET" with "http://service-nrt.geonet.org.nz"

Some code examples can be found in our FDSN github repository. It is a public repository to provide easy access. Just follow this link:

https://github.com/GeoNet/fdsn/tree/main/examples

Channel naming for GeoNet data.

Most of the data collected and archived at the GeoNet is time series data. Each recorded stream is identified by a unique set of codes representing:

<NETWORK> <STATION> <LOCATION> <CHANNEL>

The convention for each of these codes is documented in Codes Naming Appendix

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.

We now have a solution for large data requests, and some limitations have been placed on the size of a single request that can be retrieved for a single user via FDSN. Please use the AWS Open Data access mechanism or contact us via the GeoNet Help or info@geonet.org.nz for further information on large data requests.

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 affect 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 SeisComP

A bug was identified in older SeisComP3 version that causes problems when trying to use GeoNet's FDSN webservice as a data source. Newer SeisComP versions have this bug fixed. Newest versions are available from SeisComP Github repo.