Primeros pasos
Documentación para desarrolladores
Con una clave de API recibes datos de locales de Corea: horarios, menú, franja de precios, número de reseñas, aparcamiento, opciones vegetarianas, idiomas en los que atienden y un resumen de una línea hecho por IA. Cada local trae además una puntuación de actualidad y otra de confianza. Si no tienes coordenadas, pasa a /regions el nombre de un barrio como "Hongje-dong", obtén sus coordenadas y úsalas en la búsqueda por cercanía. Con la misma clave puedes pedir una reserva o preguntar por la situación del momento, como el stock o la espera. El dueño recibe un aviso para responder en 5 minutos.
Primero crea una clave. Con una sola clave puedes usar MCP, la CLI y la REST API.
Tres formas de conectar
Elige la que encaje con lo que estás creando. Cada página explica los pasos en detalle.
Pega una línea de instrucciones en una IA como Claude, Cursor, Codex o Gemini y la IA hace la conexión. ChatGPT se conecta como plugin. Si prefieres configurarlo a mano, añade la URL del servidor de abajo y autentícate con Google o con una clave de API.
https://mcp.heyyumi.ai/mcp
Llámala por HTTP desde el servidor de tu servicio. Responde en JSON.
curl -H "Authorization: Bearer hmp_xxx" \ "https://api.heyyumi.ai/api/v1/places?keyword=burger"
Pensada para agentes que trabajan en la terminal, como Claude Code, Codex y Gemini CLI. Se ejecuta con npx sin instalar nada y, tras iniciar sesión una vez con Google, ya puedes buscar y enviar solicitudes de reserva.
npx -y heyyumi login npx -y heyyumi search matcha --business_category cafe --region Euljiro
Aspectos comunes
Conectes como conectes, la autenticación, los tokens, las puntuaciones y los códigos de error son los mismos.
Autenticación
Cada clave pertenece a la cuenta que la creó. En el servidor solo guardamos un hash, así que la clave completa se muestra una sola vez, al crearla. En REST te autenticas con la cabecera Authorization: Bearer <KEY> o con X-API-Key. El servidor MCP (mcp.heyyumi.ai) acepta las dos formas: puedes poner la clave Bearer, como en Cursor, o conectarte sin clave iniciando sesión con Google (OAuth), como en ChatGPT, Claude o Perplexity. Pasar ?api_key= en la URL dejará de funcionar pronto, porque la clave acaba fácilmente en los registros del servidor.
Elegir campos y tokens
Con el parámetro fields eliges qué campos recibes. Pon nombres de nivel (core, contact_hours, quality, edge, media), all o nombres de campo, separados por comas. Si lo dejas vacío, solo recibes 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
Cada solicitud descuenta tokens una sola vez, según el nivel más alto de los campos que pidas. page_size no influye en los tokens. Todas las cuentas tienen 50.000 tokens gratis al mes, sin límite diario. Los límites de la cuenta gratuita son 30 solicitudes por minuto (si los superas, recibes 429 con Retry-After), 100 resultados por búsqueda y 20.000 locales distintos en los últimos 30 días. Un mismo local cuenta como uno aunque lo muestres muchas veces. Si necesitas todos los datos, no los reúnas paginando: usa Bulk Export o una licencia de datos (Política de uso aceptable de los Términos).
Cómo leer las puntuaciones: actualidad y confianza
No juntamos las puntuaciones en una sola: te las damos por separado para que cada servicio decida con su propio criterio si recomienda un local. En todas, más alto es mejor.
freshnessScore · actualidad de la actividad (0–1, cuanto más alto, más reciente)Indica, con un valor de 0 a 1, cuánta actividad reciente tiene el local.
0.8 – 1.0Mucha actividad en los últimos 4 meses.0.5 – 0.8La última actividad fue hace unos 4–9 meses.0.2 – 0.5La última actividad fue hace unos 9–14 meses; conviene comprobarlo antes de ir.0 – 0.2Apenas hay actividad desde hace 14–18 meses o más.null (sin datos)No hay señales suficientes para calcularla. No significa que el local haya cerrado.
confidence · confianza de los datos (0.3–0.98, cuanto más alto, más fiable)Sube cuando varias fuentes apuntan al mismo local y el teléfono, las coordenadas, la dirección y el nombre coinciden entre sí. El máximo es 0.98.
0.9 – 0.98Varias fuentes confirman que es el mismo local.0.75 – 0.9Los datos de las fuentes coinciden.0.6 – 0.75Una sola fuente o solo parte de los datos de identificación. Muchos locales tienen una sola fuente, así que estar en este tramo no significa baja calidad.0.3 – 0.6Pocos datos de identificación o nombres distintos según la fuente. Compruébalo antes de usarlo.
Excluye de tus recomendaciones los locales con cierre confirmado. Pero no des por cerrado un local solo porque su actualidad o su confianza sean bajas: puede seguir abierto. Usa las dos puntuaciones para filtrar.
Códigos de error
400Parámetros no válidos, o pides un rango de resultados demasiado grande (bulk_export_required).401Clave ausente o no válida. Revisa la cabecera y la clave.404Local no encontrado.422El local todavía no acepta reservas ni preguntas en tiempo real a través de HeyYumi (reservation_not_available, live_status_not_available). No reintentes; avisa al usuario. Fuera del horario de solicitudes de reserva recibes reservation_requests_closed, con la próxima apertura en retryAfter. Si el local está cerrado a la hora pedida, recibes venue_closed_at_requested_time.429Superaste el límite por minuto o el mensual. Espera el tiempo indicado en Retry-After y vuelve a intentarlo, o escríbenos.5xxError del servidor. Reinténtalo en un momento.