FDSN webservice

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:

• The archive service, service.geonet.org.nz or the "GEONET" shortcut if using obspy. If you are interested in the most complete waveform data, then use this service. The waveform data is 7 days behind the present time to ensure the data is as complete as possible.
• The near real-time service, service-nrt.geonet.org.nz. This service is for providing real-time data so it could be incomplete. Data delays varies and are expected to be less than 1 minute for high frequency channels and below 5 minutes for low frequency channels. The service has the most recent waveform data but only has the last 8 days available. For anything older please use the archive service.

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:

• Station
• Data Select
• Event

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.

* 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

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
    

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
    

curl -v --data-binary @post_input.txt http://service.geonet.org.nz/fdsnws/dataselect/1/query -o test_post.mseed
    

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.

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

Examples

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

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

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

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

Examples

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.

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

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|

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, which is public to provide easy access.

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.