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

# Quickstart

> Make your first API call in under 5 minutes

Get started with TerraQuake API by making your first request. No authentication required for most endpoints - you can start querying earthquake data immediately.

## What You'll Build

In this quickstart, you'll fetch the 10 most recent earthquakes from this year and display their magnitude and location. This will teach you the basics of working with the API.

**1. Choose Your Development Environment**

TerraQuake API works with any HTTP client. Pick your preferred language:

* **cURL** - Quick testing from the command line
* **JavaScript** - For web applications and Node.js
* **Python** - For data analysis and scripts

> [!NOTE]
>
> No API key needed! Most endpoints are publicly accessible.

**2. Make Your First Request**

Fetch the 10 most recent earthquakes from this year:

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

```javascript JavaScript theme={null}
// Fetch the 10 most recent earthquakes of the current year

const fetchRecentEarthquakes = async (limit = 10) => {
  const url = `https://api.terraquakeapi.com/v1/earthquakes/recent?limit=${limit}`;

  try {
    const response = await fetch(url);

    // Check HTTP status
    if (!response.ok) {
      throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();

    // Validate API success response
    if (!data.success || !Array.isArray(data.payload)) {
      console.warn("Unexpected API response format:", data);
      return;
    }

    // Display formatted result
    console.log(`Showing ${data.payload.length} recent earthquakes:`);
    data.payload.forEach(event => {
      const props = event.properties || {};
      const magnitude = props.mag ?? "N/A";
      const magnitudeType = props.magType;
      const place = props.place ?? "Unknown";
      console.log(`• ${magnitude} ${magnitudeType} — ${place}`);
    });

  } catch (error) {
    console.error("API Error:", error.message);
  }
};

fetchRecentEarthquakes(10);
```

```python Python theme={null}
# Fetch the 10 most recent earthquakes of the current year

import requests

url = "https://api.terraquakeapi.com/v1/earthquakes/recent"
params = {"limit": 10}

response = requests.get(url, params=params)

if response.status_code == 200:
    data = response.json()

    if data.get("success") and "payload" in data and isinstance(data["payload"], list):
        if len(data["payload"]) > 0:
            for event in data["payload"]:
                props = event.get("properties", {})
                magnitude = props.get("mag", "N/A")
                place = props.get("place", "Unknown")
                print(f"{magnitude} - {place}")
        else:
            print("No earthquake data found.")
    else:
        print("Unexpected data format or no payload.")
else:
    print(f"Error: {response.status_code} - {response.text}")
```

**3. Understand the Response**

The API returns a standardized JSON response with earthquake data in GeoJSON 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
      },
      "geometry": {
        "type": "Point",
        "coordinates": [14.97, 37.751, 5.5]
      }
    }
  ],
  "meta": {
    "method": "GET",
    "path": "/v1/earthquakes/recent?limit=10&page=1",
    "timestamp": "2025-11-06T00:51:33.850Z"
  },
  "totalEarthquakes": 14157,
  "pagination": {
    "page": 1,
    "totalPages": 1416,
    "limit": 10,
    "hasMore": true
  }
}
```

### Key Response Fields

**success** `boolean`

Indicates if the request was successful. Always check this before processing data.

**payload** `array`

Array of earthquake features in GeoJSON format. Each feature contains:

* `properties.mag` - Magnitude value
* `properties.place` - Location description
* `properties.time` - When the earthquake occurred
* `geometry.coordinates` - \[longitude, latitude, depth in km]

**totalEarthquakes** `integer`

Total number of earthquakes available (across all pages)

**pagination** `object`

Pagination info including current page, total pages, and whether more results exist

> [!TIP]
>
> Coordinates follow GeoJSON convention: `[longitude, latitude, depth]` - note the order!

## Next Steps

Now that you've made your first API call, explore more features:

> **[API Reference](https://docs.terraquakeapi.com/api/earthquakes/overview.md)**
>
> Explore all available endpoints and parameters

> **[Filter Earthquakes](https://docs.terraquakeapi.com/guides/filtering-earthquakes.md)**
>
> Learn how to filter by magnitude, location, depth, and date range

> **[Response Format](https://docs.terraquakeapi.com/concepts/response-format.md)**
>
> Understand the structure of API responses in detail

> **[Authentication](https://docs.terraquakeapi.com/authentication.md)**
>
> Set up authentication for protected endpoints

## Common Use Cases

### Get Today's Earthquakes

```bash theme={null}
curl "https://api.terraquakeapi.com/v1/earthquakes/today"
```

### Filter by Magnitude

```bash theme={null}
curl "https://api.terraquakeapi.com/v1/earthquakes/magnitude?minMag=4.0"
```

### Find Earthquakes Near a Location

```bash theme={null}
curl "https://api.terraquakeapi.com/v1/earthquakes/location?latitude=41.9028&longitude=12.4964&radius=100"
```

### Get Earthquakes by Region

```bash theme={null}
curl "https://api.terraquakeapi.com/v1/earthquakes/region/Lazio"
```

> [!TIP]
>
> All earthquake data comes directly from the Italian National Institute of
> Geophysics and Volcanology (INGV), ensuring accuracy and reliability.

## Need Help?

> **[Best Practices](https://docs.terraquakeapi.com/guides/best-practices.md)**
>
> Learn tips for efficient API usage

> **[Error Handling](https://docs.terraquakeapi.com/concepts/error-handling.md)**
>
> Handle errors and edge cases gracefully


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