Prompt

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

Usage:

• - INLINECODE0
• 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)
• INLINECODE3 (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. 1. Get API credentials from Naver Cloud Console:

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

CODEBLOCK0

Or create a .env file:
CODEBLOCK1

1. 3. Install dependencies:

CODEBLOCK2

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

Example workflow with goplaces:

CODEBLOCK3

Example workflow with naver-local-search:

CODEBLOCK4

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:

CODEBLOCK5

Basic route query by coordinates (direct)

CODEBLOCK6

Force specific API (optional)

If you need to override the smart routing:

CODEBLOCK7

With waypoints (coordinates only)

CODEBLOCK8

Multiple waypoints:
CODEBLOCK9

Route options

Choose from: trafast (fast), tracomfort (comfort), traoptimal (default), traavoidtoll (toll-free), traavoidcaronly (avoid car-only roads)

CODEBLOCK10

Vehicle and fuel settings

CODEBLOCK11

Vehicle types:

• - 1 (default): Small sedan
• INLINECODE22: Medium van/cargo
• INLINECODE23: Large vehicle
• INLINECODE24: 3-axle cargo truck
• INLINECODE25: 4+ axle special cargo
• INLINECODE26: Compact car

Fuel types: gasoline (default), highgradegasoline, diesel, INLINECODE30

Output

CODEBLOCK12

Response Fields

• - success - Whether the query succeeded
• INLINECODE32 - Starting point coordinates
• INLINECODE33 - Destination coordinates
• INLINECODE34 - Total distance in meters
• INLINECODE35 - Total duration in milliseconds (÷1000 = seconds)
• INLINECODE36 - Toll/highway fare in KRW
• INLINECODE37 - Estimated taxi fare in KRW
• INLINECODE38 - Estimated fuel cost in KRW
• INLINECODE39 - Query timestamp
• INLINECODE40 - Error message (if success=false)

How It Works

1. 1. Address Resolution (Optional - any geocoding skill)

1. 2. Coordinate Validation

1. 3. Route Calculation (Directions15 or Directions5)

1. 4. Waypoints Support

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
• INLINECODE45 - 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)
• INLINECODE48 - Invalid API credentials
• INLINECODE49 - API rate limit hit
• INLINECODE50 - 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.