eats-radar

--- name: eats-radar description: >- Looks up top-ranked restaurants in a Korean district and enriches them with Naver Map / Kakao Map review data. Use this skill when the user asks for restaurant recommendations, local food rankings, or dining reviews for a specific area in South Korea. compatibility: Node.js 18+, Playwright Chromium, network access required. metadata: author: eats-radar version: "0.1.0" --- # eats-radar Retrieves top-ranked restaurants from the TMAP API for a given Korean district, then crawls Naver Map and Kakao Map for review data and returns the combined results. ## Prerequisites ### 1. Install dependencies ```bash bash scripts/setup.sh ``` ### 2. Configure API keys Create a `.env` file in the skill root directory: ``` TMAP_APP_KEY=<TMAP Open API app key> PUBLIC_DATA_SERVICE_KEY=<Korea Public Data Portal service key> ``` - **TMAP_APP_KEY**: Issued at [TMAP Open API](https://openapi.sk.com/) - **PUBLIC_DATA_SERVICE_KEY**: Issued at [Korea Public Data Portal](https://www.data.go.kr/) (법정동코드 API) ### 3. Verify environment ```bash bash scripts/check-env.sh ``` ## Usage Flow Follow these steps when a user asks for restaurant recommendations: ### Step 1: Convert location to dong-level address **`--address` must be a Korean legal-district address in the format "시/도 + 구/군 + 동".** Users express locations in many ways. The agent must convert these into a dong-level address (동주소): | User input | Converted address | How | |------------|-------------------|-----| | "염창역 근처 맛집" (near Yeomchang station) | `서울특별시 영등포구 염창동` | Station name → dong where the station is located | | "의왕시 바라산로" (Barasanro, Uiwang) | `경기도 의왕시 학의동` | Street name → dong the street belongs to | | "의왕시 학의동" (Hakui-dong, Uiwang) | `경기도 의왕시 학의동` | City + dong → prepend province | | "강남 맛집" (Gangnam restaurants) | `서울특별시 강남구 역삼동` | District only → infer a representative dong, or ask the user | | "목동 맛집 추천해줘" (recommend Mokdong restaurants) | `서울특별시 양천구 목동` | Dong only → prepend city and district | | "해운대 맛집" (Haeundae restaurants) | `부산광역시 해운대구 우동` | District only → infer a representative dong, or ask | **Conversion rules:** - If the dong name is clear, convert directly (e.g., "목동" → "서울특별시 양천구 목동"). - If only a district, station, or street name is given and the dong is ambiguous, either use a well-known representative dong or ask the user "Which dong (neighborhood) are you near?" - Final format: `"OO시(도) OO구(군) OO동"` — pass this string to `--address`. ### Step 2: Determine query mode Two query modes are available: | Mode | Description | Flag | When to use | |------|-------------|------|-------------| | **By category** | Rankings by cuisine type | `--category` | "Korean food", "Japanese restaurant", "any food" | | **By theme** | Special theme rankings | `--theme` | "trending spots", "high revisit rate", "local favorites" | **Agent decision guide:** - General requests like "recommend restaurants" or "what should I eat" → category mode with `--category all` - Specific cuisine mentioned ("한식", "중식", "일식", etc.) → matching category - Theme keywords ("핫플/trending", "재방문/revisit", "현지인/local", "여행자/traveler") → matching theme - When in doubt, ask the user ### Step 3: Collect options (if needed) **Category mode** — choose a category (see `references/PARAMETERS.md`): - Korean (kor), Chinese (chn), Japanese (jpn), Western (wes), Asian (asi), Other (etc), All (all) - Default to `all` if the user didn't specify a cuisine **Theme mode** — choose a theme (see `references/PARAMETERS.md`): - `seg-rate` (demographic) requires additional `--gender` and `--age-grp` flags - All other themes need no extra options ### Step 4: Run the script ```bash node scripts/find-restaurants.mjs --env-file <path-to-env> --address "<dong address>" [options] ``` - `--env-file`: Path to the `.env` file containing `TMAP_APP_KEY` and `PUBLIC_DATA_SERVICE_KEY`. Check `TOOLS.md` for available env file paths per user. > Execution takes approximately 30 seconds to 2 minutes (due to crawling). Let the user know it will take a moment before running. ### Step 5: Present results Format the JSON array into a readable table for the user: | Rank | Name | Category | Naver Reviews | Kakao Rating | Kakao Reviews | |------|------|----------|--------------|--------------|---------------| | 1 | OO식당 | Korean | 1,234 | 4.5 | 567 | - Include Naver/Kakao URLs so the user can check the pages directly. - Show "N/A" for items where crawling failed (null). See `references/OUTPUT-FORMAT.md` for the full JSON output schema. ## Script Examples ### General restaurant lookup "목동 맛집 추천해줘" (recommend Mokdong restaurants) → category all: ```bash node scripts/find-restaurants.mjs --env-file /path/to/env --address "서울특별시 양천구 목동" --category all ``` ### Specific cuisine "역삼동 근처 일식 맛집" (Japanese restaurants near Yeoksam-dong) → category jpn: ```bash node scripts/find-restaurants.mjs --env-file /path/to/env --address "서울특별시 강남구 역삼동" --category jpn ``` ### Theme query "염창역 근처 요즘 뜨는 맛집" (trending restaurants near Yeomchang station) → theme hot-rate: ```bash node scripts/find-restaurants.mjs --env-file /path/to/env --address "서울특별시 영등포구 염창동" --theme hot-rate ``` ### Demographic query "학의동 20대 여성 인기 맛집" (popular among women in their 20s, Hakui-dong) → theme seg-rate: ```bash node scripts/find-restaurants.mjs --env-file /path/to/env --address "경기도 의왕시 학의동" --theme seg-rate --gender female --age-grp 20 ``` ## Important Notes - **TMAP API monthly limit: 10 calls (free tier).** Inform the user of this limit and avoid unnecessary repeated calls. Basic plan allows 100 calls/month at ₩220/call. - **Execution time:** 30 seconds to 2 minutes due to Naver/Kakao crawling. Notify the user before running. - **Network required:** Playwright Chromium launches a real browser for crawling, so network access is essential. - **Result count:** Returns the full ranking list from TMAP (typically 10–20 restaurants), enriched with review data. - **Dong address required:** `--address` must include a dong-level legal district name. Passing a raw street name or station name will cause the district code lookup to fail.