Erste Schritte
Entwicklerdokumentation
Mit einem API-Schlüssel bekommst du Daten zu Lokalen in Korea: Öffnungszeiten, Speisekarte, Preisklasse, Zahl der Bewertungen, Parken, vegetarische Gerichte, Fremdsprachen, in denen bedient wird, und eine einzeilige KI-Zusammenfassung. Zu jedem Lokal gibt es außerdem einen Aktualitäts- und einen Vertrauenswert. Hast du keine Koordinaten, schick einen Stadtteilnamen wie "Hongje-dong" an /regions und nimm die Koordinaten aus der Antwort für die Umkreissuche. Mit demselben Schlüssel kannst du auch Reservierungen anfragen oder nach der aktuellen Lage fragen, etwa nach Vorrat oder Wartezeit. Der Inhaber wird dann benachrichtigt und gebeten, innerhalb von 5 Minuten zu antworten.
Erstelle zuerst einen Schlüssel. Damit kannst du MCP, CLI und die REST API nutzen.
Drei Wege zum Verbinden
Wähle den Weg, der zu deinem Projekt passt. Die einzelnen Schritte stehen jeweils auf der eigenen Seite.
Füge eine Zeile in eine KI wie Claude, Cursor, Codex oder Gemini ein, dann richtet sie die Verbindung selbst ein. ChatGPT verbindest du über das Plugin. Für die manuelle Einrichtung trägst du die Server-URL unten ein und meldest dich mit Google oder einem API-Schlüssel an.
https://mcp.heyyumi.ai/mcp
Du rufst sie per HTTP von deinem Server auf. Die Antworten kommen als JSON.
curl -H "Authorization: Bearer hmp_xxx" \ "https://api.heyyumi.ai/api/v1/places?keyword=burger"
Passt zu Agenten, die im Terminal arbeiten, etwa Claude Code, Codex oder Gemini CLI. Sie läuft ohne Installation über npx. Nach einer Google-Anmeldung kannst du suchen und Reservierungen anfragen.
npx -y heyyumi login npx -y heyyumi search matcha --business_category cafe --region Euljiro
Für alle Wege gleich
Authentifizierung, Tokens, Aktualitäts- und Vertrauenswerte sowie Fehlercodes sind bei allen drei Wegen gleich.
Authentifizierung
Ein Schlüssel gehört zu dem Konto, das ihn erstellt hat. Auf dem Server speichern wir nur einen Hash, deshalb siehst du den Schlüssel im Klartext nur einmal beim Erstellen. Bei REST authentifizierst du dich mit dem Header Authorization: Bearer <KEY> oder X-API-Key. Der MCP-Server (mcp.heyyumi.ai) akzeptiert beides. Du kannst wie bei Cursor einen Bearer-Schlüssel mitschicken oder dich wie bei ChatGPT, Claude und Perplexity ohne Schlüssel per Google-Anmeldung (OAuth) verbinden. ?api_key= in der URL schalten wir bald ab, weil der Schlüssel so leicht in Server-Logs landet.
Felder auswählen und Tokens
Mit dem Parameter fields legst du fest, welche Felder du bekommst. Gib Stufennamen (core, contact_hours, quality, edge, media), all oder einzelne Feldnamen an, durch Kommas getrennt. Lässt du ihn leer, kommt nur core.
core1 tokenCore (identity & location)id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt, placeUrl
contact_hours2 tokensContact & hoursphone, homepage, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h
quality2 tokensQuality & pricereviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation, michelin
edge4 tokensAccess & contextaccessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, ownerStory, influencerFeatures, culturalAssociations, legacy, reputation
media8 tokensPhotosphotos
Pro Anfrage werden einmal Tokens abgezogen, und zwar so viele, wie die höchste angeforderte Stufe kostet. page_size spielt dabei keine Rolle. Jedes Konto bekommt jeden Monat 50.000 Tokens kostenlos, ein Tageslimit gibt es nicht. Für kostenlose Konten gelten diese Limits: 30 Anfragen pro Minute (darüber kommt 429 mit Retry-After), 100 Ergebnisse pro Suche und 20.000 verschiedene Lokale in den letzten 30 Tagen. Ein Lokal, das du mehrfach ausgibst, zählt dabei nur einmal. Brauchst du den kompletten Datenbestand, nutze Bulk Export oder eine Datenlizenz, statt alle Seiten abzurufen (siehe Richtlinie zur zulässigen Nutzung in den Nutzungsbedingungen).
So liest du die Werte: Aktualität und Vertrauen
Du bekommst die Werte einzeln, ohne Gesamtnote. Ob du ein Lokal empfiehlst, entscheidest du nach deinen eigenen Kriterien. Bei allen Werten gilt: höher ist besser.
freshnessScore · Aktualität (0–1, höher = jüngere Aktivität)Ein Wert zwischen 0 und 1, der zeigt, wie viel Aktivität es zuletzt rund um das Lokal gab.
0.8 – 1.0Viel Aktivität in den letzten 4 Monaten.0.5 – 0.8Letzte Aktivität vor etwa 4–9 Monaten.0.2 – 0.5Letzte Aktivität vor etwa 9–14 Monaten. Vor einem Besuch lieber nachprüfen.0 – 0.2Seit etwa 14–18 Monaten oder länger kaum Aktivität.null (keine)Zu wenige Signale für einen Wert. Das heißt nicht, dass das Lokal geschlossen hat.
confidence · Verlässlichkeit der Daten (0.3–0.98, höher = verlässlicher)Steigt, je mehr Quellen auf dasselbe Lokal verweisen und je besser Telefonnummer, Koordinaten, Adresse und Name zusammenpassen. Der Höchstwert ist 0.98.
0.9 – 0.98Mehrere Quellen bestätigen dasselbe Lokal.0.75 – 0.9Die Angaben der Quellen stimmen überein.0.6 – 0.75Nur eine Quelle oder nur ein Teil der Identifikationsmerkmale. Viele Lokale haben nur eine Quelle, ein Wert in diesem Bereich heißt also nicht, dass die Daten schlecht sind.0.3 – 0.6Wenige Identifikationsmerkmale, oder die Quellen nennen unterschiedliche Namen. Vor der Nutzung prüfen.
Lokale, deren Schließung bestätigt ist, solltest du nicht empfehlen. Ein niedriger Aktualitäts- oder Vertrauenswert heißt aber nicht, dass ein Lokal geschlossen hat. Es kann noch geöffnet sein. Nutze die beiden Werte zum Filtern.
Fehlercodes
400Ungültige Parameter, oder der angefragte Ergebnisbereich ist zu groß (bulk_export_required).401Schlüssel fehlt oder ist falsch. Prüfe Header und Schlüssel.404Lokal nicht gefunden.422Das Lokal nimmt über HeyYumi noch keine Reservierungen oder Live-Anfragen an (reservation_not_available, live_status_not_available). Nicht erneut versuchen, sondern dem Nutzer Bescheid geben. Außerhalb der Annahmezeiten kommt reservation_requests_closed. Wann wieder Anfragen angenommen werden, steht in retryAfter. Hat das Lokal zur gewünschten Zeit geschlossen, kommt venue_closed_at_requested_time.429Minuten- oder Monatslimit überschritten. Warte die in Retry-After angegebene Zeit ab und sende dann erneut, oder melde dich bei uns.5xxServerfehler. Versuch es gleich noch einmal.