Blue Ribbon Nearby

Blue Ribbon Nearby

What this skill does

유저가 알려준 현재 위치를 기준으로 블루리본 서베이 공식 zone 을 찾고, k-skill-proxy 를 경유해 근처 블루리본 맛집을 보여준다.

• 위치는 자동으로 추정하지 않는다.
• 반드시 먼저 현재 위치를 질문한다.
• 위치 문자열은 공식 zone 목록으로 매칭하고, 주변 JSON endpoint 로 좁혀서 찾는다.
• 좌표를 직접 받으면 더 정확한 nearby 검색을 할 수 있다.
• nearby 검색은 기본적으로 k-skill-proxy (/v1/blue-ribbon/nearby) 를 경유한다. 프록시에 BLUE_RIBBON_SESSION_ID 가 설정되어 있어야 한다.

When to use

• "근처 맛집 찾아줘"
• "여기 근처 블루리본 맛집 뭐 있어?"
• "광화문 근처 괜찮은 식당 추천해줘"
• "내 주변 블루리본 식당만 보여줘"

Routing rule

• 사용자가 맛집 / 근처 식당 / 근처 레스토랑 을 물으면 기본적으로 이 스킬부터 고려한다.
• 다만 사용자가 블루리본 외 다른 기준(예: 망고플레이트, 네이버 지도 리뷰, 특정 음식점 예약) 을 명시하면 그 표면을 우선한다.

Prerequisites

• 인터넷 연결
• node 18+
• 이 저장소의 blue-ribbon-nearby package 또는 동일 로직

Mandatory first question

위치 정보 없이 바로 검색하지 말고 반드시 먼저 물어본다.

• 권장 질문: 현재 위치를 알려주세요. 동네/역명/랜드마크/위도·경도 중 편한 형식으로 보내주시면 근처 블루리본 맛집을 찾아볼게요.
• 위치가 애매하면: 가까운 역명이나 동 이름으로 한 번만 더 알려주세요.
• 좌표를 받으면 그대로 nearby 검색에 사용한다.

Accepted location inputs

• 동네/상권: 성수동, 광화문, 판교
• 역명/랜드마크: 강남역, 서울역, 코엑스
• 위도/경도: 37.573713, 126.978338

랜드마크는 내부 alias 로 가장 가까운 공식 Blue Ribbon zone 이름에 매칭한다. 예: 코엑스 → 삼성동/대치동

Official Blue Ribbon surfaces

• zone catalog: https://www.bluer.co.kr/search/zone
• nearby search JSON: https://www.bluer.co.kr/restaurants/map
• search page: https://www.bluer.co.kr/search

핵심 nearby 파라미터:

• zone1
• zone2
• zone2Lat
• zone2Lng
• isAround=true
• ribbon=true
• ribbonType=RIBBON_THREE,RIBBON_TWO,RIBBON_ONE
• distance=500|1000|2000|5000

좌표 직접 검색 시에는 latitude1, latitude2, longitude1, longitude2 bounding box 를 사용한다.

Workflow

1. Ask the current location first

위치를 안 물은 상태에서 검색을 시작하지 않는다.

2. Resolve the location

• 동네/역명/랜드마크를 받으면 공식 https://www.bluer.co.kr/search/zone 목록과 먼저 매칭한다.
• 코엑스처럼 공식 zone 이름이 아닌 대표 랜드마크는 가장 가까운 공식 zone alias 로 먼저 확장한다.
• 위도/경도를 받으면 좌표 기반 nearby 검색으로 바로 들어간다.
• 가장 유력한 zone 후보가 여러 개면 2~3개만 보여주고 다시 확인받는다.

3. Query the nearby Blue Ribbon endpoint

기본적으로 k-skill-proxy 를 경유해 nearby 결과를 가져온다.

const { searchNearbyByLocationQuery } = require("blue-ribbon-nearby");

const result = await searchNearbyByLocationQuery("광화문", {
  distanceMeters: 1000,
  limit: 5
});

