Con una clave que tenga los permisos releases:read y data:read, los sistemas de una cuenta Enterprise leen las tablas que exporta el portal, fechadas por semana ISO (de lunes a domingo, hora peninsular). Hay tres vías: las semanas publicadas, cada tipo de datos en JSON y las tablas enteras como feeds CSV. Las listas y los feeds del módulo de campo funcionan igual, si la cuenta lo tiene. Todas las rutas que siguen empiezan por /api/portal/v1.
Semanas publicadas
GET /releases (permiso releases:read, la operación list_releases) lista las semanas ISO publicadas en el portal, de la más reciente a la más antigua, con cuántas tiendas publicó cada una:
{ "data": [ { "week": "2026-W41", "stores": 12 } ] }
Una semana se publica con la actualización nocturna que sigue a su cierre; los recorridos de la semana en curso nunca aparecen, salvo los de prueba de la propia MercaMap. Una semana nueva aquí significa datos nuevos, así que es lo más barato de consultar.
Datos del lineal en JSON
GET /data/{kind} (permiso data:read, la operación get_data) responde con un tipo de datos de la cuenta, tal como lo leen las exportaciones del portal:
| Tipo | Qué contiene |
|---|---|
placements |
Las ubicaciones de tus productos: una fila por producto y ubicación en cada tienda, con su nivel, sus facings y su precio observado |
prices |
Series semanales de precios observados por producto y tienda |
presence |
Cada uno de tus productos por cadena y provincia, frente a las tiendas cuyos recorridos miraron su categoría |
history |
Lo mismo semana a semana, dentro del historial del plan |
changes |
Lo que apareció, se movió, cambió de nivel o de precio, o dejó de verse, por tienda y semana |
visits |
Las tiendas a visitar, una fila por motivo |
shares |
Cuotas de referencias por categoría y sección, con los competidores, solo como marca |
En placements, entrance_distance_m es la distancia a pie desde la entrada más cercana, en metros enteros, vacía si el mapa no midió su entrada o no lleva hasta el lugar; unconfirmed_since_week es la semana desde la que el equipo lo marcó Sin confirmar, y price_corrected_week la de una lectura de precio retirada mientras sea el precio del lugar (con price_cents vacío). En prices, corrected_readings cuenta las lecturas retiradas de cada semana de las últimas 26 semanas, fuera de sus cifras.
La respuesta es { "kind", "columns", "truncated", "notice", "data" }: data lleva un objeto por fila, con las columnas como claves; notice recuerda que todas las cifras son observadas e indicativas (la primera línea de los archivos), y visits añade la attribution de sus direcciones. Las filas llegan de la semana más reciente a la más antigua (visits, de la más urgente a la menos). Acótalas con since y until (semanas ISO, incluidas), productId, storeId, chain (escrita como la dan las filas), province (su código INE de dos cifras) y categoryId: se aplican antes del límite de filas, así que una llamada toma y cuenta solo las filas que dejan. Un tipo responde 400 a un filtro para el que no tiene columna (ni presence ni history tienen tienda; shares no tiene semana ni producto). limit toma solo las primeras filas; sin él, una llamada toma hasta el límite de exportación del plan, que ningún limit supera. truncated: true significa que han quedado filas fuera.
Estas tablas no tienen cursor: cada llamada lee su tabla una vez y entera, así que una respuesta nunca mezcla dos estados de los datos, y cuesta las filas leídas. Para leer una tabla entera, usa su feed. Las listas del módulo de campo que se paginan (incidencias, visitas, pedidos y albaranes) responden next: devuélvelo como cursor para la página siguiente. Un cursor que no sea de esa lista responde 400.
Tiendas y productos por su nombre
GET /stores (la operación find_stores) y GET /products (find_products) encuentran los identificadores que piden las demás operaciones: las tiendas de la cuenta, por una palabra de su nombre o de su localidad o por tu código de tienda, dentro de una cadena o de una provincia; tus productos, por palabras de su marca y su nombre en cualquier orden, tu código de catálogo o un código de barras en cualquiera de sus formas (UPC-A, EAN-13 o GTIN-14). Les basta cualquiera de los permisos data:read, issues:read, orders:read o deliveries:read, y no restan filas del día de la cuenta.
Tablas enteras en CSV
GET /feeds/{kind}.csv, con la misma clave y data:read (la operación get_feed de la descripción), responde con una tabla entera en un solo archivo CSV, para Power BI, Excel o cualquier herramienta que lea una dirección web con una cabecera. Los tipos son los de /data. El archivo empieza con unas líneas que comienzan por # (el aviso y la atribución), luego la cabecera y las filas; un archivo cortado en el límite de filas del plan termina con una línea que empieza por # truncated to. Las columnas son las de las exportaciones del portal, nombradas en la cabecera, y sus valores se escriben igual sea cual sea el idioma del miembro: el tamaño de un producto es 1.5 l, nunca 1,5 l. Los archivos de importación y de entrega del módulo de campo están en Formatos CSV del módulo de campo. Mientras el módulo de campo está abierto para la cuenta, añade issues.csv, orders.csv, deliveries.csv y scorecards.csv, cada uno con su propio permiso.
La autenticación Basic de los feeds
Los feeds, y solo ellos, aceptan también la autenticación HTTP Basic, para herramientas que piden usuario y contraseña (herramientas de BI): mercamap como usuario y la clave entera como contraseña (también valen el identificador de la clave con el secreto, o la clave entera como usuario con la contraseña vacía). Solo pasa una clave de lectura: una con issues:write, orders:write o catalogue:write recibe 403. Una clave errónea, caducada o revocada recibe el mismo 401, cuyo WWW-Authenticate nombra los dos esquemas, y los límites no cambian.
Semanas, nunca días
Todas las fechas de estas respuestas son semanas ISO, escritas YYYY-Www: una respuesta que llevaría una fecha y una hora falla antes que salir. Un precio es el observado en una semana concreta, nunca el precio vigente, y una cuota o una presencia sobre menos de 30 tiendas es indicativa. Las filas leídas cuentan para el día de la cuenta (límites de peticiones y filas al día).
El centro de ayuda
POST /help/search (search_help) recibe la pregunta en el q de un cuerpo JSON, nunca en la dirección, y responde con los artículos publicados que encajan, los mejores primero, con sus secciones más afines, un extracto y su dirección; locale pide es o en, y limit, hasta diez. GET /help/{slug} (read_help) responde con un artículo en Markdown, sección a sección. Ninguna necesita permiso ni resta filas del día de la cuenta, y el texto buscado no se guarda.
Para clientes de IA
list_releases, get_data, search_help y read_help son también herramientas de la capa MCP para clientes de IA, donde get_data toma como máximo 200 filas por llamada y truncated indica que hay más; el feed CSV lee una tabla entera. La referencia del MCP recoge las herramientas, y la referencia de la API, todas las operaciones.