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

> Retrieve all earthquake events for a specific month and year

Fetches all earthquake events that occurred during a specific month and year. This endpoint is ideal for historical analysis and monthly reports.

## Endpoint

**Method:** GET\
**Path:** `/v1/earthquakes/month`\
**Authentication:** Not required

## Parameters

**year** `integer` *required*

Four-digit year (YYYY format).

**Validation:**

* Must be a valid number
* Must be between 1900 and current year + 1
* Returns 400 error if missing or invalid: "Both 'year' and 'month' parameters are required and must be numbers. Example: ?year=2025\&month=03"

**month** `integer` *required*

Month number from 1 to 12 (1 = January, 12 = December).

**Validation:**

* Must be a valid number
* Must be between 1 and 12
* Returns 400 error if invalid: "The 'month' parameter must be between 1 and 12. Example: ?month=07 for July"

**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}
curl "https://api.terraquakeapi.com/v1/earthquakes/month?year=2025&month=9&page=1&limit=50"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.terraquakeapi.com/v1/earthquakes/month?year=2025&month=9&limit=50'
);
const data = await response.json();

if (data.success) {
  console.log(`Earthquakes in September 2025: ${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/month',
    params={'year': 2025, 'month': 9, 'limit': 50}
)
data = response.json()

if data.get('success'):
    print(f"Earthquakes in September 2025: {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. Format: "Earthquake events for {year}-{month}"

**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 in the specified month

**pagination** `object`

Pagination details with page, totalPages, limit, and hasMore

## Response Example

```json theme={null}
{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquake events for 2025-09",
  "payload": [
    {
      "type": "Feature",
      "properties": {
        "eventId": 44278572,
        "originId": 140102761,
        "time": "2025-09-26T19:33:46.440000",
        "author": "SURVEY-INGV",
        "magType": "ML",
        "mag": 1,
        "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/month?year=2025&month=9&limit=50",
    "timestamp": "2025-11-06T01:00:00.000Z"
  },
  "totalEarthquakes": 1284,
  "pagination": {
    "page": 1,
    "totalPages": 26,
    "limit": 50,
    "hasMore": true
  }
}
```

## Error Responses

### Missing Required Parameters

```json theme={null}
{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "Both 'year' and 'month' parameters are required and must be numbers. Example: ?year=2025&month=03"
}
```

### Invalid Month

```json theme={null}
{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "The 'month' parameter must be between 1 and 12. Example: ?month=07 for July"
}
```

### Invalid Year

```json theme={null}
{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "The 'year' parameter must be between 1900 and 2026"
}
```

### Invalid Pagination

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

## Implementation Details

* **Date Range Calculation:** Start date is first day of month (`{year}-{month}-01`), end date is first day of next month
* **Month Padding:** Month is zero-padded to 2 digits (e.g., March = "03")
* **Sorting:** Default sort is by time (most recent first: `-time`)
* **Pagination:** Manual pagination applied after fetching all events from INGV
* **Data Source:** INGV API with `orderby=time` and `format=geojson`

## Use Cases

* Monthly seismic activity reports
* Historical analysis and comparisons
* Year-over-year trend analysis
* Research and academic studies

## Related Endpoints

* [Recent Earthquakes](https://docs.terraquakeapi.com/api/earthquakes/recent.md) - Year-to-date events
* [By Date Range](https://docs.terraquakeapi.com/api/earthquakes/by-date-range.md) - Custom date range
* [Last Week](https://docs.terraquakeapi.com/api/earthquakes/last-week.md) - Last 7 days


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