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

> Retrieve earthquake events near specific geographic coordinates

Fetches earthquake events within a specified radius of given coordinates using the Haversine formula for precise distance calculation. This endpoint is ideal for finding earthquakes near cities, landmarks, or specific points of interest.

## Endpoint

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

## Parameters

**latitude** `number` *required*

Latitude in decimal degrees.

**Validation:**

* Must be a valid number
* Valid range: -90 to 90
* Returns 400 error if missing or invalid: "Please provide valid latitude and longitude"

**longitude** `number` *required*

Longitude in decimal degrees.

**Validation:**

* Must be a valid number
* Valid range: -180 to 180
* Returns 400 error if missing or invalid: "Please provide valid latitude and longitude"

**radius** `number` (default: 50)

Search radius in kilometers.

**Default:** 50 km

**Validation:**

* Minimum: 0.1 km
* If not provided or invalid, defaults to 50 km

**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}
# Earthquakes within 500km of Tokyo
curl "https://api.terraquakeapi.com/v1/earthquakes/location?latitude=35.6762&longitude=139.6503&radius=500"

# Earthquakes within 100km of San Francisco
curl "https://api.terraquakeapi.com/v1/earthquakes/location?latitude=37.7749&longitude=-122.4194&radius=100"

# Earthquakes within default 50km of Rome
curl "https://api.terraquakeapi.com/v1/earthquakes/location?latitude=41.9028&longitude=12.4964"
```

```javascript JavaScript theme={null}
// Earthquakes near Tokyo
const response = await fetch(
  'https://api.terraquakeapi.com/v1/earthquakes/location?' +
  new URLSearchParams({
    latitude: 35.6762,
    longitude: 139.6503,
    radius: 500,
    limit: 50
  })
);
const data = await response.json();

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

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

# Earthquakes near Tokyo
response = requests.get(
    'https://api.terraquakeapi.com/v1/earthquakes/location',
    params={
        'latitude': 35.6762,
        'longitude': 139.6503,
        'radius': 500,
        'limit': 50
    }
)
data = response.json()

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

## 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: "Earthquakes events near \[{lat}, {lon}] within {radius} km from {startOfYear} to today"

**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 within the specified radius

**pagination** `object`

Pagination details with page, totalPages, limit, and hasMore

## Response Example

```json theme={null}
{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquakes events near [35.6762, 139.6503] within 500 km from 2025-01-01T00:00:00 to today",
  "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/location?latitude=35.6762&longitude=139.6503&radius=500",
    "timestamp": "2025-11-06T01:00:00.000Z"
  },
  "totalEarthquakes": 127,
  "pagination": {
    "page": 1,
    "totalPages": 3,
    "limit": 50,
    "hasMore": true
  }
}
```

## Error Responses

### Missing or Invalid Coordinates

```json theme={null}
{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "Please provide valid latitude and longitude"
}
```

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

## Implementation Details

* **Distance Calculation:** Uses Haversine formula via `haversine-distance` package for precise great-circle distance
* **Bounding Box Optimization:** Initial query uses approximate bounding box (degreeRadius = radius / 111 km) to reduce data fetching
* **Precise Filtering:** Results are filtered using exact Haversine distance calculation
* **Date Range:** From start of current year to today
* **Coordinate Format:** GeoJSON format \[longitude, latitude, depth]
* **Sorting:** Default sort is by time (most recent first: `-time`)
* **Data Source:** INGV API with minlatitude, maxlatitude, minlongitude, maxlongitude parameters

### Distance Calculation Process

1. Calculate approximate degree radius: `radius_km / 111`
2. Create bounding box: `lat ± degreeRadius`, `lon ± degreeRadius`
3. Fetch earthquakes within bounding box from INGV
4. Filter results using precise Haversine distance
5. Return only earthquakes within exact radius

## Use Cases

* Find earthquakes near cities or populated areas
* Analyze seismic activity around specific landmarks
* Risk assessment for infrastructure projects
* Real estate seismic risk analysis
* Emergency response planning

## Coordinate Examples

| City | Latitude | Longitude |
| - | - | - |
| Rome, Italy | 41.9028 | 12.4964 |
| Tokyo, Japan | 35.6762 | 139.6503 |
| Los Angeles, USA | 34.0522 | -118.2437 |
| Mexico City, Mexico | 19.4326 | -99.1332 |
| Istanbul, Turkey | 41.0082 | 28.9784 |

## Related Endpoints

* [By Region](https://docs.terraquakeapi.com/api/earthquakes/by-region.md) - Italian administrative regions
* [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


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