Share via

Business Assist Forecast API User Guide

  • Article

The Forecast API uses a set of forecasting models to predict case and conversation volumes based on historical data.

To use the API, first set up an Azure App Registration to authenticate your requests.

Microsoft is committed to storing and processing all personal data of commercial and public sector customers within their geo boundary. The offer applies to all core cloud services, which were identified as Azure, Microsoft 365, and Dynamics 365. To meet this commitment, European customers should use the European endpoint, and all other global customers should use the global endpoint.

Submit Forecast Job

A forecast job uses your input to create a forecast for a specific time frame.

Global endpoint: Send a PUT request with the data in the request body to:

https://businessassist.microsoft.com/api/beta/forecast

site_url: businessassist.microsoft.com
version: beta

European endpoint: Send a PUT request with the data in the request body to:

https://eu.businessassist.microsoft.com/api/beta/forecast

site_url: eu.businessassist.microsoft.com
version: beta

See CreateForecast API reference for request syntax.

Historical data can be formatted as a JSON string in the request body or be attached as a CSV file. You can also add holidays and special dates as a JSON string or in a CSV file.

Historical data

Field Name Definition Input method JSON string Input method CSV file
name Give the forecasting job a familiar name ✔ ✔
dataFileName Name of the file containing your historical data. ✔ ✘
inputDataJson JSON-formatted version of the historical data. ✘ ✔
dateTimeColumnName Column header for the column containing data and time information. ✘ ✔
volumeColumnName Column header for the column containing volume data. ✘ ✔
adjustmentColumnNames Column names of adjustments to the time series forecasting. ✘ ✔
predictedAdjustmentDataFileName A data frame with future date (or datetime) column and the corresponding adjustmentColumnNames columns. ✘ Only needed if adjustmentColumnNames is provided.
seasonality Divide forecasts by time periods for comparison. Select at most two seasonality from (hourly, daily, weekly, monthly, quarterly, yearly) See Seasonality Codes for valid values. ✔ ✔
endDateTime End date for the forecasting. It can be yyyymmdd, mm/dd/yyyy, or other widely known date format. ✔ ✔

Special Date Data

Field Name Definition Input method JSON string Input method CSV file
specialDateFileName File location of the file containing the special days' date and names, for both the past and the future. ✘ ✔
specialDateAdjustmentFileName File location of the file that includes the future date which needs to be adjusted. ✘ ✔
specialDataDataJson JSON-formatted string of special date data. ✔ ✘
specialDateAdjustmentDataJson JSON-formatted string of special date adjustment data. ✔ ✘
specialDateColumnName Name of the column in the specialDateFileName or specialDataDataJson listing dates for special days and holidays. ✔ ✔
specialDateEventColumnName Column header for the names of special dates and holidays. ✔ ✔
specialDateAdjustmentColumnName Column header for the adjustments to make to special dates and holidays. ✔ ✔

Generally, you don't need to specify fixed date holidays (such as Christmas) or fixed weekday holiday (such as Labor Day) in your region, or any holiday in a G8 country, because the algorithm will learn those days from historical data.

Examples of Input Data Methods

Input data can be sent in the form of a JSON-formatted string, or attached as a JSON-formatted file. Send an code from this enumerated list to specify the format.

Format Code
JSON string 0
CSV file 1

Input data as JSON string

For a small data set or a test run, include the historical data as a JSON-formatted string, as the value for inputDataJson.

Append the code for a JSON string to the URL:

Global endpoint

POST https://businessassist.microsoft.com/api/beta/forecast?inputDataMethod=0

European endpoint

POST https://eu.businessassist.microsoft.com/api/beta/forecast?inputDataMethod=0
Example Request, data as JSON string
{
  "name": "forecast_sample",
    "inputDataJson": " [{\"Date\":\"2015-01-01\",\"Ticket\":\"195\"},{\"Date\":\"2015-01-02\",\"Ticket\":\"774\"}]",
    "dateTimeColumnName": "<Date column name from the above inputDataJson field, for example, Date>",
    "volumeColumnName": "<Volume column name from the above inputDataJson field, for example, Ticket>",
    "seasonality": 2,
    "endDateTime": "<end date MM/DD/YYYY>"
}
Example Request, data attached as a CSV file

For larger or more complex data sets, attach the historical data to the request as a CSV-formatted file.

Append the code for a JSON file to the URL:

Global endpoint

POST https://businessassist.microsoft.com/api/beta/forecast?inputDataMethod=1

European endpoint

