Ncloud Maps

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

Security Scan

The code and SKILL.md clearly require Naver Cloud API credentials and call Naver Maps endpoints, but the package/registry metadata does not declare the required environment variables or primary credential — an inconsistency you should resolve before installing.

Purpose & Capability

The skill's name/description (Naver Cloud Maps routing) matches the included source code and behavior: it calls Naver Maps Directions5/15 endpoints and returns distance/duration/cost estimates. However, the registry metadata claims no required env vars or primary credential while the SKILL.md and code clearly expect NCLOUD_API_KEY_ID and NCLOUD_API_KEY. That metadata omission is an inconsistency (likely an authoring error) but the capabilities themselves align with the stated purpose.

Instruction Scope

SKILL.md and the scripts are narrowly scoped to routing: validate coordinates, call Naver Maps Directions endpoints, and return route summaries. The runtime instructions ask the user to set NCLOUD API keys and run npm install / the CLI; there are no instructions to read unrelated system files, other credentials, or to post data to unexpected endpoints. All network calls in code target Naver's map gateway (maps.apigw.ntruss.com).

Install Mechanism

This is effectively an instruction-and-code package with no special install spec in the registry. The code uses standard npm dependencies (axios) listed in package-lock.json; there are no download-from-arbitrary-URLs or extract steps. Asking users to run npm install and run the included CLI is normal for a JS/TS skill.

Credentials

The SKILL.md and all CLI code expect two environment variables (NCLOUD_API_KEY_ID and NCLOUD_API_KEY) for authentication. Yet the registry metadata lists no required env vars and no primary credential. Requesting those two Naver Cloud keys is proportionate for this functionality, but the registry omission is misleading and increases risk if users install without realizing they must supply secrets. No other unrelated credentials are requested.

Persistence & Privilege

The skill does not request always:true and is user-invocable only; it does not attempt to modify other skills or system-wide agent settings. Autonomous invocation is allowed (platform default) but is not combined with other concerning privileges here.

What to consider before installing

This skill's code and docs require NCLOUD_API_KEY_ID and NCLOUD_API_KEY (Naver Cloud API credentials) and will call Naver's Maps API endpoints — that is expected for a Naver Maps routing skill. The problem is the registry metadata did not declare those required environment variables or a primary credential, which is an authoring inconsistency you should resolve before installing. Before you proceed: (1) Confirm you are comfortable providing Naver Cloud API keys and that you will store them securely (do not commit them to git). (2) Ask the publisher/registry to update the metadata to list NCLOUD_API_KEY_ID / NCLOUD_API_KEY as required credentials. (3) Review package.json and package-lock.json (already present) and run npm audit / use non-production credentials to test. (4) Verify network egress policy allows calls to https://maps.apigw.ntruss.com and that no other unknown endpoints are contacted. If the maintainer cannot explain the metadata omission, treat the package as untrusted until that is fixed.

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)

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.

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.