Get Earthquakes by Location

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

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”

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”

number

default:"50"

Search radius in kilometers.Default: 50 kmValidation:

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

integer

default:"1"

Page number for pagination. Must be a positive integer greater than 0.Validation:

Must be > 0
Returns 400 error if invalid

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

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

string

Comma-separated list of fields to include in response.Allowed values:

time
magnitude
depth
place
coordinates

Request Example

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

// 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)`);
  });
}

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

boolean

Indicates if the request was successful

integer

HTTP status code (200 for success)

string

HTTP status message (“OK” for success)

string

Human-readable message. Format: “Earthquakes events near [, ] within km from to today”

array

Array of GeoJSON Feature objects containing earthquake data

object

Request metadata containing method, path, and timestamp

integer

Total count of earthquakes within the specified radius

object

Pagination details with page, totalPages, limit, and hasMore

Response Example

{
  "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

{
  "success": false,
  "code": 400,
  "status": "Bad Request",
  "message": "Please provide valid latitude and longitude"
}

Invalid Limit Parameter

{
  "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

{
  "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

Calculate approximate degree radius: radius_km / 111
Create bounding box: lat ± degreeRadius, lon ± degreeRadius
Fetch earthquakes within bounding box from INGV
Filter results using precise Haversine distance
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

By Region - Italian administrative regions
Recent Earthquakes - Year-to-date events
By Date Range - Custom date range

​Endpoint

​Parameters

​Request Example

​Response

​Response Example

​Error Responses

​Missing or Invalid Coordinates

​Invalid Limit Parameter

​Invalid Page Parameter

​Implementation Details

​Distance Calculation Process

​Use Cases

​Coordinate Examples

​Related Endpoints

Endpoint

Parameters

Request Example

Response

Response Example

Error Responses

Missing or Invalid Coordinates

Invalid Limit Parameter

Invalid Page Parameter

Implementation Details

Distance Calculation Process

Use Cases

Coordinate Examples

Related Endpoints