Eats Radar

3. Verify environment

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 (동주소):

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:

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

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:

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

node scripts/find-restaurants.mjs --env-file /path/to/env --address "서울특별시 양천구 목동" --category all

Specific cuisine

"역삼동 근처 일식 맛집" (Japanese restaurants near Yeoksam-dong) → category jpn:

node scripts/find-restaurants.mjs --env-file /path/to/env --address "서울특별시 강남구 역삼동" --category jpn

Theme query

"염창역 근처 요즘 뜨는 맛집" (trending restaurants near Yeomchang station) → theme hot-rate:

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:

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.