Connexion
Guide du développeur
HeyYumi est une API qui se lit comme le carnet d'une seule curatrice. Une seule clé donne accès aux établissements affinés (le oneset) : horaires, menu, gamme de prix, note, fraîcheur d'activité et confiance, ainsi que le stationnement (type/tarif/note), un index alimentaire végane/végétarien, les langues que l'établissement peut servir et un résumé en une ligne rédigé par l'IA, déjà mis en ordre. Pas de GPS ? Convertis un nom de quartier comme "Hongje-dong" en codes et coordonnées via /regions (les dong homonymes sont distingués par sido/sigungu) et utilise-le directement dans la recherche à proximité. Au-delà de la lecture, la même clé peut envoyer des demandes de réservation et des questions en temps réel comme 'est-ce disponible en ce moment ?' (stock, attente, place immédiate), auxquelles le propriétaire répond en 5 minutes.
Ce guide couvre les trois façons de se connecter (API, MCP et CLI) au même endroit. La connexion diffère selon la méthode ; les données, la facturation, les scores et les erreurs ci-dessous sont communs aux trois.
① Connexion : trois façons, chacune différente
Quoi que tu construises, tu atteins Yumi par l'une de ces trois voies. Chacune a son propre caractère, donc la connexion diffère. Suis le lien de chaque carte pour l'écran complet.
Connecte des agents comme Claude, Cursor, ChatGPT ou Perplexity. ChatGPT se connecte depuis le répertoire de plugins ; les autres utilisent l'URL du serveur. Connecte-toi avec Google ou utilise une clé API.
- 01ChatGPT : cherche HeyYumi dans les Plugins → Connecter
- 02Claude/Cursor/Perplexity : ajoute l'URL du serveur MCP
- 03Connexion Google (OAuth) ou clé Bearer
server url
https://mcp.heyyumi.ai/mcp
REST dans ton produit ou ton backend. De serveur à serveur.
- 01Créer une clé dans le tableau de bord
- 02Envoyer Authorization: Bearer <KEY>
- 03Premier appel à /api/v1/places
curl
curl -H "Authorization: Bearer hmp_xxx" \ "https://api.heyyumi.ai/api/v1/places?keyword=burger"
Pour les agents de terminal comme Claude Code et Codex. Installe → connecte-toi → s'enregistre automatiquement comme MCP.
- 01npm i -g @heyyumi/cli
- 02heyyumi login
- 03heyyumi mcp install
terminal
npm i -g @heyyumi/cli heyyumi login heyyumi mcp install
② Commun : identique pour les trois
Quelle que soit la façon dont tu te connectes, le reste est identique : quelles données Yumi renvoie, comment les champs consomment des tokens, comment lire les scores et ce que signifient les erreurs.
Sélection des champs · facturation par paliers
Nous ne renvoyons pas tout d'un coup. Utilise le paramètre fields pour choisir ce que tu reçois : noms de palier (core/contact_hours/quality/edge/media), 'all' ou noms de champ individuels, séparés par des virgules. Par défaut : 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
La facturation se fait par requête. Un appel coûte le palier de champ le plus élevé demandé (page_size n'affecte pas les tokens). Ton quota mensuel est décompté en tokens, et tu peux le dépenser librement dans le mois (sans limite quotidienne). L'abus est contrôlé par des limites, pas par le prix : rpm par forfait, fenêtres de résultats par requête (Starter 1,000 · Pro 5,000) et un plafond d'établissements distincts sur 30 jours (Starter 10,000 · Pro 40,000 ; Free 3,000). Le plafond de distincts ne compte que les établissements uniques. Renvoyer le même établissement plusieurs fois compte toujours pour un (servir de façon répétée ne s'accumule jamais ; seule la collecte de l'ensemble des données en bloc l'atteint). Les données complètes ou en masse sont vendues via Bulk Export · licence de données, pas par pagination (voir la Politique d'utilisation acceptable dans les Conditions).
Lire les scores : fraîcheur · confiance
Yumi ne réduit pas "cet endroit vaut-il d'être recommandé ?" à un seul score global. À la place, nous exposons de façon transparente les signaux qui le composent et te laissons décider selon ta propre politique. Chaque score est normalisé pour que plus haut soit meilleur.
freshnessScore · fraîcheur d'activité (0–1, plus haut = plus récent)L'estimation de Yumi, de 0 à 1, de la fraîcheur du dernier signal d'activité d'un lieu. Le maximum est 1.0.
0.8 – 1.0Activité récente nette (dans les ~4 mois). Actif.0.5 – 0.8Environ 4–9 mois. Modéré.0.2 – 0.5Environ 9–14 mois. Vérifie directement.0 – 0.2Environ 14–18 mois ou plus. Signal d'activité faible.null (aucune)Signifie seulement qu'il manquait du signal pour calculer la fraîcheur ; ce n'est pas un signal de fermeture.
confidence · confiance des données (0.3–0.98, plus haut = plus fiable)Un score de vérification croisée qui augmente quand davantage de sources distinctes désignent le même lieu et que les identifiants (téléphone/coordonnées/adresse/nom) concordent. Plafonné à 0.98.
0.9 – 0.98Vérifié de façon croisée par plusieurs sources. Très élevée.0.75 – 0.9Vérifié de façon croisée. Élevée.0.6 – 0.75Source unique ou identifiants partiels. Modérée. En Corée, beaucoup d'établissements n'apparaissent que sur un seul service de cartes, donc une source unique ne signifie pas une faible qualité.0.3 – 0.6Peu d'identifiants ou des noms qui divergent selon les sources. Vérifie avant utilisation.
Par défaut, nous excluons des recommandations les lieux confirmés fermés. Mais ne prends pas une faible fraîcheur ou confiance pour une preuve de fermeture. Le lieu peut très bien être ouvert. Ces deux scores sont une aide au filtrage, pas un verdict de fermeture.
Authentification
Les clés appartiennent à un compte. Elles sont stockées sous forme de hachage ; le texte en clair n'apparaît qu'une seule fois à la création. REST s'authentifie avec Authorization: Bearer <KEY> (ou X-API-Key). MCP (mcp.heyyumi.ai, dépôt map3-mcp) prend en charge les deux : utilise la même clé Bearer (par exemple avec Cursor), ou connecte-toi sans clé via la connexion Google (OAuth). ChatGPT depuis le répertoire de plugins, Claude et Perplexity via un connecteur personnalisé. ?api_key= dans l'URL est déconseillé, car les URL se retrouvent facilement dans les journaux.
Codes d'erreur
400Paramètres non valides / bulk_export_required. Fenêtre de résultats trop grande.401Clé manquante ou non valide. Vérifie ton en-tête et ta clé.404Lieu introuvable.422L'établissement ne peut pas accepter de réservations ni de questions en temps réel (reservation_not_available / live_status_not_available). Uniquement les établissements Yumi Partner ou de l'app propriétaire. Ne réessaie pas ; affiche-le.429Limite de débit ou quota mensuel dépassé. Attends la durée de Retry-After ou passe à un forfait supérieur.5xxErreur serveur. Réessaie sous peu.