Sea Route Navigation

Sea route navigation: generate the shortest maritime route between two ports or coordinates, output navigation waypoints and an interactive HTML map. Use when the user mentions sea route, shipping route, maritime navigation, port-to-port distance, 海运航线, 航线规划, 海上路线, 港口距离, 船运路线.

Sea Route Navigation Skill

Generate the shortest sea route between two points on the globe. Returns navigation waypoints (coordinates) and an interactive HTML map visualization.

When to Use

• User asks for a sea/shipping/maritime route between two locations
• User wants port-to-port distance or travel time estimate
• User needs navigation waypoints for maritime routing
• User wants a visual map of a shipping lane

How It Works

This skill uses a Python script (scripts/sea_route.py) powered by the searoute library. It computes the shortest path over ocean, avoids land masses, and outputs:

1. Waypoint coordinates (longitude, latitude) printed to stdout as JSON
2. An interactive HTML map saved to a user-specified path (default: ./sea_route_map.html)

The script uses uv for dependency management — no manual pip install needed.

Usage

Step 1 — Resolve user input to coordinates

The user may provide:

• City / port names (e.g., "天津" and "大阪", "Rotterdam" and "Singapore")
• Coordinates directly (e.g., [117.75, 38.99])

If the user provides city or port names, you MUST convert them to [longitude, latitude] coordinates yourself before calling the script. Use well-known port coordinates:

Port	Longitude	Latitude
天津港 (Tianjin)	117.75	38.99
上海港 (Shanghai)	121.47	31.23
大阪港 (Osaka)	135.25	34.65
深圳港 (Shenzhen)	114.27	22.55
香港 (Hong Kong)	114.17	22.28
新加坡 (Singapore)	103.85	1.29
鹿特丹 (Rotterdam)	4.50	51.90
汉堡 (Hamburg)	9.97	53.53
洛杉矶 (Los Angeles)	-118.27	33.73
纽约 (New York)	-74.04	40.67
迪拜 (Dubai)	55.27	25.27
悉尼 (Sydney)	151.21	-33.87
釜山 (Busan)	129.04	35.10
东京 (Tokyo)	139.77	35.45
高雄 (Kaohsiung)	120.29	22.61

For ports not listed above, look up reasonable coordinates for the port area.

Step 2 — Run the script

Run with uv:

uv run --script /path/to/skills/sea-route/scripts/sea_route.py \
  --origin-lon <LON> --origin-lat <LAT> \
  --dest-lon <LON> --dest-lat <LAT> \
  --origin-name "Port A" --dest-name "Port B" \
  --output ./sea_route_map.html

Parameters:

Flag	Required	Description
--origin-lon	Yes	Origin longitude
--origin-lat	Yes	Origin latitude
--dest-lon	Yes	Destination longitude
--dest-lat	Yes	Destination latitude
--origin-name	No	Display name for origin (default: "Origin")
--dest-name	No	Display name for destination (default: "Destination")
--output	No	Output HTML file path (default: ./sea_route_map.html)

Step 3 — Present results to user

The script prints a JSON object to stdout with this structure:

{
  "origin": {"name": "Tianjin", "lon": 117.75, "lat": 38.99},
  "destination": {"name": "Osaka", "lon": 135.25, "lat": 34.65},
  "distance_km": 1891,
  "duration_hours": 42.5,
  "waypoints": [
    {"seq": 1, "lon": 118.1725, "lat": 38.7726},
    ...
  ],
  "html_map": "./sea_route_map.html"
}

Present to the user:

1. A summary: origin → destination, distance, estimated time
2. The waypoint coordinate table
3. Tell them the HTML map file path and offer to open it

Step 4 — Open the map (optional)

If the user wants to see the map:

open ./sea_route_map.html    # macOS
xdg-open ./sea_route_map.html  # Linux

Example Interaction

User: 帮我生成从天津到大阪的海运航线

Agent:

1. Resolve: 天津港 → [117.75, 38.99], 大阪港 → [135.25, 34.65]
2. Run:

uv run --script ~/.agents/skills/sea-route/scripts/sea_route.py \
  --origin-lon 117.75 --origin-lat 38.99 \
  --dest-lon 135.25 --dest-lat 34.65 \
  --origin-name "天津港" --dest-name "大阪港" \
  --output ./tianjin_osaka_route.html

3. Parse JSON output, present waypoints and summary
4. Open the HTML map

Notes

• The searoute library generates approximate maritime routes suitable for visualization and distance estimation. It is NOT intended for real navigation.
• Coordinates use [longitude, latitude] order (GeoJSON convention).
• The script requires uv to be installed. It uses inline script dependencies — no virtual environment setup needed.
• Estimated speed is ~25 knots (typical cargo vessel cruising speed).