Skip to main content
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 kmValidation:
  • 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

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

​
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 [, ] within km from 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

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

  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

CityLatitudeLongitude
Rome, Italy41.902812.4964
Tokyo, Japan35.6762139.6503
Los Angeles, USA34.0522-118.2437
Mexico City, Mexico19.4326-99.1332
Istanbul, Turkey41.008228.9784

Build docs developers (and LLMs) love

Get started for freeTalk to us