Response Format

Overview

All successful TerraQuake API responses follow a consistent, standardized format. This makes it easy to parse responses and extract the data you need across all endpoints.

Standard Response Structure

Every successful API response includes these core fields:

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquakes recent events",
  "payload": [...],
  "meta": {
    "method": "GET",
    "path": "/earthquakes/recent?limit=50",
    "timestamp": "2026-03-03T10:30:45.123Z"
  },
  "totalEarthquakes": 1247,
  "pagination": {
    "page": 1,
    "totalPages": 25,
    "limit": 50,
    "hasMore": true
  }
}

Core Response Fields

success

boolean

required

Indicates whether the request was successful. Always true for successful responses, false for errors.

code

integer

required

HTTP status code. 200 for successful requests.

status

string

required

HTTP status text. "OK" for successful requests.

message

string

required

Human-readable description of the response. Examples:

"Earthquakes recent events"
"Earthquakes filtered by magnitude"
"Seismic stations retrieved successfully"

payload

array

required

The main response data. Contains an array of earthquake features or other requested resources.

Additional Fields

Depending on the endpoint, responses may include:

totalEarthquakes

integer

Total number of earthquake records available (across all pages)

pagination

object

Pagination metadata. See Pagination for details.

Show properties

page

integer

Current page number

totalPages

integer

Total number of pages available

limit

integer

Number of results per page

hasMore

boolean

Whether more pages exist after the current page

Response Builder Implementation

The API uses a standardized utility to build all responses:

export const buildResponse = (
  req = {}, 
  message = '', 
  payload = null, 
  total = null, 
  rest = {}
) => ({
  success: true,
  code: 200,
  status: 'OK',
  message,
  payload,
  meta: {
    method: req.method?.toUpperCase() || null,
    path: req.originalUrl || null,
    timestamp: new Date().toISOString()
  },
  ...rest
})

Source: /home/daytona/workspace/source/backend/src/utils/buildResponse.js:11-23

Earthquake Data Format (GeoJSON)

Earthquake data in the payload follows the GeoJSON Feature format:

{
  "type": "Feature",
  "id": "20260303_0000001",
  "properties": {
    "mag": 4.5,
    "place": "10 km NE of Rome, Italy",
    "time": 1709481234000,
    "updated": 1709481300000,
    "tz": null,
    "url": "https://terremoti.ingv.it/event/20260303_0000001",
    "detail": "https://terremoti.ingv.it/fdsnws/event/1/query?eventid=20260303_0000001",
    "felt": null,
    "cdi": null,
    "mmi": null,
    "alert": null,
    "status": "automatic",
    "tsunami": 0,
    "sig": 312,
    "net": "iv",
    "code": "20260303_0000001",
    "ids": ",iv20260303_0000001,",
    "sources": ",iv,",
    "types": ",origin,phase-data,",
    "nst": null,
    "dmin": null,
    "rms": 0.3,
    "gap": null,
    "magType": "ml",
    "type": "earthquake",
    "title": "M 4.5 - 10 km NE of Rome, Italy"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [12.5663, 41.9028, 10.0]
  }
}

GeoJSON Feature Fields

type

string

Always "Feature" for earthquake records

string

Unique identifier for the earthquake event

properties

object

Earthquake properties and metadata

Show key properties

mag

number

Earthquake magnitude (e.g., 4.5)

place

string

Human-readable location description

time

integer

Unix timestamp in milliseconds when the earthquake occurred

updated

integer

Unix timestamp in milliseconds when the data was last updated

url

string

URL to detailed information on the INGV website

status

string

Event status: "automatic", "reviewed", or "manual"

magType

string

Magnitude type: "ml" (local magnitude), "mw" (moment magnitude), etc.

type

string

Event type, typically "earthquake"

geometry

object

GeoJSON geometry object

Show properties

type

string

Always "Point" for earthquake locations

coordinates

array

Array of [longitude, latitude, depth]

longitude: Decimal degrees (e.g., 12.5663)
latitude: Decimal degrees (e.g., 41.9028)
depth: Depth in kilometers below sea level (e.g., 10.0)

Complete Response Examples

