ncloud-maps

name	ncloud-maps
description	Query Naver Cloud Maps APIs for route navigation. Smart routing: Directions5 by default, auto-switches to Directions15 for 5+ waypoints.

Ncloud Maps

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

Key Feature: Smart Routing

v1.0.6+ — 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.

Waypoints	API Used	Max Waypoints
0–4	Directions5	5
5+	Directions15	15

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 file:

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 format. If you have address-based location data, use one of these compatible skills to convert addresses to coordinates:

Available Options (choose based on your environment):

Skill	Provider	Coordinates	Setup Required
goplaces	Google Places API	Yes (lon,lat)	GOOGLE_PLACES_API_KEY
naver-local-search	Naver Local Search	Yes (lon,lat)	NAVER_CLIENT_ID, NAVER_CLIENT_SECRET
Custom API	Your choice	Yes (lon,lat)	Your setup

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 coordinates.

Smart Routing (Default Behavior)

By default, no --api flag needed. The skill automatically:

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

Provide coordinates in longitude,latitude format:

# 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 (fast), tracomfort (comfort), traoptimal (default), traavoidtoll (toll-free), traavoidcaronly (avoid car-only roads)

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 (default), 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.