Connect
Developer guide
HeyYumi is an API that reads like one curator's notebook. A single key reaches the refined venues (the oneset) — hours, menu, price band, rating, activity freshness, confidence, plus parking (type/fee/note), a vegan/vegetarian dietary index, and an AI one-line summary, already tidied. No GPS? Resolve a neighborhood name like "홍제동" into codes & coordinates via /regions (same-name dongs disambiguated by sido/sigungu) and feed it straight into nearby search.
This guide covers all three ways to connect — API, MCP, and CLI — in one place. Connecting differs per method; the data, billing, scores, and errors below are shared by all three.
① Connect — three ways, each different
Whatever you're building, you reach Yumi one of three ways. Each has its own character, so connecting differs — follow each card's link for the full screen.
Connect agents like Claude, Cursor, ChatGPT. Sign in with Google or use an API key.
- 01Add the MCP server URL
- 02Google sign-in (OAuth) or Bearer key
- 03Query straight from the agent
server url
https://mcp.heyyumi.ai
REST into your product or backend. Server-to-server.
- 01Create a key in the dashboard
- 02Send Authorization: Bearer <KEY>
- 03First call to /api/v1/places
curl
curl -H "Authorization: Bearer hmp_xxx" \ "https://api.heyyumi.ai/api/v1/places?keyword=burger"
For terminal agents like Claude Code and Codex. Install → log in → auto-registers as MCP.
- 01npm i -g @heyyumi/cli
- 02heyyumi login
- 03heyyumi mcp install
terminal
npm i -g @heyyumi/cli heyyumi login heyyumi mcp install
② Shared — the same for all three
However you connect, the rest is identical: what data Yumi returns, how fields draw down tokens, how to read the scores, and what the errors mean.
Field mask & tiered billing
We don't hand back everything at once. Use the fields param to pick what you receive — tier names (core/contact_hours/quality/edge), 'all', or individual field names, comma-separated. Defaults to core.
core1 tokenCore (identity & location)id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, lastSeenAt
contact_hours2 tokensContact & hoursphone, homepage, bookingUrl, snsLinks, businessHours, is24h
quality2 tokensQuality & pricerating, reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, photoCount, nearestStation
edge4 tokensMoat (access & context)accessHints, recommendedFor, atmosphere, cautions, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, reputation
media8 tokensPhotos (rich media)photos
Billing is per request — a call costs the highest field tier you request (page_size does not affect tokens). Your monthly quota is drawn down by tokens, and you can spend it freely within the month (no daily cap). Abuse is controlled by limits, not price: per-plan rpm, per-query result windows (Starter 1,000 · Pro 5,000), and a 30-day distinct-venue cap (Starter 10,000 · Pro 40,000; Free 3,000). The distinct cap counts unique venues only — returning the same venue many times still counts as one (repeat serving never accumulates; only harvesting the dataset wholesale hits it). Full or bulk data is sold via Bulk Export / data licensing, not pagination (see Acceptable Use in the Terms).
Reading the scores — freshness & confidence
Yumi does not collapse "is this place worth recommending" into a single composite score. Instead we expose the ingredient signals transparently and let you decide based on your own policy. Every score is normalized so that higher is better.
freshnessScore — activity freshness (0–1, higher = more recent)Yumi's 0–1 estimate of how recent a place's latest activity signal is. Max is 1.0.
0.8 – 1.0Clear recent activity (within ~4 months) — active.0.5 – 0.8About 4–9 months — moderate.0.2 – 0.5About 9–14 months — verify directly.0 – 0.2About 14–18 months or more — weak activity signal.nullNot enough signal to compute freshness — this is not a closure signal.
confidence — data confidence (0.3–0.98, higher = more trusted)A cross-verification score that rises as more distinct sources resolve to the same place and identifiers (phone/coords/address/name) line up. Capped at 0.98.
0.9 – 0.98Cross-verified by several sources — very high.0.75 – 0.9Cross-verified — high.0.6 – 0.75Single source or partial identifiers — moderate. In Korea many venues appear on only one map service, so a single source does not mean low quality.0.3 – 0.6Few identifiers or names disagree across sources — verify before use.
We exclude places confirmed closed from recommendation by default. But do not treat low freshness or confidence as proof of closure — the place may well be operating. These two scores are a screening aid, not a closure verdict.
Authentication
Keys belong to an account. They're stored hashed; the plaintext is revealed once at creation. REST authenticates with Authorization: Bearer <KEY> (or X-API-Key). MCP (mcp.heyyumi.ai, repo map3-mcp) supports both: drop in the same Bearer key (e.g. Cursor), or connect key-free via Google sign-in (OAuth) like a ChatGPT/Claude custom connector. ?api_key= in the URL is deprecated — URLs are easy to log.
Error codes
400Invalid params / bulk_export_required — result window too large.401Missing/invalid key — check your header and key.404Place not found.429Rate limit or monthly quota exceeded — wait Retry-After or upgrade.5xxServer error — retry shortly.