Metadata-Version: 2.4
Name: mountainfyi
Version: 0.1.1
Summary: Mountains, peaks and elevation data API client — mountainfyi.com
Project-URL: Homepage, https://mountainfyi.com
Project-URL: Documentation, https://mountainfyi.com/developers/
Project-URL: Repository, https://github.com/fyipedia/mountainfyi
Project-URL: Issues, https://github.com/fyipedia/mountainfyi/issues
Project-URL: Changelog, https://github.com/fyipedia/mountainfyi/releases
Author: FYIPedia
License-Expression: MIT
License-File: LICENSE
Keywords: altitude,climbing,elevation,geography,hiking,mountain,peak,summit
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

# mountainfyi

[![PyPI version](https://agentgif.com/badge/pypi/mountainfyi/version.svg)](https://pypi.org/project/mountainfyi/)
[![Python](https://img.shields.io/pypi/pyversions/mountainfyi)](https://pypi.org/project/mountainfyi/)
[![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/mountainfyi/)

Python API client for [mountainfyi.com](https://mountainfyi.com/) -- the comprehensive mountain and peak database covering mountains, ranges, climbing routes, and seasonal conditions across all continents. Browse elevation records, summit data, and route details through a free REST API, CLI, or MCP server for AI assistants.

[MountainFYI](https://mountainfyi.com/) catalogs peaks and ranges worldwide with elevation data, geographic coordinates, climbing routes, and seasonal condition reports -- built for developers, geographers, and outdoor enthusiasts who need structured mountain data.

> **Explore mountains at [mountainfyi.com](https://mountainfyi.com/)** -- browse peaks by continent, country, or mountain range.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/mountainfyi/main/demo.gif" alt="mountainfyi demo -- mountain 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)
  - [Explore Mountains and Peaks](#explore-mountains-and-peaks)
  - [Browse Mountain Ranges](#browse-mountain-ranges)
  - [Climbing Routes and Conditions](#climbing-routes-and-conditions)
- [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 Mountains](#learn-more-about-mountains)
- [Geo FYI Family](#geo-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

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

## Quick Start

```python
from mountainfyi.api import MountainFYI

with MountainFYI() as api:
    # List all mountains in the database
    mountains = api.list_mountains()

    # Get detailed info for a specific peak
    everest = api.get_mountain("mount-everest")

    # Browse mountain ranges
    ranges = api.list_ranges()
    himalayas = api.get_range("himalayas")

    # Search across all mountain content
    results = api.search("K2")
```

## What You Can Do

### Explore Mountains and Peaks

Mountains are classified by prominence, isolation, and elevation. The most recognized classification system ranks peaks by absolute elevation above sea level. The Seven Summits -- the highest peak on each continent -- represent one of mountaineering's most coveted achievements.

| Metric | Description | Example |
|--------|-------------|---------|
| Elevation | Height above sea level | Everest: 8,849 m |
| Prominence | Rise above the highest saddle connecting to a higher peak | Denali: 6,144 m prominence |
| Isolation | Distance to nearest higher peak | Kilimanjaro: 5,510 km isolation |
| Ultra-prominent | Peaks with prominence >= 1,500 m | ~1,524 peaks worldwide |

```python
from mountainfyi.api import MountainFYI

# Retrieve mountain detail with elevation, prominence, and coordinates
with MountainFYI() as api:
    mountain = api.get_mountain("mount-everest")
    print(mountain["name"])        # Mount Everest
    print(mountain["elevation"])   # Elevation in meters

    # Browse mountains by continent
    continents = api.list_continents()
    asia = api.get_continent("asia")
```

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

### Browse Mountain Ranges

A mountain range is a series of mountains connected by high ground. Major ranges form along tectonic plate boundaries -- the Himalayas arose from the collision of the Indian and Eurasian plates, while the Andes trace the subduction zone of the Nazca Plate beneath South America.

| Range | Location | Highest Peak | Length |
|-------|----------|-------------|--------|
| Himalayas | South Asia | Everest (8,849 m) | 2,400 km |
| Andes | South America | Aconcagua (6,961 m) | 7,000 km |
| Alps | Europe | Mont Blanc (4,808 m) | 1,200 km |
| Rockies | North America | Elbert (4,401 m) | 4,800 km |
| Karakoram | Central Asia | K2 (8,611 m) | 500 km |

```python
from mountainfyi.api import MountainFYI

# Explore mountain ranges and their peaks
with MountainFYI() as api:
    ranges = api.list_ranges()
    karakoram = api.get_range("karakoram")

    # Browse by geographic region
    regions = api.list_regions()
    south_asia = api.get_region("south-asia")
```

Learn more: [Browse Ranges](https://mountainfyi.com/) · [Countries](https://mountainfyi.com/) · [API Docs](https://mountainfyi.com/developers/)

### Climbing Routes and Conditions

Climbing routes vary from straightforward trekking peaks to technical ascents requiring ice axes, ropes, and high-altitude experience. Seasonal conditions -- snow depth, temperature, wind speed, and avalanche risk -- determine optimal climbing windows for each peak.

| Grade | Difficulty | Description |
|-------|-----------|-------------|
| F (Facile) | Easy | Walking on paths and easy scrambling |
| PD (Peu Difficile) | Moderate | Simple glacier travel, basic rope work |
| AD (Assez Difficile) | Fairly Difficult | Steeper ice/rock, crevasse navigation |
| D (Difficile) | Difficult | Sustained technical climbing |
| TD (Tres Difficile) | Very Difficult | Serious alpinism, objective hazards |
| ED (Extremement Difficile) | Extremely Difficult | Elite-level mountaineering |

```python
from mountainfyi.api import MountainFYI

# Explore climbing routes and seasonal conditions
with MountainFYI() as api:
    routes = api.list_routes()
    route = api.get_route("everest-south-col")

    # Check seasonal conditions for planning
    conditions = api.list_seasonal_conditions()
```

Learn more: [Routes](https://mountainfyi.com/) · [FAQs](https://mountainfyi.com/) · [Guides](https://mountainfyi.com/guides/)

## Command-Line Interface

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

# Search for mountains
mountainfyi search "Matterhorn"

# Output is JSON for easy piping
mountainfyi search "K2" | jq '.results[0].name'
```

## MCP Server (Claude, Cursor, Windsurf)

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

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

Add to your `claude_desktop_config.json`:

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

**Available tools**: `search_mountainfyi`

## REST API Client

```python
from mountainfyi.api import MountainFYI

with MountainFYI() as api:
    # List endpoints
    mountains = api.list_mountains()
    ranges = api.list_ranges()
    continents = api.list_continents()
    countries = api.list_countries()

    # Detail endpoints
    peak = api.get_mountain("mont-blanc")
    route = api.get_route("normal-route")

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

## API Reference

| Method | Description |
|--------|-------------|
| `list_mountains(**params)` | List all mountains |
| `get_mountain(slug)` | Get mountain detail |
| `list_ranges(**params)` | List all mountain ranges |
| `get_range(slug)` | Get range detail |
| `list_continents(**params)` | List all continents |
| `get_continent(slug)` | Get continent detail |
| `list_countries(**params)` | List all countries |
| `get_country(slug)` | Get country detail |
| `list_regions(**params)` | List all regions |
| `get_region(slug)` | Get region detail |
| `list_routes(**params)` | List all climbing routes |
| `get_route(slug)` | Get route detail |
| `list_seasonal_conditions(**params)` | List seasonal conditions |
| `get_seasonal_condition(slug)` | Get seasonal condition detail |
| `list_faqs(**params)` | List all FAQs |
| `get_faq(slug)` | Get FAQ detail |
| `search(query)` | Search across all content |

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

## Learn More About Mountains

- **Browse**: [Mountains](https://mountainfyi.com/) · [Ranges](https://mountainfyi.com/) · [Countries](https://mountainfyi.com/)
- **Guides**: [Glossary](https://mountainfyi.com/glossary/) · [Guides](https://mountainfyi.com/guides/)
- **API**: [REST API Docs](https://mountainfyi.com/developers/) · [OpenAPI Spec](https://mountainfyi.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/) |
| **mountainfyi** | [PyPI](https://pypi.org/project/mountainfyi/) | -- | **Mountains, peaks, elevation, climbing routes -- [mountainfyi.com](https://mountainfyi.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