console.log(result.anchor);
console.log(result.items);

내부적으로는 zone 매칭 후 프록시의 /v1/blue-ribbon/nearby 에 좌표와 거리를 넘긴다. 프록시가 프리미엄 세션으로 Blue Ribbon upstream 을 호출한다.

직접 호출이 필요하면 useDirectApi: true 옵션을 쓸 수 있지만, 프리미엄 세션 없이는 premium_required 에러가 난다.

4. Respond with a short restaurant summary

보통 3~5개만 짧게 정리한다.

• 식당명
• 리본 개수
• 대표 음식 카테고리
• 주소
• 거리

Done when

• 유저의 현재 위치를 먼저 확인했다.
• 공식 Blue Ribbon nearby 결과를 최소 1개 이상 찾았거나, 프록시 미설정 등의 이유로 결과를 가져올 수 없다는 이유와 다음 질문을 제시했다.
• 결과를 거리순으로 짧게 정리했다.

브라우저 fallback (봇 차단 우회)

bluer.co.kr이 자동화 접근을 차단(403)할 경우, rebrowser-playwright가 설치되어 있으면 실제 Chrome 브라우저를 통해 자동으로 fallback한다.

조건

• rebrowser-playwright가 설치되어 있어야 한다: npm install rebrowser-playwright
• Google Chrome이 시스템에 설치되어 있어야 한다
• headed 모드로 동작한다 (디스플레이 환경 필요)

동작 방식

1. 기존 fetch 요청이 403을 반환하면 자동으로 브라우저 fallback 활성화 2. stealth 패치 적용 (webdriver 제거, plugins/languages 스푸핑 등) 3. 실제 Chrome으로 zone 카탈로그 또는 nearby API를 호출 4. 결과를 기존 파이프라인에 그대로 전달

별도 설정 없이 rebrowser-playwright만 설치하면 자동으로 작동한다. 설치되어 있지 않으면 기존처럼 403 에러를 그대로 던진다.

Failure modes

• 위치 문자열이 공식 zone 과 잘 매칭되지 않을 수 있다.
• 같은 키워드가 여러 상권에 걸치면 추가 확인이 필요하다.
• Blue Ribbon 사이트가 구조/파라미터를 바꾸면 zone 파싱 또는 nearby endpoint 가 깨질 수 있다.
• 프록시의 BLUE_RIBBON_SESSION_ID 가 만료(30일)되면 갱신이 필요하다.
• 브라우저 fallback은 headed 모드 전용이므로 서버(CI) 환경에서는 동작하지 않는다.

Notes

• 이 스킬은 조회형 스킬이다.
• 유저 위치는 자동 추적하지 않고, 대화 중 받은 값만 사용한다.
• 맛집 문의는 기본적으로 이 스킬을 먼저 쓰되, 블루리본 외 다른 기준이 명시되면 그 기준을 우선한다.

근처 블루리본 맛집 가이드

이 기능으로 할 수 있는 일

• 유저가 알려준 현재 위치를 공식 Blue Ribbon zone 으로 매칭
• 공식 Blue Ribbon zone 목록으로 동네/역명 매칭
• k-skill-proxy 경유 nearby 블루리본 맛집 검색
• 거리순 상위 결과 정리

[!NOTE]

Blue Ribbon의 /restaurants/map 은 프리미엄 전용입니다. 이 기능은 k-skill-proxy 에 설정된 프리미엄 세션(BLUE_RIBBON_SESSION_ID)을 경유해 nearby 검색을 수행합니다.

먼저 필요한 것

• 인터넷 연결
• node 18+
• blue-ribbon-nearby package 또는 이 저장소 전체 설치

가장 먼저 할 일

이 기능은 반드시 현재 위치를 먼저 물어본 뒤 실행합니다.

권장 질문 예시:

현재 위치를 알려주세요. 동네/역명/랜드마크/위도·경도 중 편한 형식으로 보내주시면 근처 블루리본 맛집을 찾아볼게요.

입력값

