Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JaiderT/CoffeePrice/llms.txt

Use this file to discover all available pages before exploring further.

The Predictions API exposes machine-learning forecasts for the FNC (Federación Nacional de Cafeteros) reference coffee price. Predictions are generated by CoffePrice’s hybrid ML pipeline and consumed by both producers and buyers to anticipate market movements. All read endpoints are public and require no authentication. Write endpoints (create, update, delete) are restricted to the admin role. Base URL: /api/predicciones
MethodPathAuthDescription
GET/api/prediccionesNoneAll available predictions, ascending by date
GET/api/predicciones/ultimaNoneSingle latest prediction
GET/api/predicciones/resumenNoneTomorrow’s prediction with a plain-text summary
GET/api/predicciones/rangoNonePredictions for the last 7, 15, or 30 days
GET/api/predicciones/diaNonePrediction for today + N days (offset)
GET/api/predicciones/fechaNonePrediction for a specific calendar date
GET/api/predicciones/:idNoneSingle prediction by MongoDB ObjectId
POST/api/prediccionesadminCreate a prediction
PUT/api/predicciones/:idadminUpdate a prediction
DELETE/api/predicciones/:idadminDelete a prediction

​
Data sources

The API resolves predictions from two file-based sources before falling back to MongoDB:
  • backend/datos/predicciones_fnc.json — the most recent prediction generated by the daily ML pipeline run. A single JSON object following the FNC hybrid model schema.
  • backend/datos/historial_predicciones_fnc.csv — a cumulative CSV log of all past predictions produced by the pipeline. Grows with each daily run.
When both file sources are combined and deduplicated by date, the result is a chronological series of predictions. MongoDB is used as a fallback when neither file is present or readable.

​
GET /api/predicciones

Returns all available predictions merged from the history CSV and the latest JSON file, sorted by fecha ascending. If no file data is available, falls back to MongoDB and returns all stored predictions. Authentication: None — public, rate-limited.

​
Response

An array of prediction objects sorted by date ascending.

​
Prediction object fields

​
fecha
string (YYYY-MM-DD)
The calendar date this prediction applies to, in YYYY-MM-DD format.
​
precioestimado
number
Estimated FNC price in Colombian pesos (COP) for the predicted date.
​
preciominimo
number
Lower bound of the prediction confidence interval, in COP.
​
preciomaximo
number
Upper bound of the prediction confidence interval, in COP.
​
tendencia
string
Direction of predicted price movement relative to the current day. One of sube, baja, or estable.
​
confianza
number
Model confidence score from 0 to 100. Derived from the selected strategy’s holdout MAPE using max(45, min(90, round(92 - (mape * 10)))). Falls back to 65 when MAPE is not a finite number. Fixed at 92 when preciominimo === preciomaximo (point prediction with no interval).
​
modelVersion
string
Identifier of the model that produced this prediction. Typically fnc_hibrido.
​
fuente
string
Data source identifier. One of fnc_hibrido_json (from the latest JSON file), fnc_hibrido_historial (from the history CSV), or mongo (from MongoDB).
​
mensaje
string
Human-readable plain-text summary of the prediction, in Spanish. Built from tendencia and confianza, or taken directly from explicacion if available.
​
generatedAt
string (ISO 8601)
Timestamp when the ML pipeline generated this prediction.
​
variacionPorcentual
number
Percentage change between the current FNC price and precioestimado.
​
estrategiaBase
string
Base forecasting strategy used by the model (e.g., media_movil, regresion).
​
holdoutMape
number
Mean Absolute Percentage Error measured on the model’s holdout validation set.
​
holdoutMae
number
Mean Absolute Error measured on the model’s holdout validation set, in COP.
​
explicacion
string
Optional free-text model explanation. When present, used directly as mensaje.

​
Example request

curl https://api.coffeprice.com/api/predicciones

​
Example response

[
  {
    "fecha": "2024-06-01",
    "precioestimado": 1845000,
    "preciominimo": 1820000,
    "preciomaximo": 1870000,
    "tendencia": "sube",
    "confianza": 83,
    "modelVersion": "fnc_hibrido",
    "fuente": "fnc_hibrido_historial",
    "mensaje": "Se proyecta una subida del precio del cafe en la proxima jornada.",
    "generatedAt": "2024-05-31T22:00:00.000Z",
    "variacionPorcentual": 1.5,
    "estrategiaBase": "naive",
    "holdoutMape": 0.8784,
    "holdoutMae": 19714.29,
    "explicacion": null
  },
  {
    "fecha": "2024-06-02",
    "precioestimado": 1852000,
    "preciominimo": 1825000,
    "preciomaximo": 1878000,
    "tendencia": "sube",
    "confianza": 83,
    "modelVersion": "fnc_hibrido",
    "fuente": "fnc_hibrido_json",
    "mensaje": "Se proyecta una subida del precio del cafe en la proxima jornada.",
    "generatedAt": "2024-06-01T22:00:00.000Z",
    "variacionPorcentual": 0.38,
    "estrategiaBase": "naive",
    "holdoutMape": 0.8784,
    "holdoutMae": 19714.29,
    "explicacion": null
  }
]

