We have updated our FDSN event webservice. The service is now providing the (optional) ability to filter by "Event Type", and this additional information is now provided in text format. Your usual requests should still work with no required change, but please contact us here or via email info@geonet.org.nz if you need help.
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.
GeoNet FDSN webservices provide the dataselect, station and event queries options.
We have split our webservice in two separate services:
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.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.
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).
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.
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.
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
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.
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.
The same request can be fetched in text format output using format|text at the end of the URL query:
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.
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" |
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.
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:
#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:
#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 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
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
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.