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:

PortLongitudeLatitude天津港 (Tianjin)117.7538.99上海港 (Shanghai)121.4731.23大阪港 (Osaka)135.2534.65深圳港 (Shenzhen)114.2722.55香港 (Hong Kong)114.1722.28新加坡 (Singapore)103.851.29鹿特丹 (Rotterdam)4.5051.90汉堡 (Hamburg)9.9753.53洛杉矶 (Los Angeles)-118.2733.73纽约 (New York)-74.0440.67迪拜 (Dubai)55.2725.27悉尼 (Sydney)151.21-33.87釜山 (Busan)129.0435.10东京 (Tokyo)139.7735.45高雄 (Kaohsiung)120.2922.61

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

Step 2 — Run the script#

Run with uv:

bash

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:

FlagRequiredDescription--origin-lonYesOrigin longitude--origin-latYesOrigin latitude--dest-lonYesDestination longitude--dest-latYesDestination latitude--origin-nameNoDisplay name for origin (default: "Origin")--dest-nameNoDisplay name for destination (default: "Destination")--outputNoOutput 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:

json

{
  "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:

bash

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:

bash

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

1. Parse JSON output, present waypoints and summary
2. 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).