Metadata-Version: 2.4
Name: quakefyi
Version: 0.1.1
Summary: Earthquake seismic data and tectonic plates API client — quakefyi.com
Project-URL: Homepage, https://quakefyi.com
Project-URL: Documentation, https://quakefyi.com/developers/
Project-URL: Repository, https://github.com/fyipedia/quakefyi
Project-URL: Issues, https://github.com/fyipedia/quakefyi/issues
Project-URL: Changelog, https://github.com/fyipedia/quakefyi/releases
Author: FYIPedia
License-Expression: MIT
License-File: LICENSE
Keywords: earthquake,geology,magnitude,natural-disaster,richter,seismic,tectonic,usgs
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.15; extra == 'all'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# quakefyi

[![PyPI version](https://agentgif.com/badge/pypi/quakefyi/version.svg)](https://pypi.org/project/quakefyi/)
[![Python](https://img.shields.io/pypi/pyversions/quakefyi)](https://pypi.org/project/quakefyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/quakefyi/)

Python API client for [quakefyi.com](https://quakefyi.com/) -- the comprehensive earthquake and seismology database covering earthquakes, tectonic plates, fault lines, historical events, and yearly summaries. Access seismic data, magnitude records, and geological case studies through a free REST API, CLI, or MCP server for AI assistants.

[QuakeFYI](https://quakefyi.com/) catalogs earthquake events with magnitude, depth, location data, tectonic plate boundaries, and fault classifications -- built for developers, geoscientists, and educators who need structured seismological data.

> **Explore earthquakes at [quakefyi.com](https://quakefyi.com/)** -- browse seismic events, tectonic plates, and fault lines.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/quakefyi/main/demo.gif" alt="quakefyi demo -- earthquake seismic data API client for Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Earthquake Data and Magnitude Scales](#earthquake-data-and-magnitude-scales)
  - [Tectonic Plates and Boundaries](#tectonic-plates-and-boundaries)
  - [Fault Lines and Seismic Zones](#fault-lines-and-seismic-zones)
  - [Historical Earthquakes and Case Studies](#historical-earthquakes-and-case-studies)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Earthquakes](#learn-more-about-earthquakes)
- [Geo FYI Family](#geo-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

```bash
pip install quakefyi              # Core (zero deps)
pip install "quakefyi[cli]"       # + Command-line interface
pip install "quakefyi[mcp]"       # + MCP server for AI assistants
pip install "quakefyi[api]"       # + HTTP client for quakefyi.com API
pip install "quakefyi[all]"       # Everything
```

## Quick Start

```python
from quakefyi.api import QuakeFYI

with QuakeFYI() as api:
    # List earthquakes in the database
    earthquakes = api.list_earthquakes()

    # Get detailed info for a specific earthquake event
    event = api.get_earthquake("2011-tohoku")

    # Browse tectonic plates
    plates = api.list_plates()
    pacific = api.get_plate("pacific-plate")

    # Search across all seismological content
    results = api.search("San Andreas")
```

## What You Can Do

### Earthquake Data and Magnitude Scales

Earthquake magnitude quantifies the energy released at the source. The moment magnitude scale (Mw) has replaced the older Richter scale (ML) for most scientific and engineering purposes because it does not saturate at high magnitudes. A magnitude increase of 1.0 represents roughly 31.6 times more energy released.

| Magnitude (Mw) | Classification | Effects | Approximate Annual Frequency |
|----------------|---------------|---------|------------------------------|
| < 2.0 | Micro | Not felt, recorded by instruments | ~1,300,000 |
| 2.0 -- 3.9 | Minor | Often felt, rarely causes damage | ~130,000 |
| 4.0 -- 4.9 | Light | Noticeable shaking, minor damage | ~13,000 |
| 5.0 -- 5.9 | Moderate | Can cause damage to weak structures | ~1,300 |
| 6.0 -- 6.9 | Strong | Destructive in populated areas | ~130 |
| 7.0 -- 7.9 | Major | Serious damage over large areas | ~15 |
| 8.0+ | Great | Devastating, can trigger tsunamis | ~1 |

```python
from quakefyi.api import QuakeFYI

# Retrieve earthquake data with magnitude, depth, and location
with QuakeFYI() as api:
    quake = api.get_earthquake("2011-tohoku")
    print(quake["name"])       # 2011 Tohoku earthquake
    print(quake)               # Full event data including magnitude and coordinates

    # Browse yearly summaries of seismic activity
    summaries = api.list_yearly_summaries()
```

Learn more: [Browse Earthquakes](https://quakefyi.com/) · [Glossary](https://quakefyi.com/glossary/) · [Guides](https://quakefyi.com/guides/)

### Tectonic Plates and Boundaries

Earth's lithosphere is divided into major and minor tectonic plates that float on the semi-fluid asthenosphere. Plate boundaries are where most earthquakes occur. There are three boundary types: divergent (plates move apart), convergent (plates collide), and transform (plates slide past each other).

| Plate | Type | Area (million km2) | Notable Boundary |
|-------|------|-------------------|------------------|
| Pacific | Oceanic | 103.3 | Ring of Fire (subduction zones) |
| North American | Continental + Oceanic | 75.9 | San Andreas Fault (transform) |
| Eurasian | Continental + Oceanic | 67.8 | Himalayas (convergent) |
| African | Continental + Oceanic | 61.3 | East African Rift (divergent) |
| Antarctic | Continental + Oceanic | 60.9 | Mid-ocean ridges |
| Indo-Australian | Continental + Oceanic | 58.9 | Sunda megathrust |
| South American | Continental + Oceanic | 43.6 | Andes subduction zone |

```python
from quakefyi.api import QuakeFYI

# Explore tectonic plates and their boundaries
with QuakeFYI() as api:
    plates = api.list_plates()
    pacific = api.get_plate("pacific-plate")

    # Browse by country to see regional seismic risk
    countries = api.list_countries()
    japan = api.get_country("japan")
```

Learn more: [Tectonic Plates](https://quakefyi.com/) · [Countries](https://quakefyi.com/) · [API Docs](https://quakefyi.com/developers/)

### Fault Lines and Seismic Zones

A fault is a fracture in the Earth's crust along which blocks of rock have moved relative to each other. Faults are classified by the direction of movement: normal faults (extensional), reverse/thrust faults (compressional), and strike-slip faults (lateral).

| Fault Type | Movement | Tectonic Setting | Example |
|-----------|----------|-----------------|---------|
| Normal | Hanging wall drops | Divergent boundary, rifting | Basin and Range, USA |
| Reverse (Thrust) | Hanging wall rises | Convergent boundary, compression | Himalayan frontal thrust |
| Strike-slip | Lateral sliding | Transform boundary | San Andreas Fault |
| Oblique-slip | Combined vertical + lateral | Complex tectonic zones | Alpine Fault, New Zealand |

```python
from quakefyi.api import QuakeFYI

# Explore fault lines and their classifications
with QuakeFYI() as api:
    faults = api.list_faults()
    san_andreas = api.get_fault("san-andreas-fault")

    # Access seismology glossary terms
    glossary = api.list_glossary()
    term = api.get_term("epicenter")
```

Learn more: [Fault Lines](https://quakefyi.com/) · [Glossary](https://quakefyi.com/glossary/) · [FAQs](https://quakefyi.com/)

### Historical Earthquakes and Case Studies

Historical earthquakes provide critical data for understanding seismic hazard and improving building codes. The deadliest recorded earthquake was the 1556 Shaanxi earthquake in China, which killed an estimated 830,000 people. The strongest instrumentally recorded earthquake was the 1960 Valdivia earthquake in Chile at Mw 9.5.

```python
from quakefyi.api import QuakeFYI

# Explore historical earthquakes and case studies
with QuakeFYI() as api:
    historical = api.list_historical()
    case_studies = api.list_case_studies()
    study = api.get_case_study("1906-san-francisco")

    # Read expert guides on seismology topics
    guides = api.list_guides()
```

Learn more: [Historical Earthquakes](https://quakefyi.com/) · [Case Studies](https://quakefyi.com/) · [Guides](https://quakefyi.com/guides/)

## Command-Line Interface

```bash
pip install "quakefyi[cli]"

# Search for earthquakes
quakefyi search "Tohoku 2011"

# Output is JSON for easy piping
quakefyi search "magnitude 9" | jq '.results[0]'
```

## MCP Server (Claude, Cursor, Windsurf)

Add earthquake data tools to any AI assistant that supports [Model Context Protocol](https://modelcontextprotocol.io/).

```bash
pip install "quakefyi[mcp]"
```

Add to your `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "quakefyi": {
            "command": "python",
            "args": ["-m", "quakefyi.mcp_server"]
        }
    }
}
```

**Available tools**: `search_quakefyi`

## REST API Client

```python
from quakefyi.api import QuakeFYI

with QuakeFYI() as api:
    # List endpoints
    earthquakes = api.list_earthquakes()
    plates = api.list_plates()
    faults = api.list_faults()
    historical = api.list_historical()
    glossary = api.list_glossary()
    guides = api.list_guides()

    # Detail endpoints
    quake = api.get_earthquake("2011-tohoku")
    plate = api.get_plate("pacific-plate")

    # Search
    results = api.search("tsunami")
```

## API Reference

| Method | Description |
|--------|-------------|
| `list_earthquakes(**params)` | List all earthquakes |
| `get_earthquake(slug)` | Get earthquake detail |
| `list_plates(**params)` | List all tectonic plates |
| `get_plate(slug)` | Get plate detail |
| `list_faults(**params)` | List all fault lines |
| `get_fault(slug)` | Get fault detail |
| `list_historical(**params)` | List historical earthquakes |
| `get_historical(slug)` | Get historical earthquake detail |
| `list_case_studies(**params)` | List all case studies |
| `get_case_study(slug)` | Get case study detail |
| `list_yearly_summaries(**params)` | List yearly summaries |
| `get_yearly_summary(slug)` | Get yearly summary detail |
| `list_countries(**params)` | List all countries |
| `get_country(slug)` | Get country detail |
| `list_glossary(**params)` | List glossary terms |
| `get_term(slug)` | Get glossary term detail |
| `list_guides(**params)` | List all guides |
| `get_guide(slug)` | Get guide detail |
| `list_faqs(**params)` | List all FAQs |
| `get_faq(slug)` | Get FAQ detail |
| `search(query)` | Search across all content |

Full API documentation at [quakefyi.com/developers/](https://quakefyi.com/developers/).

## Learn More About Earthquakes

- **Browse**: [Earthquakes](https://quakefyi.com/) · [Tectonic Plates](https://quakefyi.com/) · [Faults](https://quakefyi.com/)
- **Guides**: [Glossary](https://quakefyi.com/glossary/) · [Guides](https://quakefyi.com/guides/)
- **API**: [REST API Docs](https://quakefyi.com/developers/) · [OpenAPI Spec](https://quakefyi.com/api/openapi.json)

## Geo FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem -- geography, distance, elevation, and natural events.

| Package | PyPI | Description |
|---------|------|-------------|
| distancefyi | [PyPI](https://pypi.org/project/distancefyi/) | Haversine distance & travel times -- [distancefyi.com](https://distancefyi.com/) |
| mountainfyi | [PyPI](https://pypi.org/project/mountainfyi/) | Mountains, peaks, elevation, climbing routes -- [mountainfyi.com](https://mountainfyi.com/) |
| **quakefyi** | [PyPI](https://pypi.org/project/quakefyi/) | **Earthquakes, seismic data, tectonic plates -- [quakefyi.com](https://quakefyi.com/)** |
| zipfyi | [PyPI](https://pypi.org/project/zipfyi/) | ZIP/postal codes, geocoding, area lookup -- [zipfyi.com](https://zipfyi.com/) |

## FYIPedia Developer Tools

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| colorfyi | [PyPI](https://pypi.org/project/colorfyi/) | [npm](https://www.npmjs.com/package/@fyipedia/colorfyi) | Color conversion, WCAG contrast, harmonies -- [colorfyi.com](https://colorfyi.com/) |
| emojifyi | [PyPI](https://pypi.org/project/emojifyi/) | [npm](https://www.npmjs.com/package/emojifyi) | Emoji encoding & metadata -- [emojifyi.com](https://emojifyi.com/) |
| symbolfyi | [PyPI](https://pypi.org/project/symbolfyi/) | [npm](https://www.npmjs.com/package/symbolfyi) | Symbol encoding in 11 formats -- [symbolfyi.com](https://symbolfyi.com/) |
| unicodefyi | [PyPI](https://pypi.org/project/unicodefyi/) | [npm](https://www.npmjs.com/package/unicodefyi) | Unicode lookup with 17 encodings -- [unicodefyi.com](https://unicodefyi.com/) |
| fontfyi | [PyPI](https://pypi.org/project/fontfyi/) | [npm](https://www.npmjs.com/package/fontfyi) | Google Fonts metadata & CSS -- [fontfyi.com](https://fontfyi.com/) |
| distancefyi | [PyPI](https://pypi.org/project/distancefyi/) | [npm](https://www.npmjs.com/package/distancefyi) | Haversine distance & travel times -- [distancefyi.com](https://distancefyi.com/) |
| timefyi | [PyPI](https://pypi.org/project/timefyi/) | [npm](https://www.npmjs.com/package/timefyi) | Timezone ops & business hours -- [timefyi.com](https://timefyi.com/) |
| namefyi | [PyPI](https://pypi.org/project/namefyi/) | [npm](https://www.npmjs.com/package/namefyi) | Korean romanization & Five Elements -- [namefyi.com](https://namefyi.com/) |
| unitfyi | [PyPI](https://pypi.org/project/unitfyi/) | [npm](https://www.npmjs.com/package/unitfyi) | Unit conversion, 220 units -- [unitfyi.com](https://unitfyi.com/) |
| holidayfyi | [PyPI](https://pypi.org/project/holidayfyi/) | [npm](https://www.npmjs.com/package/holidayfyi) | Holiday dates & Easter calculation -- [holidayfyi.com](https://holidayfyi.com/) |
| **quakefyi** | [PyPI](https://pypi.org/project/quakefyi/) | -- | **Earthquakes, seismic data, tectonic plates -- [quakefyi.com](https://quakefyi.com/)** |
| cocktailfyi | [PyPI](https://pypi.org/project/cocktailfyi/) | -- | Cocktail ABV, calories, flavor -- [cocktailfyi.com](https://cocktailfyi.com/) |
| fyipedia | [PyPI](https://pypi.org/project/fyipedia/) | -- | Unified CLI for all FYI tools -- [fyipedia.com](https://fyipedia.com/) |

## License

MIT