​
GET /api/predicciones/ultima

Returns the single most recent prediction available. Reads from predicciones_fnc.json first; falls back to the latest MongoDB document if the file is absent or invalid. Authentication: None — public, rate-limited.

​
Responses

StatusDescription
200Latest prediction object.
404No predictions available from any source.

​
Example request

curl https://api.coffeprice.com/api/predicciones/ultima

​
Example response

{
  "fecha": "2024-06-02",
  "precioestimado": 1852000,
  "preciominimo": 1825000,
  "preciomaximo": 1878000,
  "tendencia": "sube",
  "confianza": 83,
  "modelVersion": "fnc_hibrido",
  "fuente": "fnc_hibrido_json",
  "mensaje": "Se proyecta una subida del precio del cafe en la proxima jornada.",
  "generatedAt": "2024-06-01T22:00:00.000Z",
  "variacionPorcentual": 0.38,
  "estrategiaBase": "naive",
  "holdoutMape": 0.8784,
  "holdoutMae": 19714.29,
  "explicacion": null
}

​
GET /api/predicciones/resumen

Returns the prediction for the next trading day accompanied by a plain-text message in Spanish. This endpoint is designed for dashboard summaries and push notification payloads. Authentication: None — public, rate-limited. The mensaje field is determined by tendencia and confianza:
tendenciaconfianzamensaje
sube≥ 70”Se proyecta una subida del precio del cafe en la proxima jornada.”
sube< 70”Hay senales de una posible subida en el precio del cafe.”
baja≥ 70”Se proyecta una baja del precio del cafe en la proxima jornada.”
baja< 70”Hay senales de una posible baja en el precio del cafe.”
estable≥ 70”Se espera estabilidad en el precio del cafe para la proxima jornada.”
estable< 70”El precio del cafe podria mantenerse estable en la proxima jornada.”
If explicacion is set on the prediction, it overrides the generated message.

​
Responses

StatusDescription
200Prediction summary for the next trading day.
404No prediction available for tomorrow.

​
Example request

curl https://api.coffeprice.com/api/predicciones/resumen

​
Example response

{
  "fecha": "2024-06-02",
  "precioestimado": 1852000,
  "preciominimo": 1825000,
  "preciomaximo": 1878000,
  "tendencia": "sube",
  "confianza": 83,
  "generatedAt": "2024-06-01T22:00:00.000Z",
  "modelVersion": "fnc_hibrido",
  "mensaje": "Se proyecta una subida del precio del cafe en la proxima jornada.",
  "fuente": "fnc_hibrido_json"
}

​
GET /api/predicciones/rango

Returns a slice of the available prediction series covering the last dias entries. Useful for rendering trend charts on producer and buyer dashboards. Authentication: None — public, rate-limited.

​
Query parameters

​
dias
number
required
Number of days to include in the response. Must be one of 7, 15, or 30. Any other value returns a 400 error.

​
Responses

StatusDescription
200Ranged prediction envelope.
400dias is missing or not one of 7, 15, 30.
404No predictions available for the requested range (MongoDB fallback only).

​
Response fields

​
dias
number
The requested range value as provided in the query parameter.
​
total
number
Actual number of prediction records returned. May be less than dias if the history is shorter.
​
generatedAt
string (ISO 8601)
generatedAt value taken from the last prediction in the returned slice.
​
modelVersion
string
modelVersion taken from the last prediction in the returned slice.
​
fuente
string
Source identifier. fnc_hibrido_historial when served from files; mongo when served from the database fallback.
​
modo
string
prediccion_unica when only one result is available; historial_fnc otherwise.
​
mensaje
string
Contextual note about the data. Indicates whether the data comes from real historical runs or a live database projection.
​
predicciones
array
Array of prediction objects. See Prediction object fields above.

​
Example request

curl "https://api.coffeprice.com/api/predicciones/rango?dias=7"

​
Example response

