ncloud-maps

Original source / Raw SKILL.md

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

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

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

```bash
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:**

```bash
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:**

```bash
# 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:**

```bash
# 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:

```bash
# 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)

```bash
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:

```bash
# 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)

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

Multiple waypoints:
```bash
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)

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

### Vehicle and fuel settings

```bash
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

```json
{
  "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](references/api-spec.md) for detailed API specifications.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/api-spec.md

```markdown
# Naver Cloud Maps API Specification

Complete reference for Ncloud Maps APIs.

## Directions15 API

## API Endpoint

```
GET https://maps.apigw.ntruss.com/map-direction-15/v1/driving
```

## Request Headers

| Field | Required | Description |
|-------|----------|-------------|
| `x-ncp-apigw-api-key-id` | Yes | API Key ID (Client ID) |
| `x-ncp-apigw-api-key` | Yes | API Key Secret (Client Secret) |

## Query Parameters

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `start` | String | Start point (longitude,latitude) |
| `goal` | String | Destination (longitude,latitude); supports multiple destinations separated by `:` |
| | | Example: `goal=123.45,34.56:124.56,35.67` |

### Optional Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `waypoints` | String | Waypoints (longitude,latitude) separated by `\|`; max 5 | - |
| | | Example: `waypoints=127.1,37.1:127.2,37.2\|128.1,38.1` | - |
| `option` | String | Route option; multiple allowed via `:` | `traoptimal` |
| | | `trafast`: Fast route | |
| | | `tracomfort`: Comfort route | |
| | | `traoptimal`: Optimal route | |
| | | `traavoidtoll`: Toll-free priority | |
| | | `traavoidcaronly`: Avoid car-only roads | |
| `cartype` | Integer | Vehicle type (1-6) | `1` |
| | | 1: Small sedan, 2: Medium, 3: Large, 4: 3-axle cargo, 5: 4+ axle, 6: Compact | |
| `fueltype` | String | Fuel type | `gasoline` |
| | | `gasoline`, `highgradegasoline`, `diesel`, `lpg` | |
| `mileage` | Double | Fuel efficiency (km/L) | `14` |
| `lang` | String | Response language | `ko` |
| | | `ko`: Korean, `en`: English, `ja`: Japanese, `zh`: Simplified Chinese | |

## Response Format

### Success Response

```json
{
  "code": 0,
  "message": "ok",
  "currentDateTime": "2026-02-21T13:30:00",
  "route": {
    "traoptimal": [
      {
        "summary": {
          "start": {
            "location": [127.1058342, 37.359708]
          },
          "goal": {
            "location": [129.075986, 35.179470],
            "dir": 0
          },
          "distance": 298700,
          "duration": 8500000,
          "departureTime": "2026-02-21T13:30:00",
          "tollFare": 23000,
          "taxiFare": 45000,
          "fuelPrice": 3500,
          "bbox": [[127.1, 35.1], [129.1, 37.4]]
        },
        "path": [[127.1058342, 37.359708], [127.1057, 37.3596], ...],
        "section": [...],
        "guide": [...]
      }
    ]
  }
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `code` | Integer | Response code (0 = success) |
| `message` | String | Response message |
| `currentDateTime` | String | Query timestamp (ISO format) |
| `route.{option}` | Array | Route array by requested option |

### Route Summary

| Field | Type | Description |
|-------|------|-------------|
| `start.location` | Array | [longitude, latitude] |
| `goal.location` | Array | [longitude, latitude] |
| `goal.dir` | Integer | Direction (0: ahead, 1: left, 2: right) |
| `distance` | Integer | Total distance (meters) |
| `duration` | Integer | Total duration (milliseconds) |
| `departureTime` | String | Departure time (ISO format) |
| `tollFare` | Integer | Toll fee (KRW) |
| `taxiFare` | Integer | Estimated taxi fare (KRW) |
| `fuelPrice` | Integer | Estimated fuel cost (KRW) |
| `bbox` | Array | Bounding box [[left_bottom], [right_top]] |

### Path

Array of coordinate arrays `[longitude, latitude]` representing the route geometry.

### Section

Major road segments with detailed info:

| Field | Type | Description |
|-------|------|-------------|
| `pointIndex` | Integer | Index in path array |
| `pointCount` | Integer | Number of points in segment |
| `distance` | Integer | Segment distance (meters) |
| `name` | String | Road name |
| `congestion` | Integer | Congestion level (0-3) |
| `speed` | Integer | Average speed (km/h) |

**Congestion levels:**
- 0: No data
- 1: Smooth (normal speed)
- 2: Slow
- 3: Congested

### Guide

Turn-by-turn navigation instructions:

| Field | Type | Description |
|-------|------|-------------|
| `pointIndex` | Integer | Index in path array |
| `type` | Integer | Turn type (see table below) |
| `instructions` | String | Navigation text |
| `distance` | Integer | Distance to next instruction (meters) |
| `duration` | Integer | Duration to next instruction (milliseconds) |

**Turn types:**
- 1: Straight
- 2: Left turn
- 3: Right turn
- 4: Left direction
- 5: Right direction
- 6: U-turn
- 8: Unprotected left turn
- 11-16: Diagonal directions (8/9/11 o'clock, 1/3/4 o'clock)
- 21-23: Roundabout instructions

## Error Responses

| HTTP Status | Code | Message | Meaning |
|-------------|------|---------|---------|
| 400 | 100 | Bad Request Exception | Invalid request syntax |
| 401 | 200 | Authentication Failed | Invalid credentials |
| 401 | 210 | Permission Denied | No API access |
| 404 | 300 | Not Found Exception | Server error |
| 413 | 430 | Request Entity Too Large | Request > 10 MB |
| 429 | 400 | Quota Exceeded | Rate limit hit |
| 429 | 410 | Throttle Limited | Too many rapid requests |
| 429 | 420 | Rate Limited | Too many requests in time window |
| 503 | 500 | Endpoint Error | Server error |
| 504 | 510 | Endpoint Timeout | Timeout |
| 500 | 900 | Unexpected Error | Unknown error |

## Coordinate Format

Use WGS84 (EPSG:4326) coordinates:
- Longitude: -180 to 180 (east-west)
- Latitude: -90 to 90 (north-south)

South Korea examples:
- Seoul: 127.1, 37.5
- Busan: 129.1, 35.1
- Daegu: 128.6, 35.9

## Notes

- Real-time traffic data is included in route calculations
- Identical requests may return different routes due to traffic changes
- Response times typically 1-3 seconds
- Supports both JSON requests and query parameters
- All distances in meters, durations in milliseconds
- All prices in Korean Won (KRW)

```

### scripts/index.ts

```typescript
#!/usr/bin/env node

/**
 * Ncloud Maps Directions15 + Directions5 CLI
 * 
 * 환경변수:
 *   NCLOUD_API_KEY_ID: 네이버클라우드 API Key ID
 *   NCLOUD_API_KEY: 네이버클라우드 API Key
 * 
 * 사용 예:
 *   npx ts-node scripts/index.ts --start "127.0683,37.4979" --goal "126.9034,37.5087"
 *   npx ts-node scripts/index.ts --start "127.0683,37.4979" --goal "126.9034,37.5087" --waypoints "127.0100,37.5000"
 */

import { getDirections } from "../lib/directions";
import { getDirections5 } from "../lib/directions5";
import { getSmartDirections } from "../lib/smartDirections";
import type { DirectionsParams } from "../lib/directions";
import type { Directions5Params } from "../lib/directions5";
import type { SmartDirectionsParams } from "../lib/smartDirections";

async function main() {
  // 환경변수에서 인증 정보 읽기
  const apiKeyId = process.env.NCLOUD_API_KEY_ID;
  const apiKey = process.env.NCLOUD_API_KEY;

  if (!apiKeyId || !apiKey) {
    console.error(
      "❌ 에러: NCLOUD_API_KEY_ID와 NCLOUD_API_KEY 환경변수가 필요합니다.\n"
    );
    process.exit(1);
  }

  // 커맨드라인 argument 파싱
  const args = process.argv.slice(2);
  const params: Partial<DirectionsParams & Directions5Params & SmartDirectionsParams & { api: string }> = {
    apiKeyId,
    apiKey,
    api: "smart", // 기본값: 경유지 개수에 따라 자동 선택
  };

  for (let i = 0; i < args.length; i += 2) {
    const key = args[i].replace(/^--/, "");
    const value = args[i + 1];

    if (key === "start") params.start = value;
    else if (key === "goal") params.goal = value;
    else if (key === "waypoints") params.waypoints = value;
    else if (key === "option") params.option = value;
    else if (key === "cartype") params.cartype = parseInt(value);
    else if (key === "fueltype") params.fueltype = value;
    else if (key === "mileage") params.mileage = parseFloat(value);
    else if (key === "lang") params.lang = value;
    else if (key === "api") params.api = value.toLowerCase();
  }

  // 필수 파라미터 검증
  if (!params.start || !params.goal) {
    console.error(
      "❌ 에러: --start와 --goal 파라미터가 필요합니다.\n\n" +
        "사용 방법: index.ts --start <경도,위도> --goal <경도,위도> [옵션]\n\n" +
        "API 선택:\n" +
        "  --api smart         (기본값, 경유지 5개 미만: Directions5 / 5개 이상: Directions15)\n" +
        "  --api directions15  (항상 Directions15, 최대 15개 경유지)\n" +
        "  --api directions5   (항상 Directions5, 최대 5개 경유지)\n\n" +
        "예시:\n" +
        "  # Smart (기본값, 경유지 개수에 따라 자동 선택):\n" +
        "  npx ts-node scripts/index.ts --start '127.0683,37.4979' --goal '126.9034,37.5087'\n" +
        "  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'\n\n" +
        "  # 명시적으로 Directions5 사용:\n" +
        "  npx ts-node scripts/index.ts --start '127.0683,37.4979' --goal '126.9034,37.5087' --api directions5\n\n" +
        "  # 명시적으로 Directions15 사용:\n" +
        "  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'\n\n" +
        "  # 경로 옵션:\n" +
        "  npx ts-node scripts/index.ts --start '127.0683,37.4979' --goal '126.9034,37.5087' --option 'traavoidtoll'"
    );
    process.exit(1);
  }

  try {
    let result;

    if (params.api === "directions5") {
      result = await getDirections5(params as Directions5Params);
    } else if (params.api === "directions15") {
      result = await getDirections(params as DirectionsParams);
    } else {
      // 기본값: Smart Directions (경유지 개수에 따라 자동 선택)
      result = await getSmartDirections(params as SmartDirectionsParams);
    }

    if (!result.success) {
      console.error(`\n❌ 실패: ${result.error}`);
      process.exit(1);
    }

    // JSON 형식으로 출력
    console.log(JSON.stringify(result, null, 2));
  } catch (error) {
    console.error(`❌ 예상치 못한 에러: ${error}`);
    process.exit(1);
  }
}

main();

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Ncloud Maps

🗺️ **Naver Cloud Maps API integration for OpenClaw** - Calculate driving routes with real-time traffic data.

[![npm version](https://img.shields.io/npm/v/ncloud-maps-skill.svg)](https://www.npmjs.com/package/ncloud-maps-skill)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

✨ **Smart Routing** - Intelligent API selection
- **Directions5** (0-4 waypoints) - Lightweight, optimized
- **Directions15** (5+ waypoints) - Full-featured, up to 15 stops
- **Automatic selection** - No configuration needed; choose based on waypoint count
- **Manual override** - Force specific API with `--api` flag if needed

🛣️ **Directions APIs** - Calculate optimal driving routes
- Distance (meters)
- Duration (milliseconds)
- Toll fare (KRW)
- Taxi fare estimate (KRW)
- Fuel cost estimate (KRW)
- Real-time traffic info

🔄 **Waypoints Support** - Multi-stop routing
- Directions5: Up to 5 intermediate stops (auto-selected)
- Directions15: Up to 15 intermediate stops (auto-selected)
- Coordinates only (longitude,latitude format)

⚙️ **Route Options**
- `trafast` - Fastest route
- `tracomfort` - Most comfortable
- `traoptimal` - Default (best balance)
- `traavoidtoll` - Toll-free route
- `traavoidcaronly` - Avoid car-only roads

🚗 **Vehicle Settings**
- 6 vehicle types (sedan, van, truck, etc.)
- Fuel types (gasoline, diesel, LPG)
- Custom mileage

## Quick Start

### Installation (OpenClaw)

```bash
# Via ClawHub
clawhub install ncloud-maps

# Or locally
npm install ncloud-maps-skill
```

### Authentication

Get API credentials from [Naver Cloud Console](https://console.ncloud.com):

1. Create/register an Application
2. Enable "Maps Directions15"
3. Copy `Client ID` and `Client Secret`

Set environment variables:

```bash
export NCLOUD_API_KEY_ID="your-client-id"
export NCLOUD_API_KEY="your-client-secret"
```

Or create `.env`:
```
NCLOUD_API_KEY_ID=your-client-id
NCLOUD_API_KEY=your-client-secret
```

### Basic Usage

**Smart Routing (Default)**

Provide coordinates in `longitude,latitude` format:

```bash
# 0-4 waypoints → Automatically uses Directions5 (lighter, faster)
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 → Automatically uses Directions15 (supports up to 15 stops)
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"
```

The skill automatically selects the optimal API. No `--api` flag needed.

**Force Specific API (Optional)**

```bash
# 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"
```

**Other Queries**

```bash
# Query by coordinates (direct)
npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087"

# With route options
npx ts-node scripts/index.ts \
  --start "127.0683,37.4979" \
  --goal "126.9034,37.5087" \
  --option "traavoidtoll"
```

## Output Example

```json
{
  "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"
}
```

## API Parameters

### Required
- `--start` - Starting point (longitude,latitude format, e.g., 127.0683,37.4979)
- `--goal` - Destination (longitude,latitude format, e.g., 126.9034,37.5087)

### Optional
- `--waypoints` - Intermediate stops in longitude,latitude format, pipe-separated (max 15)
- `--option` - Route preference (trafast|tracomfort|traoptimal|traavoidtoll|traavoidcaronly)
- `--cartype` - Vehicle type (1-6)
- `--fueltype` - Fuel type (gasoline|diesel|lpg)
- `--mileage` - Vehicle mileage (km/L) for fuel cost calculation
- `--lang` - Response language (ko|en|ja|zh)

## Project Structure

```
ncloud-maps/
├── lib/
│   ├── directions.ts      # Directions15 API integration
│   ├── directions5.ts     # Directions5 API integration
│   └── smartDirections.ts # Intelligent routing (auto-select API based on waypoints)
├── scripts/
│   └── index.ts           # CLI entry point
├── references/
│   └── api-spec.md        # Full API documentation
├── SKILL.md               # OpenClaw skill description
├── package.json
├── tsconfig.json
└── .env                   # (local, not in git) API credentials
```

## API Endpoints

- **Directions5**: `https://maps.apigw.ntruss.com/map-direction/v1/driving` (max 5 waypoints)
- **Directions15**: `https://maps.apigw.ntruss.com/map-direction-15/v1/driving` (max 15 waypoints)

## Error Handling

Common errors and solutions:

| Error | Cause | Solution |
|-------|-------|----------|
| `좌표 형식 오류` | Invalid coordinate format | Use `longitude,latitude` format (e.g., 127.0683,37.4979) |
| `Authentication Failed` | Invalid API credentials | Verify NCLOUD_API_KEY_ID & NCLOUD_API_KEY |
| `Quota Exceeded` | Rate limit hit | Check Naver Cloud Console quota |
| `No routes found` | Invalid route | Verify start/goal are reachable by car |

## Development

### Install deps
```bash
npm install
```

### Run tests
```bash
npm test
```

### Build
```bash
npm run build
```

### Local development with .env
```bash
cat > .env << EOF
NCLOUD_API_KEY_ID=your-id
NCLOUD_API_KEY=your-key
EOF

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

## API Limits

| API | Waypoints | Auto-Selected When |
|-----|-----------|-------------------|
| **Directions5** | Max 5 | 0-4 waypoints (default, lighter) |
| **Directions15** | Max 15 | 5+ waypoints (auto-upgraded) |
| **Rate Limits** | Per your Naver Cloud plan | Both APIs |

## 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).

## Resources

- [Naver Cloud Console](https://console.ncloud.com)
- [Maps Directions API Docs](https://api.ncloud-docs.com/docs/ko/application-maps-directions)
- [OpenClaw Docs](https://docs.openclaw.ai)
- [ClawHub](https://clawhub.com)

## License

MIT - See [LICENSE](LICENSE) file

## Contributing

Pull requests welcome! Please follow existing code style.

## Changelog

### v1.0.8 (2026-02-25)
- **Add OpenClaw skill prompt** - Enable `/skill ncloud-maps` command integration
- Add prompt section to SKILL.md for proper skill recognition
- Document usage with coordinates and addresses

### v1.0.7 (2026-02-25)
- **Add CLI binary support** - Register ncloud-maps command globally
- Enable direct command: `ncloud-maps --start <lon,lat> --goal <lon,lat>`
- Include dist/ directory in npm package
- Update .gitignore to track compiled JavaScript

### v1.0.6 (2026-02-22)
- **Fix axios dependency issues** - Update to latest stable version
- Upgrade axios from 1.6.0 to 1.13.5
- Add @types/axios for TypeScript support
- Resolve runtime axios errors

### v1.0.5 (2026-02-22)
- **Support multiple geocoding skills** - More generic, flexible approach
- Add goplaces and naver-local-search examples
- Allow users to integrate any geocoding service that returns lon,lat
- Update documentation to be provider-agnostic

### v1.0.4 (2026-02-21)
- **Fix TypeScript build** - Add node types to tsconfig.json
- Resolve TS2580 "Cannot find name 'process'" error
- Resolve TS2584 "Cannot find name 'console'" error
- Build process now works correctly

### v1.0.3 (2026-02-21)
- **Add limitations documentation** - Clarify vehicle-only routes
- Document that skill only supports car routes
- Explicitly list unsupported features (public transit, walking, etc.)
- Prevent ambiguous or incorrect suggestions

### v1.0.2 (2026-02-21)
- **Remove all geocoding references** - Complete removal of Geocoding API
- Remove `lib/geocoding.ts` entirely
- Update all code and documentation to coordinates-only API
- Remove geocoding from keywords and package description
- Smart Directions Routing continues to work automatically

### v1.0.1 (2026-02-21)
- **Smart Directions Routing**: Automatically select between Directions5 and Directions15 based on waypoint count
  - 0-4 waypoints: Uses Directions5 (lightweight, optimized)
  - 5+ waypoints: Uses Directions15 (supports up to 15 stops)
- Add `lib/directions5.ts` for Directions5 API support
- Add `lib/smartDirections.ts` for intelligent routing logic
- Update CLI to use smart routing by default
- Update documentation with smart routing examples
- Maintain backward compatibility with explicit `--api` flag

### v1.0.0 (2026-02-21)
- Initial release
- Directions15 API integration
- Waypoints support
- Route options
- Vehicle & fuel settings

```

### _meta.json

```json
{
  "owner": "beomsu317",
  "slug": "ncloud-maps",
  "displayName": "Ncloud Maps",
  "latest": {
    "version": "1.0.8",
    "publishedAt": 1772015899547,
    "commit": "https://github.com/openclaw/skills/commit/d09c1ab8ecbf404cf080aa6ba0ff30230bb16f04"
  },
  "history": [
    {
      "version": "1.0.6",
      "publishedAt": 1771762017559,
      "commit": "https://github.com/openclaw/skills/commit/565750e8655b1aa1036bca04353347b4f2c61603"
    },
    {
      "version": "1.0.4",
      "publishedAt": 1771687651593,
      "commit": "https://github.com/openclaw/skills/commit/b0b5e9b31eb817742fe23ec6cc17f6b104c969f1"
    }
  ]
}

```