Importing from GeoNet

Learn how to automatically import earthquake data from GeoNet’s FDSN Event Web Service. This guide covers the import process, configuration options, duplicate handling, and best practices for maintaining current catalogues.

Overview

The platform provides seamless integration with GeoNet (New Zealand’s geological hazard information system) to automatically import earthquake data. This feature is ideal for:

  • Maintaining up-to-date earthquake catalogues for New Zealand

  • Importing historical data for specific regions or time periods

  • Updating existing events with revised (reviewed) parameters

  • Building baseline catalogues for seismological research

  • Comparing local data with the official GeoNet catalogue

Import Process Overview

        flowchart LR
    Query["QUERY"] --> Fetch["FETCH"]
    Fetch --> Parse["PARSE"]
    Parse --> Dedupe["DEDUPE"]
    Dedupe --> Score["SCORE"]
    Score --> Store["STORE"]
    Store --> Report["REPORT"]

    Query -.-> Source["GeoNet API"]
    Fetch -.-> Format["QuakeML"]
    Parse -.-> Event["Event Extraction"]
    Dedupe -.-> Compare["Duplicate Check"]
    Score -.-> Quality["Quality Grading"]
    Store -.-> DB["Database Insert"]
    Report -.-> Summary["Import Summary"]

Data Source

About GeoNet

GeoNet is New Zealand’s geological hazard monitoring system, operated by GNS Science on behalf of the New Zealand Government. It provides real-time earthquake information for New Zealand and the surrounding region.

Key Facts:

  • Organization: GNS Science

  • Coverage: New Zealand and surrounding oceanic regions

  • Network: 300+ seismic stations

  • Detection: Events as small as M 0.5 in well-monitored areas

FDSN Event Web Service

The platform uses the FDSN (International Federation of Digital Seismograph Networks) Event Web Service standard for data retrieval.

Service Details:

URL

https://service.geonet.org.nz/fdsnws/event/1/query

Protocol

FDSN Web Service 1.2

Format

QuakeML 1.2 BED

Authentication

None required (public access)

Rate Limits

Reasonable use expected

License

CC BY 4.0

Data Quality:

GeoNet provides high-quality earthquake data with:

  • Reviewed locations and magnitudes for significant events

  • Real-time automatic solutions for recent events

  • Comprehensive uncertainty estimates

  • Quality metrics (phase counts, azimuthal gaps, RMS)

Attribution:

When using GeoNet data, please cite:

GeoNet Project. (2024). New Zealand Earthquake Catalogue. GNS Science. https://www.geonet.org.nz/

Data Fields Imported

The following fields are extracted from GeoNet’s QuakeML response:

Location Parameters:

  • Origin time with uncertainty

  • Latitude and longitude with uncertainties

  • Depth with uncertainty

  • Origin evaluation mode (automatic/manual)

  • Origin evaluation status (preliminary/confirmed/reviewed/final)

Magnitude Parameters:

  • Preferred magnitude value with uncertainty

  • Magnitude type (ML, Mw, etc.)

  • Station count for magnitude determination

Quality Metrics:

  • Used phase count

  • Used station count

  • Standard error (RMS residual)

  • Azimuthal gap

  • Minimum distance to nearest station

Event Metadata:

  • Public ID (unique GeoNet identifier)

  • Event type (earthquake, etc.)

  • Geographic region (Flinn-Engdahl region)

Import Process

Step 1: Navigate to Import Page

Click Import in the navigation menu or go directly to /import.

Step 2: Configure Time Range

Choose how to specify the time range:

Quick Select (Recent Events):

Use preset options for recent seismicity:

Option

Use Case

Last 1 hour

Monitor recent activity

Last 6 hours

Daily review

Last 24 hours

Daily update

Last 7 days

Weekly review

Last 30 days

Monthly update

Custom Date Range:

Specify exact start and end dates:

Start Date: 2024-01-01 00:00:00 UTC
End Date:   2024-01-31 23:59:59 UTC

Tip

For large date ranges (>1 year), import in smaller chunks (e.g., monthly) to avoid timeouts and memory issues.

Historical Data Tips:

  • GeoNet’s digital catalogue extends back to approximately 1843

  • High-quality digital data available from 1990s onward

  • Best quality data from 2000 onward with GeoNet network deployment

Step 3: Set Magnitude Filters

Filter events by magnitude range:

Minimum Magnitude: 2.0
Maximum Magnitude: 10.0 (or leave empty for no max)

Magnitude Guidelines:

Range

Description

M ≥ 5.0

Damaging earthquakes; comprehensive global coverage

M ≥ 4.0

Significant earthquakes; felt over wide areas

M ≥ 3.0

Felt earthquakes; widely recorded

M ≥ 2.0

Recorded earthquakes; good network coverage needed

M ≥ 1.0