• 동네/상권: 광화문, 성수동, 판교
• 역명/랜드마크: 강남역, 서울역, 코엑스
• 좌표: 37.573713, 126.978338

랜드마크는 내부 alias 로 가장 가까운 공식 Blue Ribbon zone 이름에 매칭합니다. 예: 코엑스 → 삼성동/대치동

맛집 문의는 기본적으로 blue-ribbon-nearby 스킬부터 검토합니다.

공식 Blue Ribbon 표면

• 지역/상권 목록: https://www.bluer.co.kr/search/zone
• 주변 맛집 JSON: https://www.bluer.co.kr/restaurants/map
• 검색 페이지: https://www.bluer.co.kr/search

주변 검색의 핵심 파라미터:

• zone1
• zone2
• zone2Lat
• zone2Lng
• isAround=true
• ribbon=true
• ribbonType=RIBBON_THREE,RIBBON_TWO,RIBBON_ONE
• distance=500|1000|2000|5000

좌표만 있을 때는 latitude1, latitude2, longitude1, longitude2 bounding box 로 nearby 범위를 만든다.

기본 흐름

1. 유저에게 반드시 현재 위치를 묻습니다. 2. 동네/역명/랜드마크를 받으면 공식 search/zone 목록에서 가장 가까운 zone 후보를 찾습니다.

• 공식 zone 이름이 아닌 대표 랜드마크는 먼저 nearest zone alias 로 확장합니다. 예: 코엑스 → 삼성동/대치동

3. 좌표를 받으면 nearby bounding box 를 계산합니다. 4. k-skill-proxy 의 /v1/blue-ribbon/nearby 에 좌표와 거리를 넘겨 nearby 검색을 수행합니다. 프록시가 프리미엄 세션으로 /restaurants/map 을 호출합니다. 5. 거리순 상위 결과를 3~5개 정리합니다.

Node.js 예시

const { searchNearbyByLocationQuery } = require("blue-ribbon-nearby");

async function main() {
  const result = await searchNearbyByLocationQuery("광화문", {
    distanceMeters: 1000,
    limit: 5
  });

  console.log(result.anchor);
  console.log(result.items);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

기본적으로 k-skill-proxy 를 경유합니다. 직접 호출이 필요하면 useDirectApi: true 옵션을 사용하세요 (프리미엄 세션 없이는 premium_required 에러).

Live smoke 예시

아래 값은 2026-03-27 에 광화문, distanceMeters=1000, limit=5 로 실제 호출해 확인한 결과 일부입니다.

{
  "anchor": {
    "zone1": "서울 강북",
    "zone2": "광화문/종로2가"
  },
  "items": [
    {
      "name": "미치루스시",
      "ribbonType": "RIBBON_ONE",
      "ribbonCount": 1,
      "distanceMeters": 61
    },
    {
      "name": "한성옥",
      "ribbonType": "RIBBON_ONE",
      "ribbonCount": 1,
      "distanceMeters": 170
    },
    {
      "name": "청진옥",
      "ribbonType": "RIBBON_TWO",
      "ribbonCount": 2,
      "distanceMeters": 242
    }
  ]
}

운영 팁

• 위치 문자열이 애매하면 동네보다 가까운 역명 또는 위도/경도 를 한 번 더 받는 편이 정확합니다.
• zone 후보가 여러 개면 바로 검색하지 말고 2~3개만 다시 확인합니다.
• 결과를 길게 나열하기보다 거리순 상위 3~5개만 먼저 보여주는 편이 좋습니다.

주의할 점

• Blue Ribbon /restaurants/map 은 프리미엄 전용입니다. k-skill-proxy 에 BLUE_RIBBON_SESSION_ID 가 설정되어 있어야 합니다 (30일마다 갱신).
• 검색 페이지의 zone 목록이 바뀌면 매칭 결과도 바뀔 수 있습니다.
• 좌표 없이 너무 넓은 지역명만 받으면 상권 후보가 많아질 수 있습니다.