Recent Earthquakes

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquakes recent events",
  "payload": [
    {
      "type": "Feature",
      "id": "20260303_0000001",
      "properties": {
        "mag": 4.5,
        "place": "10 km NE of Rome, Italy",
        "time": 1709481234000,
        "magType": "ml",
        "type": "earthquake"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [12.5663, 41.9028, 10.0]
      }
    },
    {
      "type": "Feature",
      "id": "20260303_0000002",
      "properties": {
        "mag": 3.2,
        "place": "Central Italy",
        "time": 1709481100000,
        "magType": "ml",
        "type": "earthquake"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [13.2, 42.8, 8.5]
      }
    }
  ],
  "totalEarthquakes": 1247,
  "pagination": {
    "page": 1,
    "totalPages": 25,
    "limit": 50,
    "hasMore": true
  },
  "meta": {
    "method": "GET",
    "path": "/earthquakes/recent?limit=50",
    "timestamp": "2026-03-03T10:30:45.123Z"
  }
}

Earthquakes by Magnitude

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquakes filtered by magnitude",
  "payload": [
    {
      "type": "Feature",
      "id": "20260302_0000045",
      "properties": {
        "mag": 5.2,
        "place": "Tyrrhenian Sea",
        "time": 1709395200000,
        "magType": "mw",
        "type": "earthquake"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [14.5, 39.2, 15.0]
      }
    }
  ],
  "totalEarthquakes": 23,
  "pagination": {
    "page": 1,
    "totalPages": 1,
    "limit": 50,
    "hasMore": false
  },
  "meta": {
    "method": "GET",
    "path": "/earthquakes/magnitude?mag=5.0",
    "timestamp": "2026-03-03T10:30:45.123Z"
  }
}

Empty Results

When no earthquakes match the query:

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Earthquakes filtered by magnitude",
  "payload": [],
  "totalEarthquakes": 0,
  "pagination": {
    "page": 1,
    "totalPages": 0,
    "limit": 50,
    "hasMore": false
  },
  "meta": {
    "method": "GET",
    "path": "/earthquakes/magnitude?mag=9.0",
    "timestamp": "2026-03-03T10:30:45.123Z"
  }
}

Working with Timestamps

All timestamps in the API are provided in different formats:

ISO 8601 Format (meta.timestamp)

"timestamp": "2026-03-03T10:30:45.123Z"

const timestamp = "2026-03-03T10:30:45.123Z";
const date = new Date(timestamp);
console.log(date.toLocaleString()); // "3/3/2026, 10:30:45 AM"

Unix Timestamp in Milliseconds (properties.time)

"time": 1709481234000

const time = 1709481234000;
const date = new Date(time);
console.log(date.toISOString()); // "2026-03-03T10:33:54.000Z"

Filtering and Sorting Responses

Some endpoints support additional query parameters to filter and sort results:

Sorting

# Sort by magnitude (descending)
curl "https://api.terraquakeapi.com/earthquakes/recent?sort=-magnitude"

# Sort by time (ascending)
curl "https://api.terraquakeapi.com/earthquakes/recent?sort=time"

# Multiple sort fields
curl "https://api.terraquakeapi.com/earthquakes/recent?sort=-magnitude,time"

Sortable fields: time, magnitude, depth Sort order:

Prefix with - for descending (e.g., -magnitude)
No prefix for ascending (e.g., time)

Field Selection

# Request specific fields only
curl "https://api.terraquakeapi.com/earthquakes/recent?fields=time,magnitude,place"

Response with field selection:

{
  "payload": [
    {
      "time": 1709481234000,
      "magnitude": 4.5,
      "place": "10 km NE of Rome, Italy"
    }
  ]
}

Available fields: time, magnitude, depth, place, coordinates

Parsing Responses

JavaScript/TypeScript

interface APIResponse {
  success: boolean;
  code: number;
  status: string;
  message: string;
  payload: EarthquakeFeature[];
  totalEarthquakes?: number;
  pagination?: {
    page: number;
    totalPages: number;
    limit: number;
    hasMore: boolean;
  };
  meta: {
    method: string;
    path: string;
    timestamp: string;
  };
}

