GeoNet API

Welcome to api.geonet.org.nz. The data provided here is used for the GeoNet web site and other similar services.

The GeoNet project makes all its data and images freely available. Please ensure you have read and understood our Data Policy and Disclaimer before using any of these services.

Versioning

API queries may be versioned via the Accept header. Please specify the Accept header for your request exactly as specified for the endpoint query you are using.

If you don't specify an Accept header with a version then your request will be routed to the current highest API version of the query.

Taking advantage of the API versioning will pay dividends in the future for any client that you write. We use the jq command for JSON pretty printing etc. A curl command might look like:

curl -H "Accept: application/vnd.geo+json;version=2" "http://...API-QUERY..." | jq .

You may also be able to find a browser plugin to help with setting the Accept header for requests.

Compression

The response for a query can be compressed. If your client can handle a compressed response then the reduced download size is a great benifit. Gzip compression is supported. You can request a compressed response by including gzip in your Accept-Encoding header.

Bugs

If you believe you have found a bug, please raise an issue on our Help repository.

Endpoints

Intensity

Retrieve shaking intensity information.

[GET] /intensity?type=(measured|reported)[&aggregation=(max|median)][&publicID=(publicID)]

Accept Format/Version

application/vnd.geo+json;version=2

Parameters

type
the type of shaking information, either reported or measured. If publicID is not specified the information is for the last 60 minutes.
aggregation
optional - the selected aggregation method performed on reported values where there is a distribution of values. Default is max. Only available with type=reported.
publicID
optional - a valid quake id. Returns shaking information in a time window around the quake time. Only available with type=reported.

Response

GeoJSON features with the following properties for both reported and measured queries.

mmi
the MMI measured at the point or reported in the area around the point.

For measured queries the addtional GeoJSON properites

count
the count of MMI values reported in the area of around the point.

As well as a summary of report counts by MMI.

Examples

Strong

Retrieve strong motion information for specified quake.

[GET] /intensity/strong/processed/(publicID)

Accept Format

application/json

Parameters

publicID
- a valid quake id. Returns strong motion data for the quake.

Response

GeoJSON data containing quake information and strong motion data from stations:

metadata
- metadata about the quake.
strong motion data
- GeoJSON features on strong motion data from stations.

Examples

News

A simple JSON feed of GeoNet news.

[GET] /news/geonet

Accept Format/Version

application/json;version=2

Parameters

No query parameters are required.

Response

JSON with the following properties

mlink
a link to a mobile version of the news story.
link
a link to the news story.
published
the date the story was published.
title
the title of the story.

Examples

/news/geonet

Quake

Information for a single quake

[GET] /quake/(publicID)

Accept Format/Version

application/vnd.geo+json;version=2

Parameters

publicID
A valid publicID for a quake e.g. 2014p715167

Response

GeoJSON features with the following properties:

publicID
the unique public identifier for this quake.
time
the origin time of the quake.
depth
the depth of the quake in km.
magnitude
the summary magnitude for the quake.
locality
distance and direction to the nearest locality.
MMI
the calculated MMI shaking at the closest locality in the New Zealand region.
quality
the quality of this information: best, preliminary, automatic, deleted.

Examples

/quake/2013p407387

Quake History

Location history for a single quake. Not all quakes have a location history.

[GET] /quake/history/(publicID)

Accept Version

application/vnd.geo+json;version=2

Parameters

publicID
A valid publicID for a quake e.g. 2014p715167

Response

GeoJSON features with the following properties:

publicID
the unique public identifier for this quake.
time
the origin time of the quake.
modificationTime
the modification time of this information.
depth
the depth of the quake in km.
magnitude
the summary magnitude for the quake.
locality
distance and direction to the nearest locality.
MMI
the calculated MMI shaking at the closest locality in the New Zealand region.
quality
the quality of this information: best, preliminary, automatic, deleted.

Examples

/quake/history/2013p407387

Quake Stats

Quake statistics.

[GET] /quake/stats

Accept Version

application/vnd.geo+json;version=2

Response