{
  "dias": 7,
  "total": 7,
  "generatedAt": "2024-06-01T22:00:00.000Z",
  "modelVersion": "fnc_hibrido",
  "fuente": "fnc_hibrido_historial",
  "modo": "historial_fnc",
  "mensaje": "Historial real generado por el modelo FNC hibrido. Crece con cada ejecucion diaria del pipeline.",
  "predicciones": [
    {
      "fecha": "2024-05-26",
      "precioestimado": 1830000,
      "preciominimo": 1805000,
      "preciomaximo": 1855000,
      "tendencia": "estable",
      "confianza": 83
    }
  ]
}

​
GET /api/predicciones/dia

Returns the prediction for a date calculated as today (Bogotá timezone) + offset days. Authentication: None — public, rate-limited.

​
Query parameters

​
offset
number
required
Number of days ahead of today to look up. Must be one of 1, 7, 15, or 30. Any other value returns a 400 error.

​
Responses

StatusDescription
200Prediction for the target date, prefixed with the offset value.
400offset is missing or not one of the allowed values.
404No prediction found for the computed date.

​
Example request

curl "https://api.coffeprice.com/api/predicciones/dia?offset=1"

​
Example response

{
  "offset": 1,
  "fecha": "2024-06-02",
  "precioestimado": 1852000,
  "preciominimo": 1825000,
  "preciomaximo": 1878000,
  "tendencia": "sube",
  "confianza": 83,
  "generatedAt": "2024-06-01T22:00:00.000Z",
  "modelVersion": "fnc_hibrido"
}

​
GET /api/predicciones/fecha

Returns the prediction for a specific calendar date provided as a query parameter. Authentication: None — public, rate-limited.

​
Query parameters

​
fecha
string
required
Target date in YYYY-MM-DD format (e.g., 2024-06-02). Returns 400 if omitted or unparseable.

​
Responses

StatusDescription
200Prediction object for the requested date.
400fecha parameter is missing or not a valid date.
404No prediction found for the specified date.

​
Example request

curl "https://api.coffeprice.com/api/predicciones/fecha?fecha=2024-06-02"

​
Example response

{
  "fecha": "2024-06-02",
  "precioestimado": 1852000,
  "preciominimo": 1825000,
  "preciomaximo": 1878000,
  "tendencia": "sube",
  "confianza": 83,
  "generatedAt": "2024-06-01T22:00:00.000Z",
  "modelVersion": "fnc_hibrido"
}

​
GET /api/predicciones/:id

Returns a single prediction document fetched directly from MongoDB by its ObjectId. This endpoint bypasses the file-based data sources. Authentication: None — public.

​
Path parameters

​
id
string
required
MongoDB ObjectId of the prediction document.

​
Responses

StatusDescription
200Prediction document with fecha serialized to YYYY-MM-DD.
404No prediction with that ObjectId exists in MongoDB.

​
Example request

curl https://api.coffeprice.com/api/predicciones/665b2a3c4d5e6f7a8b9c0d1e

​
Example response

{
  "_id": "665b2a3c4d5e6f7a8b9c0d1e",
  "fecha": "2024-06-02",
  "precioestimado": 1852000,
  "preciominimo": 1825000,
  "preciomaximo": 1878000,
  "tendencia": "sube",
  "confianza": 83,
  "generatedAt": "2024-06-01T22:00:00.000Z",
  "modelVersion": "fnc_hibrido",
  "createdAt": "2024-06-01T22:00:01.000Z",
  "updatedAt": "2024-06-01T22:00:01.000Z"
}

​
Admin write endpoints

The following endpoints are restricted to users with the admin role. They operate directly on the MongoDB prediccion collection and do not interact with the file-based data sources.

​
POST /api/predicciones

Creates a new prediction document in MongoDB. Authentication: Required — admin only. Request body fields: fecha (required), precioestimado (required), preciominimo (required), preciomaximo (required), tendencia (optional, default estable), confianza (optional, 0–100). Response: 201 with the created prediction document. 
curl -X POST https://api.coffeprice.com/api/predicciones \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fecha": "2024-06-10",
    "precioestimado": 1860000,
    "preciominimo": 1835000,
    "preciomaximo": 1885000,
    "tendencia": "sube",
    "confianza": 80
  }'

​
PUT /api/predicciones/:id

Updates an existing prediction by ObjectId. Authentication: Required — admin only. Response: 200 with the updated prediction document. 404 if not found. 
curl -X PUT https://api.coffeprice.com/api/predicciones/665b2a3c4d5e6f7a8b9c0d1e \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "confianza": 85
  }'

​
DELETE /api/predicciones/:id

Permanently deletes a prediction by ObjectId. Authentication: Required — admin only. Response: 200 with { "message": "Prediccion eliminada correctamente" }. 404 if not found. 
curl -X DELETE https://api.coffeprice.com/api/predicciones/665b2a3c4d5e6f7a8b9c0d1e \
  -H "Authorization: Bearer <admin-token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us