Skip to main content
Fetches earthquake events within a specified date range (inclusive) with optional magnitude and depth filters. This endpoint is ideal for custom reports and specific incident investigations.

​
Endpoint

Method: GET
Path: /v1/earthquakes/range-time
Authentication: Not required

​
Parameters

​
startdate
string
required
Start date in ISO format (YYYY-MM-DD).Validation:
  • Must match format YYYY-MM-DD (e.g., “2024-01-01”)
  • Must be earlier than or equal to enddate
  • Returns 400 error if missing: “Both ‘startdate’ and ‘enddate’ parameters are required. Example: ?startdate=2024-01-01&enddate=2024-01-31”
  • Returns 400 error if invalid format: “Invalid date format. Use ISO format: YYYY-MM-DD. Example: ?startdate=2024-01-01”
​
enddate
string
required
End date in ISO format (YYYY-MM-DD).Validation:
  • Must match format YYYY-MM-DD
  • Must be equal to or after startdate
  • Returns 400 error if startdate > enddate: “‘startdate’ must be earlier than or equal to ‘enddate’.”
​
minmag
number
Minimum magnitude filter (optional).Validation:
  • Must be a positive number if provided
  • Returns 400 error if invalid: “‘minmag’ must be a positive number.”
​
maxdepth
number
Maximum depth filter in kilometers (optional).Validation:
  • Must be a positive number if provided
  • Returns 400 error if invalid: “‘maxdepth’ must be a positive number.”
​
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

# Basic date range
curl "https://api.terraquakeapi.com/v1/earthquakes/range-time?startdate=2025-09-01&enddate=2025-09-30"

# With magnitude filter
curl "https://api.terraquakeapi.com/v1/earthquakes/range-time?startdate=2025-09-01&enddate=2025-09-30&minmag=3.0"

# With magnitude and depth filters
curl "https://api.terraquakeapi.com/v1/earthquakes/range-time?startdate=2025-09-01&enddate=2025-09-30&minmag=3.0&maxdepth=50"

​
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 including date range and applied filters. Format: “Earthquake events between and [ with magnitude ≥ ][ and depth ≤ km]”
​
payload
array
Array of GeoJSON Feature objects containing earthquake data
​
meta
object
Request metadata containing method, path, and timestamp
​
totalEarthquakes
integer
Total count of earthquakes matching the query (after filters applied)
​
pagination
object
Pagination details with page, limit, totalPages, and hasMore

​
Response Example

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquake events between 2025-09-01 and 2025-09-30 with magnitude ≥ 3 and depth ≤ 50 km",
  "payload": [
    {
      "type": "Feature",
      "properties": {
        "eventId": 44278572,
        "originId": 140102761,
        "time": "2025-09-26T19:33:46.440000",
        "author": "SURVEY-INGV",
        "magType": "ML",
        "mag": 3.2,
        "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/range-time?startdate=2025-09-01&enddate=2025-09-30&minmag=3&maxdepth=50&limit=50",
    "timestamp": "2025-11-06T01:00:00.000Z"
  },
  "totalEarthquakes": 42,
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalPages": 1,
    "hasMore": false
  }
}

​
Error Responses

​
Missing Required Parameters

{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "Both 'startdate' and 'enddate' parameters are required. Example: ?startdate=2024-01-01&enddate=2024-01-31"
}

​
Invalid Date Format

{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "Invalid date format. Use ISO format: YYYY-MM-DD. Example: ?startdate=2024-01-01"
}

​
Invalid Date Range

{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "'startdate' must be earlier than or equal to 'enddate'."
}

​
Invalid Filter Values

{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "'minmag' must be a positive number."
}

​
Implementation Details

  • Date Validation: Uses regex /^\d{4}-\d{2}-\d{2}$/ to validate ISO format
  • Date Comparison: Converts to Date objects to ensure startdate ≤ enddate
  • Filter Application:
    • minmag: Filters features where feature.properties.mag >= magValue
    • maxdepth: Filters features where feature.properties.depth <= depthValue
  • Filter Order: Filters applied after fetching all events from INGV
  • Pagination: Applied after filtering (counts filtered results)
  • Sorting: Default sort is by time (most recent first: -time)
  • Data Source: INGV API with orderby=time and format=geojson

​
Use Cases

  • Custom time-based reports
  • Incident investigations
  • Research studies requiring specific date ranges
  • Analyzing seismic activity during specific events
  • Filtering significant earthquakes by magnitude and depth

Build docs developers (and LLMs) love

Get started for freeTalk to us