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

# Earthquakes API Overview

> Comprehensive API for querying seismic event data from INGV

The **Earthquakes API** provides comprehensive access to seismic event data sourced from the Italian National Institute of Geophysics and Volcanology (INGV). Query earthquakes by time, location, magnitude, depth, and specific event IDs.

## Base URL

```
https://api.terraquakeapi.com/v1/earthquakes
```

## Authentication

All endpoints are publicly accessible and do not require authentication.

## Available Endpoints

> **[Recent Events](https://docs.terraquakeapi.com/api/earthquakes/recent.md)**
>
> Earthquakes from start of current year to today

> **[Today's Events](https://docs.terraquakeapi.com/api/earthquakes/today.md)**
>
> All earthquakes that occurred today (UTC)

> **[Last Week](https://docs.terraquakeapi.com/api/earthquakes/last-week.md)**
>
> Seismic events from the last 7 days

> **[By Month](https://docs.terraquakeapi.com/api/earthquakes/by-month.md)**
>
> Query earthquakes for a specific month and year

> **[By Date Range](https://docs.terraquakeapi.com/api/earthquakes/by-date-range.md)**
>
> Custom date range with optional filters

> **[By Location](https://docs.terraquakeapi.com/api/earthquakes/by-location.md)**
>
> Events near specific coordinates

> **[By Region](https://docs.terraquakeapi.com/api/earthquakes/by-region.md)**
>
> Filter by Italian administrative region

> **[By Depth](https://docs.terraquakeapi.com/api/earthquakes/by-depth.md)**
>
> Filter by earthquake depth threshold

> **[By Magnitude](https://docs.terraquakeapi.com/api/earthquakes/by-magnitude.md)**
>
> Filter by minimum magnitude

> **[By Event ID](https://docs.terraquakeapi.com/api/earthquakes/by-event-id.md)**
>
> Retrieve specific earthquake by unique ID

## Common Parameters

Most endpoints support the following query parameters:

**page** `integer` (default: 1)

Page number for pagination (must be positive integer)

**limit** `integer` (default: 50)

Number of results per page (must be positive integer, typically max 1000)

**sort** `string` (default: -time)

Sort order. Available fields: `time`, `magnitude`, `depth`. Prefix with `-` for descending order.

**fields** `string`

Comma-separated list of fields to include. Available: `time`, `magnitude`, `depth`, `place`, `coordinates`

## GeoJSON Response Format

All earthquake data is returned in GeoJSON Feature Collection format:

```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=50&page=1",
    "timestamp": "2025-11-06T00:40:01.490Z"
  },
  "totalEarthquakes": 14157,
  "pagination": {
    "page": 1,
    "totalPages": 284,
    "limit": 50,
    "hasMore": true
  }
}
```

## Response Fields

**success** `boolean`

Indicates if the request was successful

**code** `integer`

HTTP status code (200, 400, 404, 500, etc.)

**status** `string`

HTTP status message

**message** `string`

Human-readable description of the response

**payload** `array`

Array of GeoJSON Feature objects containing earthquake data

**meta** `object`

Request metadata including method, path, and timestamp

**totalEarthquakes** `integer`

Total number of earthquakes matching the query

**pagination** `object`

Pagination information including current page, total pages, limit, and hasMore flag

## Quick Start

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

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

if (data.success) {
  data.payload.forEach(quake => {
    console.log(`${quake.properties.mag} - ${quake.properties.place}`);
  });
}
```

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

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

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

## Error Handling

All endpoints return errors in a consistent format:

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

Common HTTP status codes:

* `200` - Success
* `400` - Bad Request (invalid parameters)
* `404` - Not Found (event not found)
* `500` - Internal Server Error

## Data Source

All seismic data is sourced in real-time from the Italian National Institute of Geophysics and Volcanology (INGV).


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