GeoNet: API

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.

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

/intensity/strong/processed/2020p666015

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