Skip to main content
Fetches earthquake events with magnitude greater than a specified value. This endpoint is ideal for filtering significant earthquakes and analyzing major seismic events.

​
Endpoint

Method: GET
Path: /v1/earthquakes/magnitude
Authentication: Not required

​
Parameters

​
mag
number
required
Minimum magnitude threshold. Returns earthquakes with magnitude > this value.Validation:
  • Must be a positive number > 0
  • Returns 400 error if missing: “The ‘mag’ parameter is required and must be a positive number greater than 0.”
  • Returns 400 error if invalid: “The ‘mag’ parameter must be a positive number greater than 0.”
​
page
integer
default:"1"
Page number for pagination. Must be a positive integer greater than 0.Validation:
  • Must be > 0
  • Returns 400 error if invalid
​
limit
integer
default:"50"
Number of results per page. Must be a positive integer greater than 0.Validation:
  • Must be > 0
  • Returns 400 error if invalid
​
sort
string
default:"-time"
Sort order for results. Prefix with - for descending order.Allowed values:
  • time or -time (default: descending)
  • magnitude or -magnitude
  • depth or -depth
​
fields
string
Comma-separated list of fields to include in response.Allowed values:
  • time
  • magnitude
  • depth
  • place
  • coordinates

​
Request Example

# Major earthquakes (magnitude > 5.0)
curl "https://api.terraquakeapi.com/v1/earthquakes/magnitude?mag=5.0&limit=100"

# Light earthquakes (magnitude > 4.0)
curl "https://api.terraquakeapi.com/v1/earthquakes/magnitude?mag=4.0"

# Minor earthquakes (magnitude > 2.0)
curl "https://api.terraquakeapi.com/v1/earthquakes/magnitude?mag=2.0&limit=200"

​
Response

​
success
boolean
Indicates if the request was successful
​
code
integer
HTTP status code (200 for success)
​
status
string
HTTP status message (“OK” for success)
​
message
string
Human-readable message. Format: “Earthquake events with magnitude > ”
​
payload
array
Array of GeoJSON Feature objects. Magnitude is stored in properties.mag
​
meta
object
Request metadata containing method, path, and timestamp
​
totalEarthquakes
integer
Total count of earthquakes with magnitude greater than specified value
​
pagination
object
Pagination details with page, limit, totalPages, and hasMore

​
Response Example

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquake events with magnitude > 5.0",
  "payload": [
    {
      "type": "Feature",
      "properties": {
        "eventId": 44604942,
        "originId": 141077201,
        "time": "2025-11-05T23:31:48.030000",
        "author": "SURVEY-INGV-CT#KATALOC",
        "magType": "ML",
        "mag": 5.2,
        "magAuthor": "--",
        "type": "earthquake",
        "place": "13 km SE Maletto (CT)",
        "version": 100,
        "geojson_creationTime": "2025-11-06T00:40:00"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [14.97, 37.751, 5.5]
      }
    }
  ],
  "meta": {
    "method": "GET",
    "path": "/v1/earthquakes/magnitude?mag=5.0&limit=100",
    "timestamp": "2025-11-06T01:00:00.000Z"
  },
  "totalEarthquakes": 12,
  "pagination": {
    "page": 1,
    "limit": 100,
    "totalPages": 1,
    "hasMore": false
  }
}

​
Error Responses

​
Missing Magnitude Parameter

{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "The 'mag' parameter is required and must be a positive number greater than 0."
}

​
Invalid Magnitude Value

{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "The 'mag' parameter must be a positive number greater than 0."
}

​
Invalid Pagination

{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "The 'page' parameter must be a positive integer greater than 0. Example: ?page=2"
}

​
Implementation Details

  • Filter Logic: feature.properties.mag > magValue (strictly greater than)
  • Date Range: From start of current year to today
  • Filtering: Applied after fetching all events from INGV (client-side filtering)
  • Sorting: Default sort is by time (most recent first: -time)
  • Pagination: Manual pagination applied after magnitude filtering
  • Data Source: INGV API with orderby=time and format=geojson

​
Magnitude Scale Reference

Not usually felt by people. Detected by seismographs. Occurs millions of times per year.
Often felt but rarely causes damage. Occurs hundreds of thousands of times per year.
Noticeable shaking of indoor objects. Minor damage to buildings. Occurs tens of thousands of times per year.
Can cause damage to poorly constructed buildings. Slight damage to well-designed buildings. Occurs thousands of times per year.
Destructive in populated areas up to 160 km away. Occurs about 100-150 times per year.
Serious damage over large areas. Strong to violent shaking. Occurs about 10-20 times per year.
Can cause catastrophic damage over vast areas. Occurs about once per year or less.

​
Magnitude Types

The API returns different magnitude types in the magType field:
  • ML (Local Magnitude / Richter Scale) - Best for nearby earthquakes
  • Mw (Moment Magnitude) - Most accurate for large earthquakes
  • Mb (Body Wave Magnitude) - Based on body waves
  • Ms (Surface Wave Magnitude) - Based on surface waves

​
Use Cases

  • Filter for significant earthquakes only
  • Analyze major seismic events
  • Create alerts for high-magnitude earthquakes
  • Research and statistical analysis
  • News and media earthquake reporting

​
Example Queries

# Significant earthquakes (felt by many people)
curl "https://api.terraquakeapi.com/v1/earthquakes/magnitude?mag=3.0"

# Damaging earthquakes (potential structural damage)
curl "https://api.terraquakeapi.com/v1/earthquakes/magnitude?mag=5.0"

# Major earthquakes (serious damage potential)
curl "https://api.terraquakeapi.com/v1/earthquakes/magnitude?mag=7.0"

Build docs developers (and LLMs) love

Get started for freeTalk to us