Prompt

When a user requests a route calculation with addresses or coordinates, use this skill to calculate driving time, distance, and cost.

Usage:

• /skill ncloud-maps <start> <goal> [waypoints]

• Start and goal must be in

  longitude,latitude

  format OR addresses (convert using goplaces/naver-local-search first)
• Returns: distance, duration, toll fare, taxi fare, fuel cost

Examples:

• /skill ncloud-maps "126.9633,37.5524" "127.0165,37.4889"

  (coordinates)

• /skill ncloud-maps 아현역 서초역

  (addresses - requires geocoding skill first)

Ncloud Maps

Query Naver Cloud Maps APIs for intelligent routing (Directions5 + Directions15).

Key Feature: Smart Routing

v1.0.8+ — By default, the skill uses Directions5 for queries with fewer than 5 waypoints, and automatically switches to Directions15 when you have 5 or more waypoints. No manual selection needed.

Setup

1. Get API credentials from Naver Cloud Console:

   • Create/register an Application in Naver Cloud Console
   • Obtain

     Client ID

     (API Key ID) and

     Client Secret

     (API Key)
   • Enable "Maps Directions15" API

2. Set environment variables (or use .env file):

export NCLOUD_API_KEY_ID="your-api-key-id"
export NCLOUD_API_KEY="your-api-key-secret"

Or create a

.env

NCLOUD_API_KEY_ID=your-api-key-id
NCLOUD_API_KEY=your-api-key-secret

3. Install dependencies:

cd ~/.openclaw/workspace/skills/ncloud-maps
npm install

Usage

Using with Address-to-Coordinate Skills

ncloud-maps requires coordinates in

longitude,latitude

Available Options (choose based on your environment):

goplaces

GOOGLE_PLACES_API_KEY

naver-local-search

NAVER_CLIENT_ID

NAVER_CLIENT_SECRET

Example workflow with goplaces:

# Get coordinates from address
COORDS=$(goplaces resolve "강남역, 서울" --json | jq -r '.places[0] | "\(.location.longitude),\(.location.latitude)"')

# Use coordinates with ncloud-maps
npx ts-node scripts/index.ts --start "$COORDS" --goal "127.0049,37.4947"

Example workflow with naver-local-search:

# Get coordinates from address
COORDS=$(naver-local-search search "강남역" --format json | jq -r '.[0] | "\(.x),\(.y)"')

# Use coordinates with ncloud-maps
npx ts-node scripts/index.ts --start "$COORDS" --goal "127.0049,37.4947"

Or integrate any other geocoding service that returns

longitude,latitude

Smart Routing (Default Behavior)

By default, no

--api

• Uses Directions5 for 0–4 waypoints (faster)
• Switches to Directions15 for 5+ waypoints (necessary)

Provide coordinates in

longitude,latitude

# 0–4 waypoints → Directions5 (automatic)
npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087" \
  --waypoints "127.0100,37.5000|127.0200,37.5100"

# 5+ waypoints → Directions15 (automatic)
npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087" \
  --waypoints "127.0100,37.5000|127.0200,37.5100|127.0300,37.5200|127.0400,37.5300|127.0500,37.5400"

Basic route query by coordinates (direct)

npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087"

Force specific API (optional)

If you need to override the smart routing:

# Force Directions5 (max 5 waypoints)
npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087" \
  --api directions5 \
  --waypoints "127.0100,37.5000|127.0200,37.5100"

# Force Directions15 (max 15 waypoints)
npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087" \
  --api directions15 \
  --waypoints "127.0100,37.5000|127.0200,37.5100|127.0300,37.5200|127.0400,37.5300|127.0500,37.5400"

With waypoints (coordinates only)

npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087" \
  --waypoints "127.0100,37.5000"

Multiple waypoints:

npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087" \
  --waypoints "127.0100,37.5000|127.0200,37.5100"

Route options

Choose from:

trafast

tracomfort

traoptimal

traavoidtoll

traavoidcaronly

npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087" \
  --option "traavoidtoll"

Vehicle and fuel settings

npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087" \
  --cartype 2 \
  --fueltype "diesel" \
  --mileage 10.5

Vehicle types:

• 1

  (default): Small sedan

• 2

  : Medium van/cargo

• 3

  : Large vehicle

• 4

  : 3-axle cargo truck

• 5

  : 4+ axle special cargo

• 6

  : Compact car

Fuel types:

gasoline

highgradegasoline

diesel

lpg

Output

{
  "success": true,
  "start": "127.0683,37.4979",
  "goal": "126.9034,37.5087",
  "distance": 12850,
  "duration": 1145000,
  "toll_fare": 0,
  "taxi_fare": 18600,
  "fuel_price": 1550,
  "departure_time": "2026-02-21T14:10:00"
}

Response Fields

• success

  - Whether the query succeeded

• start

  - Starting point coordinates

• goal

  - Destination coordinates

• distance

  - Total distance in meters

• duration

  - Total duration in milliseconds (÷1000 = seconds)

• toll_fare

  - Toll/highway fare in KRW

• taxi_fare

  - Estimated taxi fare in KRW

• fuel_price

  - Estimated fuel cost in KRW

• departure_time

  - Query timestamp

• error

  - Error message (if success=false)

How It Works

1. Address Resolution (Optional - any geocoding skill)

   • Use any available skill that provides coordinates (goplaces, naver-local-search, etc.)
   • Extract

     longitude,latitude

     format from the result
   • Pass coordinates to ncloud-maps

2. Coordinate Validation

   • Input: Coordinates in

     longitude,latitude

     format (direct input or from geocoding skill)
   • Validates format and range
   • Returns error if format is invalid

3. Route Calculation (Directions15 or Directions5)

   • Coordinates sent to appropriate Directions API
   • Returns distance, duration, tolls, taxi fare, fuel cost
   • Only for vehicle (car) routes — not for pedestrian or public transit

4. Waypoints Support

   • Each waypoint must be in

     longitude,latitude

     format
   • All coordinates sent to Directions API

Limitations

⚠️ This skill only calculates vehicle (car) routes. It does not support:

• Public transportation (subway, bus, etc.)
• Walking routes
• Multi-modal journeys
• Transit-specific features (fare, stops, schedules)

For those use cases, use transit-specific APIs (e.g., Kakao Map, Naver Map Transit API).

Environment Variables

Required:

• NCLOUD_API_KEY_ID

  - Naver Cloud API Key ID

• NCLOUD_API_KEY

  - Naver Cloud API Key Secret

API Limits

Smart Routing:

• 0–4 waypoints: Directions5 API (max 5 waypoints)
• 5+ waypoints: Directions15 API (max 15 waypoints)

General:

• Real-time traffic information included
• Request rate limits apply per your Naver Cloud plan

Error Handling

Common errors:

• 좌표 형식 오류

  - Invalid coordinate format (use

  longitude,latitude

  )

• Authentication Failed

  - Invalid API credentials

• Quota Exceeded

  - API rate limit hit

• No routes found

  - No valid route between points

Check Naver Cloud Console for:

• API enablement for your application
• Quota/rate limit status
• Valid coordinates

References

See api-spec.md for detailed API specifications.