Skip to content

nagcas/TerraQuakeApi

BranchesTags

Repository files navigation

TerraQuake API

License GitHub Stars GitHub Issues PRs Welcome

A modern, open-source seismic data platform providing real-time earthquake information through a RESTful API and interactive visualization interface.

Getting Started • Frontend Features • API Reference • Support the Project • Contributing

Overview

TerraQuake is a comprehensive seismic data platform that combines a powerful REST API with an intuitive web interface. It provides researchers, developers, and organizations with easy access to real-time earthquake data, advanced filtering capabilities, and interactive visualizations.

🌍 Support Terraquake API

Terraquake API is an open-source project created to provide fast, reliable, and accessible seismic data. Maintaining servers, fetching real-time data, and keeping the API fast and free requires continuous work and infrastructure costs.

If this project has helped you build an app, fetch data, or learn something new, please consider supporting its development! Every coffee keeps the servers running and sparks new features.

ko-fi

Thank you so much for your generosity and for being part of this journey! 🚀

Project Overview

  • Backend (TerraQuake API) — Node.js + Express REST API to serve earthquake data.
  • Frontend — React + TailwindCSS interface for visualizing seismic events.
  • Data Source — INGV (Istituto Nazionale di Geofisica e Vulcanologia) and synthetic demo data.
  • API Access — Public endpoints for querying earthquakes by time, magnitude, location, and more.

Technologies Used

Backend

  • Node.js
  • Express
  • MongoDB (planned for persistent data)
  • JWT (for secure access, future feature)
  • Custom earthquake generator (for demo/testing)

Frontend

  • React 19
  • Vite
  • Tailwind CSS 4
  • React Router
  • Hero sections, maps, charts (via Leaflet, Chart.js – if added)

Getting Started

Prerequisites

  • Node.js (v18+ recommended)
  • Git

Installation

  1. Clone the repository:

    git clone https://github.com/nagcas/TerraQuakeApi.git
cd TerraQuakeApi

  2. Install backend dependencies:

    cd backend
pnpm install

  3. Install frontend dependencies:

    cd ../frontend
pnpm install

  4. Set up environment variables:

    • Copy backend/.env-example to backend/.env and fill in required values (e.g., database URL, API keys).
    • Copy frontend/.env-example to frontend/.env if needed.

  5. Run the backend:

    cd backend
pnpm start

  6. Run the frontend (in a new terminal):

    cd frontend
pnpm dev

Visit http://localhost:5173 for the frontend interface and http://localhost:5001 for the API endpoints.

API Reference

The TerraQuake API provides various endpoints for querying earthquake data. For detailed usage, examples, and testing, visit the API Docs.

Earthquake API Endpoints

All endpoints support pagination:

  • page (optional, default: 1) → Page number
  • limit (optional, default: 50) → Number of results per page
Method Endpoint Description Query Parameters
GET /v1/earthquakes/recent Fetches recent earthquakes from the start of the year to today. page, limit
GET /v1/earthquakes/today Fetches earthquakes that occurred today. page, limit
GET /v1/earthquakes/last-week Fetches earthquakes from the last 7 days. page, limit
GET /v1/earthquakes/month Fetches earthquakes for a specific month/year. year (required), month (required), page, limit
GET /v1/earthquakes/location Fetches earthquakes near a latitude/longitude. latitude (required), longitude (required), radius, page, limit
GET /v1/earthquakes/region Fetches earthquakes in a specific Italian region. region (required), page, limit
GET /v1/earthquakes/depth Fetches earthquakes at or below a specific depth. depth (required), page, limit
GET /v1/earthquakes/range-time Fetches earthquakes within a date range. startdate (required), enddate (required), page, limit
GET /v1/earthquakes/magnitude Fetches earthquakes of a specific magnitude or higher. mag (required), page, limit
GET /v1/earthquakes/eventId Fetches details of a specific earthquake by ID. eventId (required)

Example Request

URL "https://api.terraquakeapi.com/v1/earthquakes/recent?limit=50&page=1"

Example Response

{
  "success": true,
  "code": 200,
  "status": "OK",
  "message": "Recent seismic events",
  "payload": [
    {
      "type": "Feature",
      "properties": {
        "eventId": 44278572,
        "originId": 140102761,
        "time": "2025-09-26T19:33:46.440000",
        "author": "SURVEY-INGV",
        "magType": "ML",
        "mag": 1,
        "magAuthor": "--",
        "type": "earthquake",
        "place": "Costa Calabra sud-orientale (Reggio di Calabria)",
        "version": 100,
        "geojson_creationTime": "2025-09-26T20:34:27"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          16.2387,
          37.9982,
          10.5
        ],
       "meta": {
          "method": "GET",
          "path": "/v1/earthquakes/recent?limit=50&page=1",
          "timestamp": "2025-11-06T00:40:01.490Z"
        },
        "totalEarthquakes": 14157,
        "pagination": {
          "page": 1,
          "totalPages": 284,
          "limit": 50,
          "hasMore": true
        }
      }
    }
  ]
}

Response Fields:

