연동하기
개발자 가이드
API 키 하나로 정리된 매장 데이터를 받아요. 영업시간, 메뉴, 가격대, 리뷰 수, 최신성, 신뢰도에 주차, 비건·채식, 외국어 응대, AI 한 줄 요약까지 들어 있어요. 좌표가 없어도 "홍제동" 같은 동네 이름을 /regions로 좌표로 바꿔 주변 검색에 쓸 수 있어요. 같은 키로 예약 요청과 실시간 문의(재고, 웨이팅, 바로 앉을 수 있는지)도 보낼 수 있어요. 사장님에게 5분 안에 답해 달라는 알림이 가요.
이 가이드는 API·MCP·CLI 세 가지 연결 방식을 한곳에서 다뤄요. 연결하는 법은 방식마다 다르고, 그 아래 데이터·과금·점수·에러는 셋 다 공통이에요.
연결하는 세 가지 방법
무엇을 만들든 아래 셋 중 하나로 유미를 씁니다. 방법마다 연결 순서가 달라서, 자세한 안내는 각 카드의 링크에 있어요.
Claude·Cursor·ChatGPT·Perplexity 같은 에이전트에 연결. ChatGPT는 플러그인에서 검색·연결, 나머지는 서버 URL. 구글 로그인 또는 API 키로 인증.
- 01ChatGPT: 플러그인에서 HeyYumi 검색·연결
- 02Claude·Cursor·Perplexity: MCP 서버 URL 추가
- 03구글 로그인(OAuth) 또는 Bearer 키
server url
https://mcp.heyyumi.ai/mcp
제품·백엔드에 REST로 넣어요. 서버-투-서버.
- 01대시보드에서 키 발급
- 02헤더에 Authorization: Bearer <KEY>
- 03/api/v1/places 첫 호출
curl
curl -H "Authorization: Bearer hmp_xxx" \ "https://api.heyyumi.ai/api/v1/places?keyword=버거킹"
Claude Code·Codex·Gemini CLI 같은 터미널 에이전트용. 설치 없이 npx로 돌고, 구글 로그인 한 번이면 검색·예약 요청까지 돼요.
- 01npx -y heyyumi login
- 02npx -y heyyumi search
- 03npx -y heyyumi reserve
terminal
npx -y heyyumi login npx -y heyyumi search naengmyeon --region Euljiro
세 방법 모두 똑같은 것
어떤 방법으로 연결하든 인증, 필드별 토큰 차감, 점수 읽는 법, 에러 코드는 같아요.
필드 선택 · 차등과금
한 번에 모든 데이터를 주진 않아요. fields 파라미터로 받을 필드를 고르세요. 등급명(core/contact_hours/quality/edge/media)·all·개별 필드명을 콤마로 넣으면 돼요. 미지정 시 core.
core1 token기본 (식별·위치)id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt, placeUrl
contact_hours2 tokens연락처·영업시간phone, homepage, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h
quality2 tokens품질·가격reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation
edge4 tokens접근성·맥락accessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, ownerStory, influencerFeatures, culturalAssociations, legacy, reputation
media8 tokens사진photos
과금은 요청당이에요. 호출 단가 = 요청 필드 중 최고 등급(page_size는 단가에 영향 없음). 월 한도는 토큰 합으로 차감되고, 그 안에서는 원하는 만큼 자유롭게 쓰면 돼요(개발자 플랜은 하루 한도가 없어요. 개인용 무료·플러스는 하루 토큰 한도로 움직여요). 남용 방지는 가격이 아니라 한도로 막아요: 플랜별 분당 요청수(rpm) 제한(초과 시 429 + Retry-After), 검색 조건별 결과창(무료 100 · Starter 1,000 · Pro·Scale 5,000), 최근 30일 distinct 매장 캡(Starter 10,000곳 · Pro 40,000곳 · Scale 100,000곳; 무료 3,000곳). distinct 캡은 '서로 다른 매장 수'만 세니까 같은 매장을 여러 번 돌려줘도 1곳으로 카운트돼요(반복 서빙은 누적되지 않고, 데이터셋을 통째로 수집할 때만 걸려요). 전체·대량 데이터는 페이지네이션이 아니라 Bulk Export · 데이터 라이선스 대상이에요(약관의 허용 사용 정책 참고).
점수 읽는 법: 최신성·신뢰도
유미는 '추천해도 되는 곳'을 하나의 합산 점수로 못 박지 않아요. 대신 판단에 필요한 재료 점수를 투명하게 주고, 최종 추천 여부는 받는 쪽이 서비스 정책에 맞게 정하게 해요. 모든 점수는 높을수록 좋게 통일돼 있어요.
freshnessScore · 활동 최신성 (0~1, 높을수록 최근)매장의 최근 활동 신호가 얼마나 최신인지를 유미가 0~1로 산출한 값. 만점은 1.0.
0.8 – 1.0최근(약 4개월 내) 활동 신호가 뚜렷하고 활발.0.5 – 0.8약 4~9개월, 보통.0.2 – 0.5약 9~14개월. 직접 확인을 권장.0 – 0.2약 14~18개월 이상. 활동 신호가 약함.null(없음)최신성을 산출할 신호가 부족했다는 뜻일 뿐, 폐업 신호는 아니에요.
confidence · 데이터 신뢰도 (0.3~0.98, 높을수록 신뢰)여러 출처가 같은 매장으로 모이고 식별정보(전화·좌표·주소·이름)가 맞물릴수록 높아지는 교차검증 점수. 상한은 0.98.
0.9 – 0.98여러 출처가 교차 확인, 매우 높음.0.75 – 0.9교차 확인됨, 높음.0.6 – 0.75단일 출처거나 식별정보 일부, 보통. 한 출처에서만 확인되는 매장도 많아서, 단일 출처가 곧 저품질을 뜻하진 않아요.0.3 – 0.6식별정보가 적거나 출처 간 이름이 어긋나 사용 전 확인을 권장.
폐업이 확인된 매장은 추천 대상에서 빼는 걸 원칙으로 해요. 다만 최신성·신뢰도가 낮다고 해서 폐업으로 단정하진 마세요. 실제로 운영 중인 매장일 수 있어요. 두 점수는 '거르는 기준'이지 '폐업 판정'은 아니에요.
인증
키가 계정에 속해요. 키는 해시로만 저장되고 평문은 발급 시 1회만 노출돼요. REST는 Authorization: Bearer <KEY>(또는 X-API-Key)로 인증해요. MCP(mcp.heyyumi.ai · 전용 레포 map3-mcp)는 두 방식을 다 지원해요. Cursor처럼 같은 Bearer 키를 넣어도 되고, ChatGPT(플러그인 디렉터리에서 HeyYumi 검색·연결)·Claude·Perplexity(커스텀 커넥터에 서버 URL)처럼 구글 로그인(OAuth)으로 키 없이 연결해도 돼요. URL의 ?api_key=는 로그에 남기 쉬워서 비추천·폐기 예정이에요.
에러 코드
400잘못된 파라미터 / bulk_export_required. 결과창이 너무 큼.401키 없음/무효. 헤더와 키를 확인하세요.404해당 매장 없음.422예약·실시간 문의를 받을 수 없는 매장(reservation_not_available / live_status_not_available). 예약은 헤이유미로 아직 예약을 받지 않는 매장, 실시간 문의는 사장님 앱이 없는 매장이 여기에 해당 — 재시도하지 말고 안내하세요. 예약 요청 시간 밖이면 reservation_requests_closed(retryAfter에 다음 접수 시각), 그 시각에 매장이 영업하지 않으면 venue_closed_at_requested_time.429rate limit · 월 한도 초과. Retry-After 만큼 대기하거나 플랜 상향.5xx서버 오류. 잠시 후 재시도.