Microearthquakes; limited to well-monitored areas

M ≥ 0.0

All events including micro-seismicity (large volume)

Warning

Importing all events (M ≥ 0) for extended periods will result in very large catalogues (100,000+ events per year). Consider filtering by region or magnitude.

Step 4: Set Depth Filters (Optional)

Filter by hypocentral depth:

Minimum Depth: 0 km
Maximum Depth: 100 km

New Zealand Depth Context:

Depth Range

Characteristics

0-15 km

Crustal earthquakes; most common in NZ

15-40 km

Lower crust to upper mantle

40-100 km

Subduction-related (Hikurangi, Puysegur)

100-300 km

Deep subduction zone events

300-700 km

Very deep events (rare in NZ region)

Typical Filters:

  • Shallow only (0-40 km): Most crustal earthquakes

  • Upper 100 km: Excludes very deep subduction events

  • All depths: Complete catalogue including deep events

Step 5: Define Geographic Bounds (Optional)

Limit imports to a specific region using a bounding box:

Minimum Latitude:  -47.5  (South)
Maximum Latitude:  -34.0  (North)
Minimum Longitude: 165.0  (West)
Maximum Longitude: 179.0  (East)

Predefined Regions:

Region

Coordinates

All New Zealand

Lat: -47.5 to -34.0, Lon: 165.0 to 179.0

North Island

Lat: -42.0 to -34.0, Lon: 172.0 to 179.0

South Island

Lat: -47.5 to -40.0, Lon: 165.0 to 175.0

Canterbury

Lat: -44.5 to -42.0, Lon: 170.5 to 174.0

Wellington

Lat: -42.0 to -40.5, Lon: 174.0 to 176.5

Auckland

Lat: -37.5 to -36.0, Lon: 174.0 to 175.5

Taupo Volcanic Zone

Lat: -39.5 to -37.5, Lon: 175.5 to 177.0

Note

Leave bounds empty to import all events within the time and magnitude range for the entire GeoNet coverage area.

Step 6: Configure Duplicate Handling

Choose how to handle events that already exist in your catalogue:

Skip Duplicates (Default)

Events already in the catalogue are skipped. Use this when:

  • Building a new catalogue from scratch

  • Adding events for a new time period

  • You want to preserve local modifications

Update Existing Events

Replace existing events with fresh data from GeoNet. Use this when:

  • Refreshing automatic solutions with reviewed parameters

  • Updating preliminary data with final solutions

  • Syncing with GeoNet’s latest revisions

How Duplicates Are Detected:

The platform matches events using:

Matching Criteria:
- Time difference:     ± 60 seconds
- Spatial distance:    ≤ 50 km
- Magnitude difference: ≤ 0.5

Events meeting ALL criteria are considered duplicates.

Step 7: Select or Create Catalogue

Create New Catalogue:

Provide a descriptive name:

Good examples:
- "GeoNet NZ 2024"
- "Canterbury Earthquakes M3+ 2020-2024"
- "Taupo Volcanic Zone - All Events"

Add to Existing Catalogue:

Select an existing catalogue from the dropdown to append events.

Step 8: Start Import

Click Start Import to begin.

Processing Steps:

  1. Query: Send request to GeoNet FDSN service

  2. Fetch: Download QuakeML response

  3. Parse: Extract events and metadata

  4. Deduplicate: Compare with existing events

  5. Score: Calculate quality grades

  6. Store: Insert new/updated events

  7. Report: Generate import summary

Progress Indicator:

During import, you’ll see:

  • Events fetched count

  • Events processed count

  • Current processing stage

Import Results

After import completes, review the summary:

Import Summary
==============

Source:            GeoNet FDSN Event Web Service
Time Range:        2024-01-01 to 2024-01-31
Magnitude Range:   M ≥ 3.0

Results:
--------
Total Fetched:     1,234 events
New Events:        1,150 events
Updated Events:    45 events
Skipped (Dupes):   39 events
Errors:            0 events

Quality Distribution:
A+/A: 342 (28%)
B+/B: 521 (42%)
C:    287 (23%)
D/F:  85 (7%)

Processing Time:   12.5 seconds

Import History

Track all imports for data provenance:

View Import History:

  1. Navigate to Catalogues page

  2. Select a catalogue

  3. Click Import History tab

History Record Contains:

  • Import date and time

  • Time range imported

  • Filter parameters (magnitude, depth, bounds)

  • Event counts (new, updated, skipped, errors)

  • User who performed import

  • Processing duration

Tip

Use import history to verify catalogue completeness and track when data was last refreshed.

Duplicate Detection

Understanding Duplicates

When importing from GeoNet, some events may already exist in your catalogue from previous imports or uploads. The platform detects these duplicates intelligently.

Matching Algorithm:

Event A matches Event B if ALL conditions are true:

