연동하기

개발자 가이드

유미 데이터는 한 명의 큐레이터가 정리한 노트 같은 API야. 키 하나로 정제된 매장(원셋)에 닿아. 영업시간·메뉴·가격대·평점·활동 최신성·신뢰도는 물론, 주차(유형·요금·안내)·비건/채식 식단 인덱스·AI 한줄 요약까지 정리된 채로. 좌표가 없어도 "홍제동" 같은 동네 이름을 /regions로 코드·좌표로 풀어 주변 검색에 바로 쓸 수 있고(동명이동은 시도/시군구로 구분).

이 가이드는 API·MCP·CLI 세 가지 연결 방식을 한곳에서 다뤄. 연결하는 법은 방식마다 다르고, 그 아래 데이터·과금·점수·에러는 셋 다 공통이야.

API 키 받기 →API 레퍼런스 →체험존에서 바로 호출 →MCP 서버 →CLI →OpenAPI 스펙

① 연결: 세 가지, 각자 다르게

무엇을 만들든 아래 셋 중 하나로 유미에 닿아. 각 방식은 성격이 달라서 연결하는 법도 다르고. 자세한 화면은 각 카드의 링크로 이어져.

MCP운영 중

Claude·Cursor·ChatGPT 같은 에이전트에 연결. 구글 로그인 또는 API 키로 인증.

01MCP 서버 URL 추가
02구글 로그인(OAuth) 또는 Bearer 키
03에이전트에서 바로 질의

server url

https://mcp.heyyumi.ai

MCP 연결 보기 →

API운영 중

제품·백엔드에 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=버거킹"

API 연결 전체 보기 →

CLI준비중

Claude Code·Codex 같은 터미널 에이전트용. 설치 → 로그인 → MCP 자동 등록.

01npm i -g @heyyumi/cli
02heyyumi login
03heyyumi mcp install

terminal

npm i -g @heyyumi/cli
heyyumi login
heyyumi mcp install

CLI 연결 보기 →

② 공통: 세 방식 모두 같아

어떤 방식으로 연결하든 아래는 똑같이 적용돼. 유미가 어떤 데이터를 주는지, 필드에 따라 토큰이 어떻게 빠지는지, 점수를 어떻게 읽는지, 에러는 무슨 뜻인지.

필드 선택 · 차등과금

한 번에 모든 데이터를 주진 않아. fields 파라미터로 받을 필드를 골라. 등급명(core/contact_hours/quality/edge)·all·개별 필드명을 콤마로 넣으면 돼. 미지정 시 core.

core1 token기본 (식별·위치)
id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, lastSeenAt
contact_hours2 tokens연락처·영업시간
phone, homepage, bookingUrl, snsLinks, businessHours, is24h
quality2 tokens품질·가격
rating, reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, photoCount, nearestStation
edge4 tokens해자 (접근성·맥락)
accessHints, recommendedFor, atmosphere, cautions, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, reputation
media8 tokens사진 (리치데이터)
photos

과금은 요청당이야. 호출 단가 = 요청 필드 중 최고 등급(page_size는 단가에 영향 없음). 월 한도는 토큰 합으로 차감되고, 그 안에서는 원하는 만큼 자유롭게 쓰면 돼(일일 한도 없음). 남용 방지는 가격이 아니라 한도로 막아: 플랜별 분당 요청수(rpm) 제한(초과 시 429 + Retry-After), 검색 조건별 결과창(Starter 1,000 · Pro 5,000), 최근 30일 distinct 매장 캡(Starter 10,000곳 · Pro 40,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·Claude의 커스텀 커넥터처럼 구글 로그인(OAuth)으로 키 없이 연결해도 돼. URL의 ?api_key=는 로그에 남기 쉬워서 비추천·폐기 예정이야.

에러 코드

400잘못된 파라미터 / bulk_export_required. 결과창이 너무 큼.
401키 없음/무효. 헤더와 키를 확인해.
404해당 매장 없음.
429rate limit · 월 한도 초과. Retry-After 만큼 대기하거나 플랜 상향.
5xx서버 오류. 잠시 후 재시도.