magnitudeCount
contains three members that summarise magnitude by count over the last 7, 28, and 365 days.
rate
contains the member perDay that gives a per day summary by count of quake occurence.

Examples

/quake/stats

Quakes

Returns quakes possibly felt in the New Zealand region during the last 365 days up to a maximum of 100 quakes.

[GET] /quake?MMI=(int)

Accept Version

application/vnd.geo+json;version=2

Parameters

MMI
request quakes that may have caused shaking greater than or equal to the MMI value in the New Zealand region. Allowable values are -1..8 inclusive. -1 is used for quakes that are to small to calculate a stable MMI value for.

Response

GeoJSON features with the following properties:

publicID
the unique public identifier for this quake.
time
the origin time of the quake.
depth
the depth of the quake in km.
magnitude
the summary magnitude for the quake.
locality
distance and direction to the nearest locality.
mmi
the calculated MMI shaking at the closest locality in the New Zealand region.
quality
the quality of this information: best, preliminary, automatic, deleted.

Examples

/quake?MMI=3

Quake CAP

Information in CAP format for a single quake.

[GET] /cap/1.2/GPA1.0/quake/(ID)

Accept Version

Queries to this endpoint are not versioned by accept header.

Parameters

ID
a valid quake CAP ID from the Quake CAP Feed.

Example Response

The response is a CAP document using the Google Public Alerts CAP v1.0 profile e.g.,

<?xml version="1.0" encoding="UTF-8"?>
    <alert xmlns="urn:oasis:names:tc:emergency:cap:1.2">
        <identifier>2.49.0.0.554.1.2015p012816.1420493554884741</identifier>
        <sender>https://geonet.org.nz</sender>
        <sent>2015-01-06T10:32:34+13:00</sent>
        <status>Actual</status>
        <msgType>Alert</msgType>
        <scope>Public</scope>
        <info>
            <language>en-NZ</language>
            <category>Geo</category>
            <event>Earthquake</event>
            <responseType>Monitor</responseType>
            <urgency>Past</urgency>
            <severity>Moderate</severity>
            <certainty>Observed</certainty>
            <onset>2015-01-06T10:31:34+13:00</onset>
            <expires>2015-01-08T10:32:34+13:00</expires>
            <senderName>GNS Science (GeoNet)</senderName>
            <headline>Quake 25 km south-west of Arthur&#39;s Pass , intensity severe, approx. M6.0, depth 5 km Tue Jan 06 2015 10:31 PM (NZDT).</headline>
            <description>A magnitude 6.0 earthquake occurred 25 km south-west of Arthur&#39;s Pass, New Zealand at Tue Jan 06 2015 10:31 PM (NZDT). The quake was 5.1 kilometres deep and the intensity was severe close to the quake.  The quake may have been felt in Arthur&#39;s Pass, Hokitika, Greymouth, Methven and surrounding localities.</description>
            <instruction>During an earthquake, if you are inside a building, move no more than a few steps, then Drop, Cover and Hold. Stay indoors until the shaking stops and you are sure it is safe to exit. If you are outdoors when the shaking starts, move no more than a few steps away from buildings, trees, streetlights and power lines, then Drop, Cover and Hold. After an earthquake, listen to your local radio stations as emergency management officials will be broadcasting the most appropriate advice for your community and situation. Expect to feel aftershocks. If you are in a damaged building, try to get outside and find a safe, open place. Use the stairs, not the elevators.</instruction>
            <web>https://geonet.org.nz/quakes/2015p012816</web>
            <contact>info@geonet.org.nz</contact>
            <parameter>
                <valueName>PublicID</valueName>
                <value>2015p012816</value>
            </parameter>
            <parameter>
                <valueName>Time</valueName>
                <value>2019-11-20T15:48:04+13:00</value>
            </parameter>
            <parameter>
                <valueName>LatitudeLongitude</valueName>
                <value>-43.06,171.25</value>
            </parameter>
            <parameter>
                <valueName>Depth</valueName>
                <value>5</value>
            </parameter>
            <parameter>
                <valueName>Magnitude</valueName>
                <value>6.0</value>
            </parameter>
            <parameter>
                <valueName>Locality</valueName>
                <value>25 km south-west of Arthur&#39;s Pass, 40 km south-east of Hokitika, 65 km south of Greymouth, 70 km north-west of Methven</value>
            </parameter>
            <parameter>
                <valueName>Quality</valueName>
                <value>best</value>
            </parameter>
            <parameter>
                <valueName>Intensity</valueName>
                <value>severe</value>
            </parameter>
            <parameter>
                <valueName>MMI</valueName>
                <value>8.0</value>
            </parameter>
            <area>
                <areaDesc>25 km south-west of Arthur&#39;s Pass, 40 km south-east of Hokitika, 65 km south of Greymouth, 70 km north-west of Methven</areaDesc>
                <circle>-43.06,171.25 71.3</circle>
            </area>
        </info>
    </alert>

