Verbinden
Entwicklerhandbuch
HeyYumi ist eine API, die sich wie das Notizbuch einer einzelnen Kuratorin liest. Mit einem einzigen Schlüssel erreichst du die aufbereiteten Locations (das Oneset): Öffnungszeiten, Menü, Preisklasse, Bewertung, Aktivitätsaktualität und Vertrauen, dazu Parken (Art/Gebühr/Hinweis), einen veganen/vegetarischen Ernährungsindex, die Sprachen, die die Location bedienen kann, und eine KI-Zusammenfassung in einer Zeile, bereits aufgeräumt. Kein GPS? Wandle einen Stadtteilnamen wie "Hongje-dong" über /regions in Codes und Koordinaten um (gleichnamige Dongs werden nach Sido/Sigungu unterschieden) und nutze ihn direkt für die Umkreissuche. Über das Lesen hinaus kann derselbe Schlüssel Reservierungsanfragen und Echtzeitfragen wie 'Ist das gerade verfügbar?' senden (Bestand, Wartezeit, sofortige Platzierung), die der Inhaber innerhalb von 5 Minuten beantwortet.
Dieses Handbuch behandelt alle drei Verbindungswege (API, MCP und CLI) an einem Ort. Das Verbinden unterscheidet sich je nach Methode; die Daten, die Abrechnung, die Bewertungen und die Fehler weiter unten sind bei allen dreien gleich.
① Verbinden: drei Wege, jeder anders
Was du auch baust, du erreichst Yumi auf einem von drei Wegen. Jeder hat seinen eigenen Charakter, also unterscheidet sich das Verbinden. Folge dem Link jeder Karte für die vollständige Ansicht.
Verbinde Agenten wie Claude, Cursor, ChatGPT oder Perplexity. ChatGPT verbindet sich über das Plugin-Verzeichnis; die anderen nutzen die Server-URL. Melde dich mit Google an oder verwende einen API-Schlüssel.
- 01ChatGPT: HeyYumi in den Plugins suchen → verbinden
- 02Claude/Cursor/Perplexity: die MCP-Server-URL hinzufügen
- 03Google-Anmeldung (OAuth) oder Bearer-Schlüssel
server url
https://mcp.heyyumi.ai/mcp
Per REST in dein Produkt oder Backend einbinden. Server-zu-Server.
- 01Einen Schlüssel im Dashboard erstellen
- 02Authorization: Bearer <KEY> senden
- 03Erster Aufruf an /api/v1/places
curl
curl -H "Authorization: Bearer hmp_xxx" \ "https://api.heyyumi.ai/api/v1/places?keyword=burger"
Für Terminal-Agenten wie Claude Code und Codex. Installieren → anmelden → wird automatisch als MCP registriert.
- 01npm i -g @heyyumi/cli
- 02heyyumi login
- 03heyyumi mcp install
terminal
npm i -g @heyyumi/cli heyyumi login heyyumi mcp install
② Gemeinsam: für alle drei gleich
Wie du auch verbindest, der Rest ist identisch: welche Daten Yumi zurückgibt, wie Felder Tokens verbrauchen, wie du die Bewertungen liest und was die Fehler bedeuten.
Feldauswahl · gestaffelte Abrechnung
Wir geben nicht alles auf einmal zurück. Mit dem Parameter fields wählst du, was du erhältst: Stufennamen (core/contact_hours/quality/edge/media), 'all' oder einzelne Feldnamen, durch Kommas getrennt. Standard ist core.
core1 tokenCore (identity & location)id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt
contact_hours2 tokensContact & hoursphone, homepage, bookingUrl, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h
quality2 tokensQuality & pricerating, reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation
edge4 tokensMoat (access & context)accessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, influencerFeatures, culturalAssociations, legacy, reputation
media8 tokensPhotos (rich media)photos
Die Abrechnung erfolgt pro Anfrage. Ein Aufruf kostet die höchste angeforderte Feldstufe (page_size beeinflusst die Tokens nicht). Dein Monatskontingent wird in Tokens abgezogen, und du kannst es innerhalb des Monats frei ausgeben (kein Tageslimit). Missbrauch wird über Limits gesteuert, nicht über den Preis: rpm pro Plan, Ergebnisfenster pro Abfrage (Starter 1,000 · Pro 5,000) und eine Obergrenze für verschiedene Locations in 30 Tagen (Starter 10,000 · Pro 40,000; Free 3,000). Die Obergrenze zählt nur eindeutige Locations. Dieselbe Location mehrfach zurückzugeben zählt weiterhin als eine (wiederholtes Ausliefern summiert sich nie; nur das komplette Abgreifen des Datensatzes erreicht sie). Vollständige oder große Datenmengen werden über Bulk Export · Datenlizenzierung verkauft, nicht über Paginierung (siehe Richtlinie zur zulässigen Nutzung in den Bedingungen).
Die Bewertungen lesen: Aktualität · Vertrauen
Yumi presst "ist dieser Ort empfehlenswert?" nicht in eine einzige Gesamtbewertung. Stattdessen legen wir die zugrunde liegenden Signale transparent offen und lassen dich nach deiner eigenen Richtlinie entscheiden. Jede Bewertung ist so normiert, dass höher besser ist.
freshnessScore · Aktivitätsaktualität (0–1, höher = aktueller)Yumis Schätzung von 0 bis 1, wie aktuell das jüngste Aktivitätssignal eines Ortes ist. Maximum ist 1.0.
0.8 – 1.0Deutliche aktuelle Aktivität (innerhalb von ~4 Monaten). Aktiv.0.5 – 0.8Etwa 4–9 Monate. Mittel.0.2 – 0.5Etwa 9–14 Monate. Direkt überprüfen.0 – 0.2Etwa 14–18 Monate oder mehr. Schwaches Aktivitätssignal.null (keine)Bedeutet nur, dass zu wenig Signal vorlag, um die Aktualität zu berechnen; kein Schließungssignal.
confidence · Datenvertrauen (0.3–0.98, höher = vertrauenswürdiger)Ein Kreuzvalidierungswert, der steigt, wenn mehr verschiedene Quellen auf denselben Ort verweisen und die Kennungen (Telefon/Koordinaten/Adresse/Name) zusammenpassen. Gedeckelt bei 0.98.
0.9 – 0.98Von mehreren Quellen kreuzgeprüft. Sehr hoch.0.75 – 0.9Kreuzgeprüft. Hoch.0.6 – 0.75Einzelquelle oder teilweise Kennungen. Mittel. In Korea erscheinen viele Locations nur auf einem Kartendienst, daher bedeutet eine einzelne Quelle keine schlechte Qualität.0.3 – 0.6Wenige Kennungen oder Namen, die sich zwischen Quellen widersprechen. Vor der Nutzung überprüfen.
Als geschlossen bestätigte Orte schließen wir standardmäßig von Empfehlungen aus. Aber nimm niedrige Aktualität oder Vertrauen nicht als Beweis für eine Schließung. Der Ort kann durchaus geöffnet sein. Diese beiden Bewertungen sind eine Filterhilfe, kein Schließungsurteil.
Authentifizierung
Schlüssel gehören zu einem Konto. Sie werden nur gehasht gespeichert; der Klartext wird bei der Erstellung nur einmal angezeigt. REST authentifiziert sich mit Authorization: Bearer <KEY> (oder X-API-Key). MCP (mcp.heyyumi.ai, Repository map3-mcp) unterstützt beides: denselben Bearer-Schlüssel einsetzen (z. B. bei Cursor) oder ohne Schlüssel über die Google-Anmeldung (OAuth) verbinden. ChatGPT über das Plugin-Verzeichnis, Claude und Perplexity über einen benutzerdefinierten Connector. ?api_key= in der URL ist veraltet, weil URLs leicht in Logs landen.
Fehlercodes
400Ungültige Parameter / bulk_export_required. Ergebnisfenster zu groß.401Schlüssel fehlt/ungültig. Prüfe Header und Schlüssel.404Ort nicht gefunden.422Location kann keine Reservierungen oder Echtzeitfragen annehmen (reservation_not_available / live_status_not_available). Nur Locations von Yumi Partner oder der Inhaber-App. Nicht erneut versuchen; dem Nutzer anzeigen.429Ratenlimit oder Monatskontingent überschritten. Warte gemäß Retry-After oder erhöhe den Plan.5xxServerfehler. Kurz darauf erneut versuchen.