Conectar

Guía para desarrolladores

HeyYumi es una API que se lee como el cuaderno de una sola curadora. Con una única clave llegas a los locales depurados (el oneset): horarios, menú, franja de precios, valoración, frescura de actividad y confianza, además de aparcamiento (tipo/tarifa/nota), un índice dietético vegano/vegetariano, los idiomas que el local puede atender y un resumen de una línea hecho por IA, ya ordenados. ¿Sin GPS? Convierte el nombre de un barrio como "Hongje-dong" en códigos y coordenadas con /regions (los dong con el mismo nombre se distinguen por sido/sigungu) y úsalo directamente en la búsqueda por cercanía. Más allá de leer, la misma clave puede enviar solicitudes de reserva y preguntas en tiempo real como '¿esto está disponible ahora mismo?' (stock, espera, mesa inmediata) que el dueño responde en 5 minutos.

Esta guía cubre las tres formas de conectar (API, MCP y CLI) en un solo lugar. La forma de conectar cambia según el método; los datos, la facturación, las puntuaciones y los errores de más abajo son comunes a los tres.

Obtener una clave de API →Referencia de API →Pruébalo en vivo →Servidor MCP →CLI →Especificación OpenAPI

① Conectar: tres formas, cada una distinta

Sea lo que sea que estés creando, llegas a Yumi por una de estas tres vías. Cada una tiene su propio carácter, así que la forma de conectar cambia. Sigue el enlace de cada tarjeta para ver la pantalla completa.

MCPActivo

Conecta agentes como Claude, Cursor, ChatGPT o Perplexity. ChatGPT se conecta desde el directorio de plugins; los demás usan la URL del servidor. Inicia sesión con Google o usa una clave de API.

01ChatGPT: busca HeyYumi en Plugins → Conectar
02Claude/Cursor/Perplexity: añade la URL del servidor MCP
03Inicio de sesión con Google (OAuth) o clave Bearer

server url

https://mcp.heyyumi.ai/mcp

Ver conexión de MCP →

APIActivo

REST en tu producto o backend. De servidor a servidor.

01Crea una clave en el panel
02Envía Authorization: Bearer <KEY>
03Primera llamada a /api/v1/places

curl

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

Ver toda la conexión de API →

CLIPróximamente

Para agentes de terminal como Claude Code y Codex. Instala → inicia sesión → se registra automáticamente como MCP.

01npm i -g @heyyumi/cli
02heyyumi login
03heyyumi mcp install

terminal

npm i -g @heyyumi/cli
heyyumi login
heyyumi mcp install

Ver conexión de CLI →

② Común: igual para las tres

Conectes como conectes, lo demás es idéntico: qué datos devuelve Yumi, cómo los campos consumen tokens, cómo leer las puntuaciones y qué significan los errores.

Selección de campos · facturación por niveles

No devolvemos todo de una vez. Usa el parámetro fields para elegir qué recibes: nombres de nivel (core/contact_hours/quality/edge/media), 'all' o nombres de campo individuales, separados por comas. Por defecto es core.

core1 tokenCore (identity & location)
id, name, category, categoryLabel, location, address, regionCode, confidence, sourceCount, possiblyClosed, lastSeenAt
contact_hours2 tokensContact & hours
phone, homepage, bookingUrl, yumiReservable, reservationChannels, snsLinks, businessHours, temporaryClosures, is24h
quality2 tokensQuality & price
rating, 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 facturación es por solicitud. Una llamada cuesta el nivel de campo más alto que pidas (page_size no afecta a los tokens). Tu cuota mensual se descuenta en tokens y puedes gastarla libremente dentro del mes (sin límite diario). El abuso se controla con límites, no con el precio: rpm por plan, ventanas de resultados por consulta (Starter 1,000 · Pro 5,000) y un tope de locales distintos en 30 días (Starter 10,000 · Pro 40,000; Free 3,000). El tope de distintos cuenta solo locales únicos. Devolver el mismo local muchas veces sigue contando como uno (servir de forma repetida nunca se acumula; solo recolectar el conjunto de datos entero lo alcanza). Los datos completos o masivos se venden mediante Bulk Export · licencia de datos, no con paginación (consulta la Política de uso aceptable en los Términos).

Cómo leer las puntuaciones: frescura · confianza

Yumi no reduce "¿vale la pena recomendar este lugar?" a una sola puntuación combinada. En su lugar, exponemos de forma transparente las señales que la componen y dejamos que tú decidas según tu propia política. Todas las puntuaciones están normalizadas para que un valor más alto sea mejor.

freshnessScore · frescura de actividad (0–1, más alto = más reciente)

Estimación de Yumi, de 0 a 1, de cómo de reciente es la última señal de actividad de un local. El máximo es 1.0.

0.8 – 1.0Actividad reciente clara (en unos 4 meses). Activo.
0.5 – 0.8Unos 4–9 meses. Moderado.
0.2 – 0.5Unos 9–14 meses. Verifícalo directamente.
0 – 0.2Unos 14–18 meses o más. Señal de actividad débil.
null (sin datos)Solo significa que faltó señal para calcular la frescura; no es una señal de cierre.

confidence · confianza de los datos (0.3–0.98, más alto = más fiable)

Una puntuación de verificación cruzada que sube cuando más fuentes distintas coinciden en el mismo local y los identificadores (teléfono/coordenadas/dirección/nombre) encajan. Con tope en 0.98.

0.9 – 0.98Verificado de forma cruzada por varias fuentes. Muy alta.
0.75 – 0.9Verificado de forma cruzada. Alta.
0.6 – 0.75Fuente única o identificadores parciales. Moderada. En Corea muchos locales aparecen en un solo servicio de mapas, así que una sola fuente no significa baja calidad.
0.3 – 0.6Pocos identificadores o nombres que no coinciden entre fuentes. Verifícalo antes de usarlo.

Por defecto excluimos de las recomendaciones los locales que se confirman cerrados. Pero no tomes una frescura o una confianza bajas como prueba de cierre. El local podría estar abierto. Estas dos puntuaciones son una ayuda para filtrar, no un veredicto de cierre.

Autenticación

Las claves pertenecen a una cuenta. Se guardan con hash; el texto plano se muestra una sola vez al crearla. REST se autentica con Authorization: Bearer <KEY> (o X-API-Key). MCP (mcp.heyyumi.ai, repositorio map3-mcp) admite ambas opciones: usa la misma clave Bearer (por ejemplo, en Cursor), o conéctate sin clave mediante el inicio de sesión con Google (OAuth). ChatGPT desde el directorio de plugins, Claude y Perplexity mediante un conector personalizado. ?api_key= en la URL está obsoleto porque las URL quedan fácilmente en los registros.

Códigos de error

400Parámetros no válidos / bulk_export_required. La ventana de resultados es demasiado grande.
401Clave ausente o no válida. Revisa la cabecera y la clave.
404Local no encontrado.
422El local no puede aceptar reservas ni preguntas en tiempo real (reservation_not_available / live_status_not_available). Solo los locales de Yumi Partner o de la app para dueños. No reintentes; muéstralo al usuario.
429Límite de tasa o cuota mensual superada. Espera lo indicado en Retry-After o mejora el plan.
5xxError del servidor. Reinténtalo en un momento.