POST https://eu.businessassist.microsoft.com/api/beta/forecast?inputDataMethod=1
CSV file sample
Date Count
9/1/2021 2
9/2/2021 1
9/3/2021 2
9/4/2021 1
... ...
Example request, with CSV attachment
 {
  "inputDataFileName": "historical_data.csv",
  "dateTimeColumnName": "Date",
  "volumeColumnName": "Ticket",
  "seasonality": "2",
  "endDateTime": "9/30/2021>"
}
Example request, with JSON string for special dates
{
  "name": "forecast_sample_3",
  "inputDataJson": " [{'Date':'2015-01-01','Ticket':'195'},{'Date':'2015-01-02','Ticket':'774'}]",
  "dateTimeColumnName": "Date",
  "volumeColumnName": "Ticket",
  "specialDateDataJson":" [{'Date':'2021-10-28','Name':'IgniteDay1'},{'Date':'2022-06-02','Name':'IgniteDay1'}]",
  "specialDateAdjustmentDataJson":" [{'Date':'2015-01-01','Ratio':'-0.3'},{'Date':'2015-01-02','Ratio ':'0.2'}]",
  "specialDateColumnName":" Date",
  "specialDateEventColumnName":"Name",
  "specialDateAdjustmentColumnName":"Ratio",
  "seasonality": 2,
  "endDateTime": "07/30/2021"
}

Get back a 202 with an OperationId. Use this OperationId to get the status and the results of this job.

CreateForecast job sample success response

{
  "operationId": "000001",
  "name": "forecast_sample_3",
  "status": 0,
  "diagnostics": "string"
}
Field Definition
operationId Job ID, use to get status and results.
name Job name submitted with request.
status Status code of forecast job. See Status codes.
diagnostics Errors or warnings generated during job creation.

Create forecast job success response code

Code Explanation
202 The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.

Submit forecast job error response

Error Code Cause
400 Input Data is null.
403 Missing or incorrect permissions.
500 Submit request failed.

You can influence the machine learning model to identify trends between days, weeks or months by setting a seasonality code in the request body.

Seasonality codes

Code Time period
0 No seasonality (Default)
1 Daily seasonality trend observed in input data.
2 Weekly seasonality trend observed in input data.
4 Monthly seasonality trend observed in input data.
8 Quarterly seasonality trend observed in input data.
16 Yearly seasonality trend observed in input data.

You can get multiple trends by combining the codes. For example, to get daily and weekly trends, set the code to 3 (1 + 2).

Get Job Status

Use the OperationId to send a GET request.

Global endpoint

https://businessassist.microsoft.com/api/beta/forecast/{operationid}

European endpoint

https://eu.businessassist.microsoft.com/api/beta/forecast/{operationid}

See ForecastStatus API reference for request syntax.

Example get job status success response

The response will contain a numerical Status property.

{
  "operationId": "00000001",
  "name": "forecast_sample_3",
  "status": 2,
  "diagnostics": "string"
}
Field Definition
operationId Job ID
name Job name provided.
status Code showing status of forecast job.
diagnostics Errors or warnings generated during job creation.

Job Status Codes

Code Job Status
0 Not started
1 In progress
2 Completed

Get Forecast success response code

Code Explanation
202 The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.

Sample Get forecast job status error response

Error Code Cause
400 Operation id null or empty.
403 Missing permission.
500 Get status failed.

Get Job Results

When the Status of a Get Status request returns 2, the job is completed and ready for download.

Global endpoint

https://businessassist.microsoft.com/api/beta/forecast/({operationid}/download

European endpoint

https://eu.businessassist.microsoft.com/api/beta/forecast/({operationid}/download

See ForecastDownload API reference for request syntax.

Sample Get forecast job results success response

{
  "predictions": [
    {
    "date": "2022-08-08T16:07:19.329Z",
    "forecast": 0.0,
    "low": 0.0,
    "high": 0.0
    }
  ]
}
Field Definition
date The date the forecast job was created.
forecast Forecast of for the defined time period.
low Low end of the forecast range predicted.
high High end of the forecast range predicted.

Get forecast job success response code

Code Explanation
200 Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request the response will contain an entity describing or containing the result of the action.

Get forecast job results error response

Error Code Cause
400 The operationId is null or empty.
403 Missing or incorrect permissions.
500 Get results failed.

First time user of Business Assist Forecast API?

Find resources for getting the most out of the Business Assist Forecast APIs:

  • Overview: High-level introduction to Business Assist Forecast API.
  • Core concepts: Learn about the key concepts and the process of importing datasets and generating forecasts.
  • API reference: Familiarize yourself with the Business Assist Forecast API actions and data types.