Pour commencer

Documentation développeur

Une seule clé API te donne les données des établissements coréens : horaires, menu, gamme de prix, nombre d'avis, stationnement, plats végétariens, langues parlées sur place et un résumé en une ligne rédigé par l'IA. Chaque établissement a un score de fraîcheur et un score de confiance. Pas de coordonnées ? Envoie un nom de quartier comme "Hongje-dong" à /regions pour obtenir ses coordonnées, puis utilise-les dans la recherche à proximité. La même clé sert aussi à demander une réservation ou à poser une question sur la situation du moment, comme le stock ou l'attente. Le gérant reçoit alors une notification qui lui demande de répondre en 5 minutes.

Commence par créer une clé. La même clé fonctionne avec MCP, la CLI et l'API REST.

Trois façons de se connecter

Choisis selon ce que tu construis. Chaque page détaille les étapes.

Colle une ligne d'instructions dans une IA comme Claude, Cursor, Codex ou Gemini, et elle termine la connexion toute seule. ChatGPT se connecte par son plugin. Pour configurer à la main, ajoute l'URL du serveur ci-dessous et authentifie-toi avec Google ou une clé API.

https://mcp.heyyumi.ai/mcp
REST APIREST API →

Appelle-la en HTTP depuis le serveur de ton service. Les réponses sont en JSON.

curl -H "Authorization: Bearer hmp_xxx" \
  "https://api.heyyumi.ai/api/v1/places?keyword=burger"

Pour les agents qui travaillent dans le terminal, comme Claude Code, Codex et Gemini CLI. Rien à installer : npx lance la CLI, et une connexion Google suffit pour chercher et envoyer des demandes de réservation.

npx -y heyyumi login
npx -y heyyumi search matcha --business_category cafe --region Euljiro

Commun aux trois méthodes

Quelle que soit la méthode, l'authentification, les tokens, les scores et les codes d'erreur sont les mêmes.

Authentification

La clé appartient au compte qui l'a créée. Le serveur n'en garde qu'un hachage : la clé en clair ne s'affiche qu'une fois, à la création. En REST, authentifie-toi avec l'en-tête Authorization: Bearer <KEY> ou X-API-Key. Le serveur MCP (mcp.heyyumi.ai) accepte les deux : une clé Bearer, comme dans Cursor, ou la connexion Google (OAuth) sans clé, comme dans ChatGPT, Claude et Perplexity. Passer la clé dans l'URL avec ?api_key= sera bientôt bloqué, car elle finit facilement dans les journaux du serveur.

Choix des champs et tokens

Le paramètre fields choisit les champs renvoyés : noms de palier (core, contact_hours, quality, edge, media), all ou noms de champs, séparés par des virgules. Sans fields, tu reçois seulement core.

  • core1 tokenCore (identity & location)

    id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt, placeUrl

  • contact_hours2 tokensContact & hours

    phone, homepage, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h

  • quality2 tokensQuality & price

    reviewCount, latestReviewDate, freshnessScore, dataQuality, price, menuSummary, openNow, closureSignal, promotion, photoCount, nearestStation, michelin

  • edge4 tokensAccess & context

    accessHints, recommendedFor, atmosphere, menu, serviceAttributes, dietary, atmosphereScores, aiSummary, ownerIntro, ownerStory, influencerFeatures, culturalAssociations, legacy, reputation

  • media8 tokensPhotos

    photos

Chaque requête consomme des tokens une seule fois, selon le palier le plus élevé parmi les champs demandés. page_size n'a aucun effet sur les tokens. Chaque compte a 50 000 tokens gratuits par mois, sans limite quotidienne. Limites du compte gratuit : 30 requêtes par minute (au-delà, 429 avec Retry-After), 100 résultats par recherche et 20 000 établissements distincts sur les 30 derniers jours. Un même établissement affiché plusieurs fois compte pour un. Si tu as besoin de toutes les données, ne pagine pas pour les collecter : passe par Bulk Export ou une licence de données (Politique d'utilisation acceptable des Conditions).

Lire les scores : fraîcheur et confiance

Les scores sont fournis séparément, sans être fusionnés en une note unique. À chaque service de décider quoi recommander selon ses propres critères. Pour tous les scores, plus c'est haut, mieux c'est.

freshnessScore · fraîcheur d'activité (0–1, plus haut = plus récent)

Mesure, entre 0 et 1, l'activité récente de l'établissement.

  • 0.8 – 1.0Beaucoup d'activité ces 4 derniers mois.
  • 0.5 – 0.8Dernière activité il y a environ 4 à 9 mois.
  • 0.2 – 0.5Dernière activité il y a environ 9 à 14 mois. Mieux vaut vérifier avant d'y aller.
  • 0 – 0.2Presque aucune activité depuis plus de 14 à 18 mois.
  • null (aucune)Pas assez de signaux pour calculer le score. Cela ne veut pas dire que l'établissement a fermé.
confidence · confiance des données (0.3–0.98, plus haut = plus fiable)

Augmente quand plusieurs sources désignent le même établissement et que téléphone, coordonnées, adresse et nom concordent. Le maximum est 0.98.

  • 0.9 – 0.98Confirmé comme le même établissement par plusieurs sources.
  • 0.75 – 0.9Les informations des sources concordent.
  • 0.6 – 0.75Une seule source, ou des identifiants partiels. Beaucoup d'établissements n'ont qu'une source, donc cette tranche ne veut pas dire que la qualité est faible.
  • 0.3 – 0.6Peu d'identifiants ou des noms qui divergent selon les sources. Vérifie avant utilisation.

Retire des recommandations les établissements dont la fermeture est confirmée. Une fraîcheur ou une confiance faible ne prouve pas une fermeture : l'établissement peut très bien être encore ouvert. Utilise ces deux scores pour filtrer.

Codes d'erreur

  • 400Paramètres non valides, ou plage de résultats demandée trop grande (bulk_export_required).
  • 401Clé manquante ou non valide. Vérifie ton en-tête et ta clé.
  • 404Établissement introuvable.
  • 422Cet établissement n'accepte pas encore les réservations ni les questions en temps réel via HeyYumi (reservation_not_available, live_status_not_available). Ne réessaie pas : préviens l'utilisateur. En dehors des heures de demande, tu reçois reservation_requests_closed, avec la prochaine ouverture dans retryAfter. Si l'établissement est fermé à l'heure demandée, tu reçois venue_closed_at_requested_time.
  • 429Limite par minute ou quota mensuel dépassé. Attends la durée indiquée dans Retry-After avant de renvoyer la requête, ou contacte-nous.
  • 5xxErreur serveur. Réessaie sous peu.