Get Earthquakes by Depth - TerraQuake API

Fetches earthquake events at or deeper than a specified depth threshold. This endpoint is ideal for studying shallow vs deep earthquakes and analyzing crustal vs subduction zone events.

Endpoint

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

Parameters

number

required

Minimum depth in kilometers. Returns earthquakes with depth >= this value.Validation:

Must be a positive number > 0
Returns 400 error if missing: “The depth parameter is required and must be a positive number greater than 0”
Returns 400 error if invalid: “The depth parameter must be a positive number greater than 0”

integer

default:"1"

Page number for pagination. Must be a positive integer greater than 0.Validation:

Must be > 0
Returns 400 error if invalid

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

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

string

Comma-separated list of fields to include in response. Allowed values: - time - magnitude - depth - place - coordinates

Request Example

# Shallow earthquakes (≤10km deep)
curl "https://api.terraquakeapi.com/v1/earthquakes/depth?depth=10"

# Intermediate depth earthquakes (≥70km deep)

curl "https://api.terraquakeapi.com/v1/earthquakes/depth?depth=70&limit=100"

# Deep earthquakes (≥300km deep)

curl "https://api.terraquakeapi.com/v1/earthquakes/depth?depth=300"

// Get shallow earthquakes (≤10km)
const response = await fetch(
  'https://api.terraquakeapi.com/v1/earthquakes/depth?' +
  new URLSearchParams({
    depth: 10,
    limit: 100
  })
);
const data = await response.json();

if (data.success) {
  console.log(`Total earthquakes at depth ≥10km: ${data.totalEarthquakes}`);
  console.log(`Message: ${data.message}`);
  data.payload.forEach(quake => {
    const { mag, place, time } = quake.properties;
    const depth = quake.geometry.coordinates[2];
    console.log(`${mag} - ${place} at ${time} (${depth}km deep)`);
  });
}

import requests

# Get shallow earthquakes (≤10km)
response = requests.get(
    'https://api.terraquakeapi.com/v1/earthquakes/depth',
    params={'depth': 10, 'limit': 100}
)
data = response.json()

if data.get('success'):
    print(f"Total earthquakes at depth ≥10km: {data.get('totalEarthquakes')}")
    print(f"Message: {data.get('message')}")
    for quake in data.get('payload', []):
        props = quake['properties']
        depth = quake['geometry']['coordinates'][2]
        print(f"{props['mag']} - {props['place']} at {props['time']} ({depth}km deep)")

Response

boolean

Indicates if the request was successful

integer

HTTP status code (200 for success)

string

HTTP status message (“OK” for success)

string

Human-readable message. Format: “Earthquake events with depth > km”

array

Array of GeoJSON Feature objects. Depth is stored in geometry.coordinates[2] (third element of coordinates array)

object

Request metadata containing method, path, and timestamp

integer

Total count of earthquakes at or deeper than specified depth

object

Pagination details with page, totalPages, limit, and hasMore

Response Example

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquake events with depth > 10 km",
  "payload": [
    {
      "type": "Feature",
      "properties": {
        "eventId": 44278572,
        "originId": 140102761,
        "time": "2025-09-26T19:33:46.440000",
        "author": "SURVEY-INGV",
        "magType": "ML",
        "mag": 1,
        "magAuthor": "--",
        "type": "earthquake",
        "place": "Costa Calabra sud-orientale (Reggio di Calabria)",
        "version": 100,
        "geojson_creationTime": "2025-11-06T00:52:30"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [16.2387, 37.9982, 10.5]
      }
    }
  ],
  "meta": {
    "method": "GET",
    "path": "/v1/earthquakes/depth?depth=10&limit=100",
    "timestamp": "2025-11-06T01:00:00.000Z"
  },
  "totalEarthquakes": 3421,
  "pagination": {
    "page": 1,
    "totalPages": 35,
    "limit": 100,
    "hasMore": true
  }
}

Error Responses

Missing Depth Parameter

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

Invalid Depth Value

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

Invalid Limit Parameter

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

Implementation Details

Filter Logic: feature.geometry.coordinates[2] >= depthValue
Depth Location: Third element of GeoJSON coordinates array (index 2)
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 depth filtering
Coordinate Format: [longitude, latitude, depth in km]

Earthquake Depth Classification

Shallow

0-70 km Most common type. Occur in Earth’s crust. Can cause significant damage due to proximity to surface.

Intermediate

70-300 km Occur in subduction zones. Less common but can still be felt at surface.

Deep

300-700 km Occur in subduction zones. Rare and typically less damaging at surface.

Use Cases

Studying crustal vs subduction zone earthquakes
Analyzing tectonic plate interactions
Research on earthquake mechanisms
Identifying shallow earthquakes with higher damage potential
Seismological studies on Earth’s interior structure

Example Queries

# Very shallow earthquakes (crustal)
curl "https://api.terraquakeapi.com/v1/earthquakes/depth?depth=5"

# Shallow to intermediate boundary
curl "https://api.terraquakeapi.com/v1/earthquakes/depth?depth=70"

# Deep earthquakes only
curl "https://api.terraquakeapi.com/v1/earthquakes/depth?depth=300"

By Magnitude - Filter by magnitude
By Date Range - Custom date range with depth filter
Recent Earthquakes - Year-to-date events

​Endpoint

​Parameters

​Request Example

​Response

​Response Example

​Error Responses

​Missing Depth Parameter

​Invalid Depth Value

​Invalid Limit Parameter

​Implementation Details

​Earthquake Depth Classification

Shallow

Intermediate

Deep

​Use Cases

​Example Queries

​Related Endpoints

Endpoint

Parameters

Request Example

Response

Response Example

Error Responses

Missing Depth Parameter

Invalid Depth Value

Invalid Limit Parameter

Implementation Details

Earthquake Depth Classification

Use Cases

Example Queries

Related Endpoints