Quake CAP Feed

Quake feed with CAP links for alerting.

Feed of quakes in the last 48 hours of intensity moderate or higher in the New Zealand region and a suitable quality for alerting. Links (type application/cap+xml) to individual quakes in the requested CAP version and profile are included in the returned feed.

[GET] /cap/1.2/GPA1.0/feed/atom1.0/quake

Accept Version

queries to this endpoint are not versioned by accept header.

Examples

/cap/1.2/GPA1.0/feed/atom1.0/quake

Volcanic Alert Level

Returns the current Volcanic Alert Level for volcanoes in New Zealand.

[GET] /volcano/val

Accept Format/Version

application/vnd.geo+json;version=2

Response

GeoJSON features with the following properties:

volcanoID
a unique identifier for the volcano.
volcanoTitle
the volcano title.
level
volcanic alert level.
acc
aviation colour code.
activity
volcanic activity.
hazards
most likely hazards.

Examples

/volcano/val

Volcano Quakes

Returns quakes in the vicinity of a volcano (within a pre-defined region) in the past 60 days.

[GET] /volcano/quake/(volcanoID)

Accept Format/Version

application/vnd.geo+json;version=2

Parameters

volcanoID
A valid volcanoID e.g. ruapehu

Response

GeoJSON features with the following properties:

publicID
the unique public identifier for this quake.
time
the origin time of the quake.
depth
the depth of the quake in km.
magnitude
the summary magnitude for the quake.
locality
distance and direction to the nearest locality.
intensity
quake intensity at the epicentre.
regionIntensity
quake intensity at the closest locality in the New Zealand region.
mmi
the calculated MMI shaking at the closest locality in the New Zealand region.
quality
the quality of this information: best, preliminary, automatic, deleted.
status
the evaluation status of this information: automatic, reviewed, duplicate, deleted.

Examples

/volcano/quake/ruapehu

Network Data

Returns GeoNet network sensor data.

[GET] /network/sensor

Accept Format/Version

application/vnd.geo+json;version=2

Parameters

sensorType
type(s) of the sensor e.g. 1,2,3,4,5,6,7,8,9,10, which can be queried from /network/sensor/type
startDate
the start date of the sensor, optional
endDate
the end date of the sensor, optional
station
the station code of the sensor, optional

Response

GeoJSON features with the following properties:

Network
the network id.
Station
the station code
Location
the location of the sensor
Code
Code for search (Mark or Station Code)
Start
Start date of the sensor
End
End date of the sensor
SensorType
The sensor type

Examples

/network/sensor?sensorType=2,6&endDate=9999-01-01

Network Sensor Details

Returns GeoNet network sensor details (GNSS marks and FDSN stations).

[GET] /network/fdsn/station

[GET] /network/gnss/mark

Accept Format/Version

application/vnd.geo+json;version=2

Parameters

code
mark code (for gnss marks)
station
station code (for fdsn stations)
network
the network code (for fdsn stations)

Response

GeoJSON features with the detailed information of the mark or station

Examples

/network/gnss/mark?code=DUND

/network/fdsn/station?network=NZ&station=QRZ