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 from January 1st of the current year up to the current date. This endpoint is ideal for monitoring year-to-date seismic activity.

​
Endpoint

Method: GET
Path: /v1/earthquakes/recent
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 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 or null
​
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/recent?limit=100&page=1"

​
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: “Earthquakes recent events”
​
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 (string) - HTTP method used
  • path (string) - Request path with query parameters
  • timestamp (string) - ISO 8601 timestamp of request
​
totalEarthquakes
integer
Total count of earthquakes from start of year to today
​
pagination
object
Pagination details:
  • page (integer) - Current page number
  • totalPages (integer) - Total number of pages
  • limit (integer) - Results per page
  • hasMore (boolean) - Whether more pages exist

​
Response Example

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquakes recent events",
  "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/recent?limit=1&page=1",
    "timestamp": "2025-11-06T00:51:33.850Z"
  },
  "totalEarthquakes": 14157,
  "pagination": {
    "page": 1,
    "totalPages": 14157,
    "limit": 1,
    "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": "The page parameter must be a positive integer greater than 0. Example: ?page=2"
}

​
INGV Source Error

{
  "success": false,
  "code": 500,
  "status": "Internal Server Error",
  "message": "HTTP error from the INGV source: 503 Service Unavailable"
}

​
Implementation Details

  • Date Range: Automatically calculated from January 1st of current year to today’s date
  • Sorting: Default sort is by time (most recent first: -time)
  • Pagination: Manual pagination applied after fetching all events from INGV
  • Data Source: INGV API (Italian National Institute of Geophysics and Volcanology)
  • Format: GeoJSON with orderby=time parameter