> ## 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.

# Get Recent Earthquakes

> Retrieve earthquakes from the start of the current year until today

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

```bash cURL theme={null}
curl "https://api.terraquakeapi.com/v1/earthquakes/recent?limit=100&page=1"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.terraquakeapi.com/v1/earthquakes/recent?limit=100&page=1'
);
const data = await response.json();

if (data.success) {
  console.log(`Total earthquakes this year: ${data.totalEarthquakes}`);
  data.payload.forEach(quake => {
    const { mag, place, time } = quake.properties;
    console.log(`${mag} - ${place} at ${time}`);
  });
}
```

```python Python theme={null}
import requests

response = requests.get(
    'https://api.terraquakeapi.com/v1/earthquakes/recent',
    params={'limit': 100, 'page': 1}
)
data = response.json()

if data.get('success'):
    print(f"Total earthquakes this year: {data.get('totalEarthquakes')}")
    for quake in data.get('payload', []):
        props = quake['properties']
        print(f"{props['mag']} - {props['place']} at {props['time']}")
```

## 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

## Related Endpoints

* [Today's Earthquakes](https://docs.terraquakeapi.com/api/earthquakes/today.md) - Only today's events
* [Last Week](https://docs.terraquakeapi.com/api/earthquakes/last-week.md) - Last 7 days
* [By Date Range](https://docs.terraquakeapi.com/api/earthquakes/by-date-range.md) - Custom date range


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.