NAV Navbar

Forecast as a service

javascript shell
  • Introduction
  • Authentication
  • Forecast
  • Errors
  • Introduction

    Welcome to the meqem API documentation! You can use our API to easily forecast data to improve your business.

    We have an official API wrapper in node.js! You can view code examples in the dark area to the right. You can also integrate via a simple HTTP library in your language by following this documentation.

    Base endpoint: https://api.meqem.com

    Current API version: v0

    Authentication

    const Meqem = require('meqem');
    
    let meqem = new Meqem({'apiKey': 'your-api-key-here'});
    
    curl -H "X-API-Key: your-api-key-here"
    

    meqem expects for the API key to be included in all API requests to the server in a header that looks like the following X-API-Key:

    X-API-Key: your-api-key-here

    You can find your API key in your dashboard.

    Forecast

    Create a new forecast

    const Meqem = require('meqem');
    
    let meqem = new Meqem({'apiKey': 'your-api-key-here'});
    let filePath = '/home/user/my_history_data.json'
    let getNext = 6 // get next 6 datapoints
    let frequency = 'day' // my_history_data.json has daily datapoints
    meqem.forecast.new({history_data: filePath, get_next: getNext, frequency: frequency}).then(...).catch(...)
    
    curl -X POST -H "X-API-Key: your-api-key-here" \
    -F get_next=6 \
    -F frequency="day" \
    -F history_data=@/home/user/my_history_data.json \
    https://api.meqem.com/v0/forecast
    

    Request a new forecast. This is an asynchronous process, this means that when the status of the forecast is set to done the forecast will be available.

    HTTP Request

    POST https://api.meqem.com/v0/forecast

    History data file example

    [
      {
        "date": "2018-12-10",
        "my_custom_field": 10,
        "my_optional_second_field": 2912,
        "my_option_third_and_last_field": 1.3972
      },
      {
        "date": "2018-12-11",
        "my_custom_field": 8,
        "my_optional_second_field": 398.93,
        "my_option_third_and_last_field": 0.2972
      },
      {
        "date": "2018-12-12",
        "my_custom_field": 7,
        "my_optional_second_field": 834.34,
        "my_option_third_and_last_field": 3.43
      }
      ...
    ]
    

    When creating a new forecast you must provide the JSON history data. Content type must be set to multipart/form-data.

    The history data must be an array of JSON object with a mandatory date formatted in ISO8601 or as YYYY-MM-DD (e.g. 2018-12-31), objects must be indexed in a chronological order, data points interval can be seconds, minutes, hours, months, years and non consistent. We automatically calculate the interval, if you do not have consistent data or if you already know the data interval you can directly set the frequency.

    You can have a maximum of 3 fields and a minimum of 1 to forecast, but all must be numbers (integer, float, positive or negative). Fields in JSON objects must be consistent (each JSON object should have the same fields/shape).

    Form fields

    Parameter Type Description
    history_data JSON file (Array of JSON objects) File stream of your JSON data
    get_next Integer Set how many datapoints meqem needs to forecast (default: 5)
    frequency String The type of granularity of your history data, must be second - minute - hour - day - month - year - it will be automatically calculated if not provided, we suggest to set this if you know the history data.

    200 Response example

    {
      "success": true,
      "forecast_id": "new-string-id"
    }
    

    JSON Response fields

    Parameter Type Description
    success Boolean If the creation was successful
    forecast_id String Id for this request (only if success: true), use this to check the status and to download the forecast

    Example

    With data history: [{"date": "2018-12-10", "stock_unit": 2023, "price": 1.23, "n_people_store": 293},...] we will generate a forecast for the get_next datapoints that will include stock_unit - price - n_people_store

    Get a Specific Forecast (info only)

    const Meqem = require('meqem');
    
    let meqem = new Meqem({'apiKey': 'your-api-key-here'});
    meqem.forecast.getInfo('forecast-id').then(...).catch(...)
    
    curl -H "X-API-Key: your-api-key-here" \
    https://api.meqem.com/v0/forecast/forecast-id
    

    This endpoint retrieves a specific forecast info. This can be useful if you need to check the status, so when it's done you can access the forecast json via download.

    HTTP Request

    GET https://api.meqem.com/v0/forecast/<forecast_id>

    URL Parameters

    Parameter Type Description
    forecast_id String The ID of the forecast to retrieve (generated on POST)

    200 Response example

    {
      "forecast_id": "forecast_id",
      "get_next": 10,
      "status": "done",
      "frequency": "day",
      "_created": "2018-06-22T17:06:02.346Z",
      "_updated": "2018-06-22T17:06:04.106Z"
    }
    

    JSON Response fields

    Parameter Type Description
    forecast_id String Forecast id
    get_next Integer get_next provided on creation
    status String Current status for this forecast, it can be failed - processing - done
    frequency String frequency provided on creation or calculated by us (e.g. 'day')
    _created String Forecast creation in ISO8601 date string
    _updated String Last update of the forecast in ISO8601 date string

    List all (info only)

    const Meqem = require('meqem');
    
    let meqem = new Meqem({'apiKey': 'your-api-key-here'});
    meqem.forecast.listAll().then(...).catch(...)
    
    curl -H "X-API-Key: your-api-key-here" \
    https://api.meqem.com/v0/forecast
    

    This endpoint lists all forecasts that you have created before.

    HTTP Request

    GET https://api.meqem.com/v0/forecast

    URL Parameters

    No parameters are required for this endpoint.

    200 Response example

    [
      {
        "forecast_id": "string-random-id",
        "get_next": 10,
        "status": "done",
        "frequency": "day",
        "_created": "2018-06-22T17:06:02.346Z",
        "_updated": "2018-06-22T17:06:04.106Z"
      },
      ...
    ]
    

    JSON Response

    Array of JSON objects, the inner JSON objects have the same structure of the get by specific forecast id

    Get/Download forecast JSON

    const Meqem = require('meqem');
    
    let meqem = new Meqem({'apiKey': 'your-api-key-here'});
    meqem.forecast.getJSON('forecast-id').then(...).catch(...)
    
    curl -H "X-API-Key: your-api-key-here" \
    https://api.meqem.com/v0/forecast/forecast-id/json
    

    This endpoint returns the forecast data in JSON format (array of json). Before calling this endpoint you need to make sure that the forecast has done by checking if the status parameter is set to done via a GET request.

    HTTP Request

    GET https://api.meqem.com/v0/forecast/<forecast_id>/json

    URL Parameters

    Parameter Description
    forecast_id The ID of the forecast to retrieve (generated on POST)

    200 Response (forecast JSON example)

    [
      {
        "date": "2018-12-13",
        "stock_unit": 293
      },
      {
        "date": "2018-12-14",
        "stock_unit": 194.94
      },
      {
        "date": "2018-12-15",
        "stock_unit": 391.39
      },
      ...
    ]
    

    JSON Response fields

    Array of JSON objects, the fields inside json objects will match the same structure of the history data.

    Errors

    If an error occurs during a request meqem will reply with an error JSON object like the following:

    {
        "error": {
            "message": "error reason",
            "code": 1234
        }
    }
    

    JSON Response fields

    Parameter Type Description
    error JSON Object Error object
    error.message String Reason of the error
    error.code Integer Number mapping of the error (see below for error codes)
    error.plan Boolean This will be present and set to true only if the error is related to your plan limit
    Error Code Meaning
    1000 Internal server error -- Unexpected error from meqem during the processing of your request
    1001 Missing or invalid X-API-Key provided -- X-API-Key not found or invalid
    1050 Forecast not found -- Wrong forecast_id or if you are calling the download route it means that the status is not done (forecast file is not ready), try again later
    1100 Mandatory file missing -- History data missing/not found
    1101 Invalid or no date provided -- date field in history data is mandatory (json objects), it was not found
    1102 Invalid get_next value -- get_next provided is not a positive integer or your plan doesn't allow it
    1103 Found invalid fields in datapoints (must be numbers) -- Found one or multiple non-number fields
    1104 Inconsistent fields found, field structure should be the same across all objects
    1105 History data exceeds plan limit (upgrade plan to increase limit) -- History data length not allowed in your current plan
    1106 No fields found -- No fields found in your history data
    1107 Forecast monthly limit reached (upgrade to increase limit)
    1108 Found one or multiple invalid dates, date field must be YYYY-MM-DD or ISO8601 string
    1109 Invalid frequency provided, must be one of: second - minute - hour - day - month - year