BerriAI / trend-api

Anomaly detection and forecasting API

Trend

An anomaly detection and forecasting API. Get started quickly with state-of-the-art algorithms.

Installation

Docker

An image is available on Docker Hub. Run:

docker run -ti -p=8000:8000 ankane/trend

Non-Docker

Download the latest code

git clone https://github.com/ankane/trend-api.git
cd trend-api

Install Jetpack and run:

Rscript -e 'jetpack::install()'

And start the server

Rscript server.R

Anomaly Detection

Detect anomalies in a time series.

• Works with dates and times
• Accounts for seasonality and trend
• Robust to missing values

The current version uses STL with multiple seasonal components for decomposition.

POST /anomalies HTTP/1.1
Host: trendapi.org
Content-Type: application/json

{
  "series": {
    "2023-01-01": 150,
    "2023-01-02": 125,
    "2023-01-03": 133
  }
}

Returns JSON structured like this:

{
  "anomalies": [
    "2023-01-10",
    "2023-01-13"
  ]
}

Forecasting

Get future predictions for a time series.

• Works with dates and times
• Accounts for seasonality and trend
• Robust to missing values
• No need to remove outliers beforehand

The current version uses TBATS for predictions.

POST /forecast HTTP/1.1
Host: trendapi.org
Content-Type: application/json

{
  "series": {
    "2023-01-01": 150,
    "2023-01-02": 125,
    "2023-01-03": 133
  },
  "count": 3
}

Returns JSON structured like this:

{
  "forecast": {
    "2023-03-01": 137.5,
    "2023-03-02": 122.9,
    "2023-03-03": 144.1
  }
}

If you get a flat or linear forecast, this is expected. It means no seasonality is detected in the series.

Correlation (Experimental)

Get the correlation between two time series.

The current version uses normalized cross correlation.

POST /correlation HTTP/1.1
Host: trendapi.org
Content-Type: application/json

{
  "series": {
    "2023-01-01": 150,
    "2023-01-02": 125,
    "2023-01-03": 133
  },
  "series2": {
    "2023-01-01": 150,
    "2023-01-02": 176,
    "2023-01-03": 145
  }
}

Returns JSON structured like this:

{
  "correlation": 0.95
}

Errors

The API uses HTTP status codes to indicate errors.

Code	Description
400	There’s an issue with the request parameters
500	There’s an issue with the server

The body will contain details about the specific error.

{
  "error": "Missing parameter: series"
}

Clients

A client library is available for Ruby.

Here’s an example with jQuery:

var series = {}, i, date, data;
for (i = 1; i < 30; i++) {
  date = new Date(2018, 3, i);
  series[date.toISOString()] = date.getDay();
}
data = {series: series};

$.post("https://trendapi.org/forecast", data, function(resp) {
  console.log(resp);
}, "json");

Credits

A special thanks to Rob J Hyndman for his incredible work on forecasting. Learn more about the topic from his free online book.

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features