Unplugg API

This API currently provides forecasting for timeseries data that you can test below. You can use it to forecast energy comsuption, temperature, or any other timeseries data which has some seasonality effect. To know more about this project visit unplu.gg. If you have feedback or want to know more, get in touch with us at [email protected].


You can try it out online or use the API directly.


Request your API key here:



Note: Access is limited to valid access tokens only.

Try it out

Timeseries payload:


Forecasting timeseries:

API Basic Usage


To start using the API you’ll first need to request a token:



Note: Access is limited to valid access tokens only.

The API is available at https://api.unplu.gg/. With Unplugg’s API you can request a forecast based on a provided timeseries. To do this you have to make a POST to endpoint /forecast with headers and JSON payloads that will be described in the following sections.


Headers

To authorize your requests, add the following headers:

                    
                       x-access-token: <YOUR-ACCESS-TOKEN>
                       Content-Type: application/json
                     
                  

Payload

Payloads sent to the API will be a Json structure with three objects:

  • Time Series data (data):

    Time series data will be a list of values with associated timestamps.

    Parameter Example Description
    timestamp 1466640000 Timestamps in Unix time format (seconds)
    value 0.27589941523037853 Integer or float value for specified timestamp
  • Link for webhook callback (callback)

    The link will be used to return forecasting result to the webhook once job is finished.

    Parameter Example Description
    callback http://your.domain/yourcallback Link to which the job payload will be sent
  • [Optional] Forecasting end date (forecast_to)

    The time series will be forecasted up to this date.

    Parameter Example Description
    forecast_to 1458136800 Timestamps in Unix time format (seconds)

Payload example:

                           
                           {
                              "data": [
                                 {"timestamp":1466640000,"value":0.27589941523037853},
                                 {"timestamp":1466640900,"value":0.4059699097648263},
                                 {...} ,
                                 {"timestamp":1466641800,"value":0.8376112426631153}
                              ],
                              "forecast_to":1458136800,
                              "callback": "http://your.domain/yourcallback"
                           }
                           
                        

Response

If the payload is well-behaved and sent for processing you’ll receive a job_id in the body that uniquely identifies the processing job for your data. If the time series in the payload is not equally spaced, a resampling will be applied in order to have each value separated from the next by the same amount as the first two values in the given time series. Malformed payloads will return a 422: UNPROCESSABLE ENTITY status as well as a message that should help in locating the error.


Once the job finishes your webhook will be sent a Json structure with:

  • Forecasting data will be will a list of values with associated timestamps inside an object called forecast, similarly to the historic data (see Payload). The forecasted time series will be executed until the given date in parameter forecast_to or, in case it is not provided, the forecasted array will have the length of 1/8 of the number of points in the time series provided in the payload.

  • Object job_id containing the job ID you’ve received earlier, associated with this specific forecasting request.

Webhook content example:


                        {
                           "forecast": [
                              {"timestamp":1466640000,"value":0.27589941523037853},
                              {"timestamp":1466640900,"value":0.4059699097648263},
                              {...} ,
                              {"timestamp":1466641800,"value":0.8376112426631153}
                           ],
                           "job_id": "y0urJ0b1d"
                        }
                     

Example usage and response

  • Request (application/json)

  • Body

  • Headers

    x-access-token: [YOUR-ACCESS-TOKEN]
  • Response 200 (application/json)

    
                               [
                                  {
                                     "forecast": [
                                        {"timestamp":1458129600,"value":58.6912515906},
                                        {"timestamp":1458133200,"value":30.5359068808},
                                        {"timestamp":1458136800,"value":36.7927021395},
                                        {"timestamp":1458140400,"value":48.7672586419}
                                     ],
                                     "job_id": "y0urJ0b1d"
                                  }
                               ]
                            

How will the temperature be like in the next days?


Let’s say we have the historic data on the daily mean temperature (this dataset was obtained from Wunderground) of the previous two months (November and December) and that we want to know what will the temperature be like in the first days of January.


Our payload would be:


And the forecast would be:




alt text

What will be the electricity consumption in the next hours?


With power consumption measured hourly with a smartmeter, we may gather hourly instant consumption data to forecast the next hours. Here we have a dataset with a day and a half of hourly instant consumption data.


Our payload would be:


And the forecast would be:




alt text

What will the ISP traffic be like in the next minutes?


For this example we have a dataset with internet traffic data (in bits) from an ISP (Origin: DataMarket). The original timeseries was resampled to show values in 10 minute intervals intead if the original 5 minutes.


Our payload would be:


And the forecast would be:




alt text