> ## 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 Earthquakes by Date Range

> Retrieve earthquake events within a custom date range with optional filters

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

```bash cURL theme={null}
# 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"

```

```javascript JavaScript theme={null}
// Basic date range query
const response = await fetch(
  'https://api.terraquakeapi.com/v1/earthquakes/range-time?' +
  new URLSearchParams({
    startdate: '2025-09-01',
    enddate: '2025-09-30',
    limit: 100
  })
);
const data = await response.json();

if (data.success) {
  console.log(`Total earthquakes: ${data.totalEarthquakes}`);
  console.log(`Message: ${data.message}`);
  data.payload.forEach(quake => {
    const { mag, place, time } = quake.properties;
    const depth = quake.geometry.coordinates[2];
    console.log(`${mag} - ${place} at ${time} (${depth}km deep)`);
  });
}

// With filters
const filteredResponse = await fetch(
  'https://api.terraquakeapi.com/v1/earthquakes/range-time?' +
  new URLSearchParams({
    startdate: '2025-09-01',
    enddate: '2025-09-30',
    minmag: '3.0',
    maxdepth: '50',
    limit: 50
  })
);
```

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

# Basic date range query
response = requests.get(
    'https://api.terraquakeapi.com/v1/earthquakes/range-time',
    params={
        'startdate': '2025-09-01',
        'enddate': '2025-09-30',
        'limit': 100
    }
)
data = response.json()

if data.get('success'):
    print(f"Total earthquakes: {data.get('totalEarthquakes')}")
    print(f"Message: {data.get('message')}")
    for quake in data.get('payload', []):
        props = quake['properties']
        depth = quake['geometry']['coordinates'][2]
        print(f"{props['mag']} - {props['place']} at {props['time']} ({depth}km deep)")

# With filters
filtered_response = requests.get(
    'https://api.terraquakeapi.com/v1/earthquakes/range-time',
    params={
        'startdate': '2025-09-01',
        'enddate': '2025-09-30',
        'minmag': 3.0,
        'maxdepth': 50,
        '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 including date range and applied filters. Format:
"Earthquake events between {startdate} and {enddate}\[ with magnitude ≥ 
{minmag}]\[ and depth ≤ {maxdepth} 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

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

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

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

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

### Invalid Filter Values

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

## Related Endpoints

* [By Month](https://docs.terraquakeapi.com/v1/earthquakes/by-month) - Specific month and year
* [Recent Earthquakes](https://docs.terraquakeapi.com/v1/earthquakes/recent) - Year-to-date events
* [Last Week](https://docs.terraquakeapi.com/v1/earthquakes/last-week) - Last 7 days
* [By Magnitude](https://docs.terraquakeapi.com/v1/earthquakes/by-magnitude) - Filter by magnitude only
* [By Depth](https://docs.terraquakeapi.com/v1/earthquakes/by-depth) - Filter by depth only


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