interface EarthquakeFeature {
  type: 'Feature';
  id: string;
  properties: {
    mag: number;
    place: string;
    time: number;
    magType: string;
    type: string;
  };
  geometry: {
    type: 'Point';
    coordinates: [number, number, number]; // [lon, lat, depth]
  };
}

const response = await fetch('https://api.terraquakeapi.com/earthquakes/recent');
const data: APIResponse = await response.json();

// Access earthquake data
data.payload.forEach(earthquake => {
  const { mag, place, time } = earthquake.properties;
  const [lon, lat, depth] = earthquake.geometry.coordinates;
  
  console.log(`M${mag} - ${place}`);
  console.log(`Location: ${lat}, ${lon}`);
  console.log(`Depth: ${depth} km`);
  console.log(`Time: ${new Date(time).toISOString()}`);
});

Python

import requests
from typing import List, Dict, Any

def get_earthquakes() -> Dict[str, Any]:
    response = requests.get('https://api.terraquakeapi.com/earthquakes/recent')
    return response.json()

data = get_earthquakes()

# Access earthquake data
for earthquake in data['payload']:
    props = earthquake['properties']
    coords = earthquake['geometry']['coordinates']
    
    mag = props['mag']
    place = props['place']
    lon, lat, depth = coords
    
    print(f"M{mag} - {place}")
    print(f"Location: {lat}, {lon}")
    print(f"Depth: {depth} km")

Best Practices

Check Success Field

Always verify success is true before processing the payload.

Use Pagination Metadata

Check pagination.hasMore to determine if more data exists.

Parse Timestamps Correctly

Convert properties.time from milliseconds and meta.timestamp from ISO 8601.

Handle Empty Payloads

Check if payload is empty or totalEarthquakes is 0 before processing.

Common Questions

Why are coordinates in [longitude, latitude] order?

This follows the GeoJSON specification, which uses [longitude, latitude, altitude] order (x, y, z). This differs from common “lat, lon” notation.

What timezone are timestamps in?

All timestamps are in UTC. Convert to your local timezone as needed.

Can I request the response in a different format (XML, CSV)?

Currently, the API only supports JSON responses following the GeoJSON standard for earthquake data.

What's the difference between 'code' and 'status'?

code: Numeric HTTP status code (e.g., 200)
status: Text representation (e.g., "OK")

Both convey the same information in different formats.

Get Started

Core Concepts

Guides

Overview

Standard Response Structure

Core Response Fields

Additional Fields

Response Builder Implementation

Earthquake Data Format (GeoJSON)

GeoJSON Feature Fields

Complete Response Examples

Recent Earthquakes

Earthquakes by Magnitude

Empty Results

Working with Timestamps

ISO 8601 Format (meta.timestamp)

Unix Timestamp in Milliseconds (properties.time)

Filtering and Sorting Responses

Sorting

Field Selection

Parsing Responses

JavaScript/TypeScript

Python

Best Practices

Check Success Field

Use Pagination Metadata

Parse Timestamps Correctly

Handle Empty Payloads

Common Questions

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Overview

​Standard Response Structure

​Core Response Fields

​Additional Fields

​Response Builder Implementation

​Earthquake Data Format (GeoJSON)

​GeoJSON Feature Fields

​Complete Response Examples

​Recent Earthquakes

​Earthquakes by Magnitude

​Empty Results

​Working with Timestamps

​ISO 8601 Format (meta.timestamp)

​Unix Timestamp in Milliseconds (properties.time)

​Filtering and Sorting Responses

​Sorting

​Field Selection

​Parsing Responses

​JavaScript/TypeScript

​Python

​Best Practices

Check Success Field

Use Pagination Metadata

Parse Timestamps Correctly

Handle Empty Payloads

​Common Questions

Build docs developers (and LLMs) love

Overview

Standard Response Structure

Core Response Fields

Additional Fields

Response Builder Implementation

Earthquake Data Format (GeoJSON)

GeoJSON Feature Fields

Complete Response Examples

Recent Earthquakes

Earthquakes by Magnitude

Empty Results

Working with Timestamps

ISO 8601 Format (meta.timestamp)

Unix Timestamp in Milliseconds (properties.time)

Filtering and Sorting Responses

Sorting

Field Selection

Parsing Responses

JavaScript/TypeScript

Python

Best Practices

Common Questions