# cablefyi

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

Python API client for submarine cable data. Look up undersea fiber optic cable systems, explore landing station locations, query cable operators and owners, and retrieve route geometries — all from [CableFYI](https://cablefyi.com/), a submarine cable reference platform mapping the physical infrastructure of the global internet.

Over 95% of intercontinental data traffic travels through submarine cables laid on the ocean floor. CableFYI catalogs active and planned cable systems with their landing points, Ready-for-Service (RFS) dates, cable lengths, fiber pair counts, and design capacities — used by network engineers, telecom analysts, and infrastructure researchers.

> **Explore submarine cables at [cablefyi.com](https://cablefyi.com/)** — browse the [cable map](https://cablefyi.com/cables/), search [landing stations](https://cablefyi.com/landing-stations/), and view operator data.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/cablefyi/main/demo.gif" alt="cablefyi demo — submarine cable lookup, landing stations, and fiber optic infrastructure in Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Submarine Cable Systems](#submarine-cable-systems)
  - [Landing Stations](#landing-stations)
  - [Cable Operators and Owners](#cable-operators-and-owners)
  - [Fiber Optic Technology](#fiber-optic-technology)
- [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 Submarine Cables](#learn-more-about-submarine-cables)
- [Also Available](#also-available)
- [Network FYI Family](#network-fyi-family)
- [License](#license)

## Install

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

## Quick Start

```python
from cablefyi.api import CableFYI

with CableFYI() as api:
    # Look up a submarine cable system
    cable = api.get_cable("marea")
    print(cable["name"])             # MAREA
    print(cable["length_km"])        # 6,605 km
    print(cable["rfs_year"])         # 2018
    print(cable["owners"])           # Microsoft, Meta, Telxius

    # List cables by country
    cables = api.list_cables(country="united-states")
    for c in cables:
        print(f"{c['name']}: {c['length_km']} km")

    # Search cable infrastructure
    results = api.search("transatlantic")
```

## What You Can Do

### Submarine Cable Systems

Submarine telecommunications cables are the backbone of the global internet. Each cable system consists of fiber optic strands encased in protective layers (polyethylene, steel wire, copper) laid on the ocean floor. Modern cables contain multiple fiber pairs, each carrying terabits per second using wavelength-division multiplexing (WDM).

| Era | Capacity per Fiber Pair | Example Cable |
|-----|------------------------|---------------|
| 2000s | 640 Gbps | FLAG Atlantic-1 |
| 2010s | 10-20 Tbps | AEConnect, Hibernia Express |
| 2018+ | 20-80 Tbps | MAREA (224 Tbps total), Dunant |
| 2024+ | 100+ Tbps | Firmina, Echo/Bifrost |

```python
from cablefyi.api import CableFYI

with CableFYI() as api:
    # Get full cable system details
    cable = api.get_cable("dunant")
    print(f"Name: {cable['name']}")
    print(f"Length: {cable['length_km']} km")
    print(f"Fiber pairs: {cable.get('fiber_pairs')}")
    print(f"RFS: {cable.get('rfs_year')}")
    print(f"Owners: {cable.get('owners')}")
```

Learn more: [Cable Directory](https://cablefyi.com/cables/) · [Glossary](https://cablefyi.com/glossary/)

### Landing Stations

Landing stations are the shore-based facilities where submarine cables come ashore and connect to terrestrial networks. Major landing hubs include Bude (UK), Marseille (France), Tuas (Singapore), and Virginia Beach (US) — each serving as a critical junction for dozens of cable systems.

```python
from cablefyi.api import CableFYI

with CableFYI() as api:
    # List landing stations by country
    stations = api.list_landing_stations(country="united-kingdom")
    for s in stations:
        print(f"{s['name']}: {s.get('cable_count', 0)} cables")

    # Get landing station details
    station = api.get_landing_station("bude")
    for cable in station.get("cables", []):
        print(f"  {cable['name']}")
```

Learn more: [Landing Stations](https://cablefyi.com/landing-stations/) · [Guides](https://cablefyi.com/guides/)

### Cable Operators and Owners

Submarine cable ownership has shifted from telecom consortia to hyperscale cloud providers. Google, Meta, Microsoft, and Amazon now own or co-own major cable systems, investing billions to control their network paths and reduce latency for cloud services.

| Owner Type | Examples | Strategy |
|-----------|---------|----------|
| Hyperscalers | Google, Meta, Microsoft, Amazon | Private capacity, low-latency cloud |
| Carrier-neutral | SubCom, NEC, Alcatel (builders) | Build and maintain cables |
| Telecom consortia | Traditional multi-carrier ownership | Shared capacity, legacy model |
| Regional operators | Telxius, Aqua Comms | Specific corridor focus |

```python
from cablefyi.api import CableFYI

with CableFYI() as api:
    # List cable operators/owners
    operators = api.list_operators()
    for op in operators[:5]:
        print(f"{op['name']}: {op.get('cable_count', 0)} cables")
```

Learn more: [Cable Operators](https://cablefyi.com/operators/) · [Glossary](https://cablefyi.com/glossary/)

### Fiber Optic Technology

Modern submarine cables use optical fiber to transmit data as pulses of light. Key technologies include WDM (wavelength-division multiplexing) to carry multiple signals on different light wavelengths, EDFA (erbium-doped fiber amplifiers) to boost signals every 60-80 km, and coherent detection for high spectral efficiency.

| Technology | Function | Impact |
|-----------|---------|--------|
| WDM | Multiple wavelengths per fiber | Multiplied capacity |
| EDFA | Optical signal amplification | 60-80 km repeater spacing |
| Coherent detection | Phase + amplitude modulation | Higher bits/symbol |
| SDM (Space-division) | Multiple fiber cores | Next-gen capacity |

```python
from cablefyi.api import CableFYI

with CableFYI() as api:
    # Search for cables by technology or route
    results = api.search("pacific")
    for r in results:
        print(f"{r['name']}: {r.get('length_km', 'N/A')} km")
```

Learn more: [Cable Technology](https://cablefyi.com/guides/) · [API Documentation](https://cablefyi.com/developers/)

## Command-Line Interface

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

cablefyi cable marea                         # Cable system details
cablefyi search "atlantic"                   # Search cables
cablefyi country united-states               # Cables landing in US
cablefyi landing-stations united-kingdom     # UK landing stations
```

## MCP Server (Claude, Cursor, Windsurf)

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

```json
{
    "mcpServers": {
        "cablefyi": {
            "command": "uvx",
            "args": ["--from", "cablefyi[mcp]", "python", "-m", "cablefyi.mcp_server"]
        }
    }
}
```

## REST API Client

```python
from cablefyi.api import CableFYI

with CableFYI() as api:
    cable = api.get_cable("marea")                          # GET /api/v1/cables/marea/
    cables = api.list_cables(country="united-states")        # GET /api/v1/cables/?country=united-states
    stations = api.list_landing_stations(country="uk")       # GET /api/v1/landing-stations/?country=uk
    results = api.search("google")                          # GET /api/v1/search/?q=google
```

### Example

```bash
curl -s "https://cablefyi.com/api/v1/cables/marea/"
```

```json
{
    "slug": "marea",
    "name": "MAREA",
    "length_km": 6605,
    "rfs_year": 2018,
    "owners": ["Microsoft", "Meta", "Telxius"]
}
```

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

## API Reference

| Function | Description |
|----------|-------------|
| `api.get_cable(slug)` | Cable system details (length, capacity, owners) |
| `api.list_cables(country)` | List cables, optionally by country |
| `api.list_landing_stations(country)` | Landing stations by country |
| `api.get_landing_station(slug)` | Station details with connected cables |
| `api.list_operators()` | All cable operators/owners |
| `api.search(query)` | Search cables, stations, and operators |

## Learn More About Submarine Cables

- **Browse**: [Cable Directory](https://cablefyi.com/cables/) · [Landing Stations](https://cablefyi.com/landing-stations/) · [Operators](https://cablefyi.com/operators/)
- **Guides**: [Cable Guides](https://cablefyi.com/guides/) · [Glossary](https://cablefyi.com/glossary/)
- **API**: [REST API Docs](https://cablefyi.com/developers/) · [OpenAPI Spec](https://cablefyi.com/api/openapi.json)

## Also Available

| Platform | Install | Link |
|----------|---------|------|
| **npm** | `npm install cablefyi` | [npm](https://www.npmjs.com/package/cablefyi) |
| **MCP** | `uvx --from "cablefyi[mcp]" python -m cablefyi.mcp_server` | [Config](#mcp-server-claude-cursor-windsurf) |

## Network FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem — internet infrastructure, cables, domains, and protocols.

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| **cablefyi** | [PyPI](https://pypi.org/project/cablefyi/) | [npm](https://www.npmjs.com/package/cablefyi) | **Submarine cables, landing points, operators — [cablefyi.com](https://cablefyi.com/)** |
| tldfyi | [PyPI](https://pypi.org/project/tldfyi/) | [npm](https://www.npmjs.com/package/tldfyi) | TLD registry, domain extensions, WHOIS — [tldfyi.com](https://tldfyi.com/) |
| ipfyi | [PyPI](https://pypi.org/project/ipfyi/) | [npm](https://www.npmjs.com/package/ipfyi) | IP geolocation, ASN lookup, CIDR ranges — [ipfyi.com](https://ipfyi.com/) |
| protocolcodes | [PyPI](https://pypi.org/project/protocolcodes/) | [npm](https://www.npmjs.com/package/protocolcodes) | HTTP status codes, protocol references — [statuscodefyi.com](https://statuscodefyi.com/) |

## License

MIT
