Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.terraquakeapi.com/llms.txt

Use this file to discover all available pages before exploring further.

Fetches all earthquake events that occurred on the current calendar day in UTC timezone. This endpoint is ideal for daily monitoring and real-time alerts.

​
Endpoint

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

​
Parameters

​
page
integer
default:"1"
Page number for pagination. Must be a positive integer greater than 0.Validation:
  • Must be > 0
  • Returns 400 error: “Invalid ‘page’ parameter. It must be a positive integer (e.g., ?page=2).”
​
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

curl "https://api.terraquakeapi.com/v1/earthquakes/today?limit=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: “Earthquake events for today”
​
payload
array
Array of GeoJSON Feature objects. Each feature contains: Properties: - eventId (integer) - Unique event identifier - originId (integer) - Origin identifier - time (string) - ISO 8601 timestamp - author (string) - Reporting agency - magType (string) - Magnitude type (ML, Mw, etc.) - mag (float) - Magnitude value - magAuthor (string) - Magnitude author - type (string) - Event type (“earthquake”) - place (string) - Location description
  • version (integer) - Version number - geojson_creationTime (string) - GeoJSON creation time Geometry: - type (string) - Always “Point” - coordinates (array) - [longitude, latitude, depth in km]
​
meta
object
Request metadata containing method, path, and timestamp
​
totalEarthquakes
integer
Total count of earthquakes that occurred today
​
pagination
object
Pagination details with page, totalPages, limit, and hasMore

​
Response Example

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquake events for today",
  "payload": [
    {
      "type": "Feature",
      "properties": {
        "eventId": 44604942,
        "originId": 141077201,
        "time": "2025-11-05T23:31:48.030000",
        "author": "SURVEY-INGV-CT#KATALOC",
        "magType": "ML",
        "mag": 2.1,
        "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/today?limit=50",
    "timestamp": "2025-11-06T00:51:33.850Z"
  },
  "totalEarthquakes": 87,
  "pagination": {
    "page": 1,
    "totalPages": 2,
    "limit": 50,
    "hasMore": true
  }
}

​
Error Responses

​
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"
}

​
Invalid Page Parameter

{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "Invalid 'page' parameter. It must be a positive integer (e.g., ?page=2)."
}

​
Implementation Details

  • Date Range: Current day from 00:00:00 to 23:59:59 UTC
  • Timezone: All times are in UTC
  • Time Query: starttime={dateStr}T00:00:00&endtime={dateStr}T23:59:59
  • Sorting: Default sort is by time (most recent first: -time)
  • Pagination: Manual pagination applied after fetching all today’s events
  • Data Source: INGV API with GeoJSON format

​
Use Cases

  • Real-time earthquake monitoring dashboards
  • Daily seismic activity reports
  • Alert systems for recent seismic events
  • News and media earthquake tracking