Field Description
success Indicates whether the request was successful
code HTTP status code
status Status message
message Summary of the response
payload Array of seismic event objects
properties.eventId Unique event ID
properties.time Event timestamp (ISO 8601)
properties.mag Magnitude of the earthquake
properties.place Location description
geometry.coordinates [longitude, latitude, depth]
meta [method, path, timestamp]
meta [method, path, timestamp]
totalEarthquakes Total number of events returned
pagination [page, totalPages, limit, hasMore]

Stations API Endpoints

All endpoints support pagination:

  • page (optional, default: 1) → Page number
  • limit (optional, default: 50) → Number of results per page
Method Endpoint Description Query Parameters
GET /v1/stations Retrieve all seismic monitoring stations (INGV network). page, limit
GET /v1/stations/code Retrieve a station by its station code. code* (required)
GET /v1/stations/geojson Retrieve all stations formatted as GeoJSON for mapping tools. page, limit
GET /v1/stations/status/open List all currently active/operational stations. page, limit
GET /v1/stations/status/closed List stations that are no longer operational. page, limit
GET /v1/stations/statistics Provides aggregated information about the station network. no parameters

Frontend Features

  • Visualize earthquakes on an interactive map
  • Filter events by date
  • View statistics in chart format
  • Educational UI: earthquake basics and seismic zones (planned)
  • Search and filter functionality

Analytics Microservice (Django + AI)

A new analytics microservice is being introduced to extend TerraQuake API with advanced data processing and seismic intelligence capabilities.

This service is built with Django + Django REST Framework and is responsible for transforming raw seismic events into structured insights, statistics, and machine learning-based analysis.

Architecture Role Receives seismic event data from the Node.js backend Processes and aggregates events by region, time, and magnitude Exposes analytical REST APIs for frontend and external services Serves as the foundation for AI-based seismic interpretation models.

Core Responsibilities

Regional seismic statistics (events per area, magnitude distribution)

  • Temporal analysis (daily, weekly, monthly trends)
  • Detection of seismic clusters and swarms
  • Data enrichment for geographic and depth-based insights
  • Preparation of datasets for AI/ML models

AI / Machine Learning Integration

The microservice will also integrate Python-based machine learning models to enhance seismic analysis.

Planned capabilities include:

  • Anomaly detection on seismic activity patterns
  • Clustering of events based on spatial and temporal proximity
  • Pattern recognition for recurring seismic sequences
  • Support for predictive analytics experiments (research phase)

Technologies planned:

  • Scikit-learn (clustering & anomaly detection)
  • Pandas / NumPy (data processing)
  • Future extensions with deep learning models (LSTM / time-series models)

Author

Dr. Gianluca Chiaravalloti Web Developer & Geologist LinkedIn Portfolio

Contributing

Contributions are welcome!
If you’d like to improve TerraQuake API, please fork the repository and open a pull request.
Whether it’s fixing a bug, improving documentation, or adding a feature — all contributions are appreciated!

Please make sure to follow the contributing guidelines.

Community

Join our community on Discord to connect, share ideas, and collaborate with other contributors.

Hacktoberfest 2025

This project is participating in Hacktoberfest 2025!
Contributions count toward the event. Feel free to submit PRs and join us in building TerraQuake API together 🌍

Credits

Core Team

  • Dr. Gianluca Chiaravalloti - Project Lead & Founder

Key Contributors

  • International team of 5 collaborators contributing to:
    • Backend Development
    • Frontend Enhancements
    • Testing & Quality Assurance
    • Documentation
    • Community Support

Data Sources & Partners

  • INGV (Istituto Nazionale di Geofisica e Vulcanologia)
    • Primary source of seismic data
    • Technical consultation on seismological aspects

Technologies & Resources

  • Frontend Technologies

    • React.js Documentation & Community
    • Tailwind CSS Framework
    • Vite Build Tool
    • OpenStreetMap for geographical data

  • Backend Technologies

    • Node.js & Express.js Communities
    • MongoDB Documentation & Support
    • JWT Authentication Resources
    • ESLint & StandardJS

Special Thanks

  • Open Source Community
  • Early Adopters & Testers
  • Bug Reporters & Feature Requesters
  • Documentation Contributors

Support the Project

TerraQuake API is an open-source initiative aimed at making real-time seismic data accessible for developers, researchers, and communities.

If you find this project useful and would like to support its development, consider becoming a sponsor. Your contribution helps:

Maintain and improve the API

Add new features and documentation

Keep the project open and accessible to everyone

Even a small donation makes a big difference in keeping the project alive and growing.

Sponsor

Thank you for supporting open source and helping TerraQuake API reach more people! 🌍

About

A developer-friendly REST API for exploring and analyzing seismic events across Italy and beyond. Built with Node.js, Express, MongoDB, Python, Django, Django Rest-Framework

www.terraquakeapi.com

Topics

react nodejs python open-source django express mongodb django-rest-framework axios api-rest hacktoberfest tailwindcss

Resources

Readme

License

AGPL-3.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

31 stars

Watchers

1 watching

Forks

46 forks
Report repository

Releases

No releases published

Sponsor this project

  •  
Learn more about GitHub Sponsors

Packages

 
 
 

Contributors

Languages