1. |Time_A - Time_B| ≤ 60 seconds
2. Distance(A, B) ≤ 50 km
3. |Mag_A - Mag_B| ≤ 0.5

Why These Thresholds?

  • Time (60s): Event parameters may be refined, shifting origin time

  • Distance (50km): Location revisions can shift epicenters significantly

  • Magnitude (0.5): Magnitude estimates often change with review

Handling Strategies

Skip (Preserve Local):

Existing: 2024-01-15 10:30:45, M4.5, -41.5, 174.2
Imported: 2024-01-15 10:30:47, M4.6, -41.51, 174.21

Result: Keep existing, skip imported

Update (Use GeoNet):

Existing: 2024-01-15 10:30:45, M4.5, -41.5, 174.2 (automatic)
Imported: 2024-01-15 10:30:47, M4.6, -41.51, 174.21 (reviewed)

Result: Replace with imported (better quality)

Best Practices

Building a Baseline Catalogue

For new projects, establish a comprehensive baseline:

  1. Import Historical Data:

    Time Range: Past 10-20 years
Magnitude: M ≥ 2.0 (or your analysis threshold)
Import in yearly chunks to avoid timeouts

  2. Document Your Criteria:

    Record the filters used for reproducibility:

    Catalogue: NZ Baseline 2010-2024
Source: GeoNet FDSN
Filters: M ≥ 2.0, All depths, NZ region
Import Date: 2024-01-15

Maintaining Current Catalogues

For ongoing monitoring, establish a regular update schedule:

Daily Updates:

Frequency: Every 24 hours
Time Range: Last 7 days (overlap catches revisions)
Duplicate Mode: Update existing
Magnitude: M ≥ 2.0

Weekly Updates:

Frequency: Weekly
Time Range: Last 30 days (catches all revisions)
Duplicate Mode: Update existing

Why Overlap?

GeoNet frequently updates event parameters:

  • Automatic locations refined within hours

  • Manual review within 1-7 days for significant events

  • Magnitude updates may occur weeks later

Importing overlapping time periods with “Update” mode ensures you get the latest revised parameters.

Quality Considerations

Import High-Quality Events Only:

For precise analysis, apply quality filters:

Minimum Magnitude: 3.0 (better located)
After import, filter by: Quality Grade ≥ B

Import All, Filter Later:

For completeness studies:

Import: All events (M ≥ 0)
Analysis: Filter by quality as needed
Benefit: Complete catalogue, flexible analysis

Large Historical Imports

For multi-year imports:

  1. Chunk by Time:

    2020: Import Jan-Dec separately
2021: Import Jan-Dec separately
...

  2. Start with Recent Data:

    Import recent years first (better quality), then historical.

  3. Verify Counts:

    Compare with GeoNet’s published statistics to verify completeness.

  4. Monitor Memory:

    Very large imports (>50,000 events) may require:

    • Increased Node.js memory

    • Smaller time chunks

    • Import during low-usage periods

API Access

For programmatic imports, use the REST API:

Trigger Import:

curl -X POST "http://localhost:3000/api/import/geonet" \
  -H "Content-Type: application/json" \
  -d '{
    "catalogueId": "existing-catalogue-id",
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-31T23:59:59Z",
    "minMagnitude": 3.0,
    "updateExisting": true
  }'

See Import API for complete API documentation.

Troubleshooting

No Events Found

Symptoms: Import returns zero events

Solutions:

  1. Verify time range is in the past (not future dates)

  2. Check magnitude filter isn’t too restrictive

  3. Ensure geographic bounds include seismic areas

  4. Test GeoNet service directly:

    curl "https://service.geonet.org.nz/fdsnws/event/1/count?\
starttime=2024-01-01&endtime=2024-01-31&minmagnitude=3"

Timeout Errors

Symptoms: “Request timeout” or incomplete import

Solutions:

  1. Reduce time range (import in monthly chunks)

  2. Increase minimum magnitude

  3. Add geographic bounds to limit results

  4. Import during off-peak hours

Too Many Duplicates

Symptoms: Most events skipped as duplicates

Solutions:

  1. Check if time range overlaps previous imports

  2. Use “Update” mode if refreshing existing data

  3. Verify you’re importing to the correct catalogue

Incomplete Data

Symptoms: Missing fields (uncertainties, quality metrics)

Explanation:

Not all GeoNet events have complete metadata:

  • Automatic solutions may lack uncertainty estimates

  • Older events may have less detailed quality metrics

  • Very small events may have minimal metadata

This is normal; quality scoring handles missing fields appropriately.

GeoNet Service Unavailable

Symptoms: Connection refused or service errors

Solutions:

  1. Check GeoNet status: https://www.geonet.org.nz/

  2. Wait and retry (service may be under maintenance)

  3. Check your internet connection

  4. Verify URL hasn’t changed

Next Steps

After importing:

See also