ncloud-maps

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