Upload Demand Data

Upload your demand data as CSV, line-delimited JSON or JSON.

Beam Analyses support daily or weekly demand data. The type of data is detected automatically on upload.

For daily demand the minimum amount of data required is 6 months, or 180 data points. Beam can impute up to 20% of missing values, provided that the minimum data requirements are satisfied and there are no more than 7 consecutive days missing.

For weekly demand the minimum amount of data required is 2 years, or 104 data points. Beam can impute up to 10% of missing values, provided that the minimum data requirements are satisfied and there are no more than 5 consecutive weeks missing. All weekly data points must align with the start of the week and occur on the same weekday.

All data points need to be between 2017-01-01 and one year into the future from today's date (today + 365 days).

Uploading data replaces existing data for the same date. It's not currently possible to remove data for a particular date. The idea with this endpoint is that you're continuously adding new demand data over time.

The data can be uploaded in chunks, but the analysis data must remain valid at all times. If a newly uploaded chunk renders the analysis data invalid (for example, by introducing a large gap between data points), the chunk will be rejected, and the previously stored demand data will be preserved.

Request

HTTP Request

POST https://api.predicthq.com/v1/beam/analyses//sink

Path Parameters

Parameter	Description
analysis_id	An existing Beam Analysis ID.

Request Headers

Header	Value
Content-Type	Must be one of the following: text/csv application/x-ldjson application/json

Request Body

You can upload the demand data for your analysis in any of the following formats:

CSV

The request body should contain comma-separated values that represent multiple data points with the column names (in lowercase) as date and demand, demonstrated by the example below:

date,demand
2023-01-01,12.235
2023-01-02,11.4
2023-01-03,12.14

The following request headers must be set:

Header	Value
Content-Type	text/csv

Column Types:

Column	Description
date string required	ISO8601 Date format (YYYY-MM-DD) E.g., 2023-01-01
demand number required	Number value (float or integer, must be a positive number). Demand will typically be the demand you use in your demand forecast if you are forecasting. For example, it could be units sold, room bookings, or number of staff rostered on per day or any other unit. E.g., 12.235

Line-delimited JSON

The request body should consist of line-delimited JSON objects, each representing a distinct data point. Ensure that the fields within these objects are named date and demand (lowercase). The format should follow the example given below:

{"date": "2023-01-01", "demand": 12.235}
{"date": "2023-01-02", "demand": 11.4}
{"date": "2023-01-03", "demand": 12.14}

The following request headers must be set:

Header	Value
Content-Type	application/x-ldjson

JSON Fields:

Field	Description
date string required	ISO8601 Date format (YYYY-MM-DD) E.g., 2023-01-01
demand string required	Number value (float or integer, must be a positive number). Demand will typically be the demand you use in your demand forecast if you are forecasting. For example, it could be units sold, room bookings, or number of staff rostered on per day or any other unit. E.g., 12.235

JSON

Note that this format is only suitable for appending data to an already valid data set.

The request body should contain a JSON object that represents a single data point. For each request, only one data point is permitted. Ensure that the fields are named date and demand (lowercase), as demonstrated in the example below:

{
  "date": "2023-01-01",
  "demand": 12.235
}

The following request headers must be set:

Header	Value
Content-Type	application/json

JSON Fields:

Field	Description
date string required	ISO8601 Date format (YYYY-MM-DD) E.g., 2023-01-01
demand string required	Number value (float or integer, must be a positive number). Demand will typically be the demand you use in your demand forecast if you are forecasting. For example, it could be units sold, room bookings, or number of staff rostered on per day or any other unit. E.g., 12.235

Response

If successful, the HTTP response code will be 202 Accepted.

Examples

curl

curl -X POST https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID/sink \
     -H "Content-Type: text/csv" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data @data.csv

python

import requests

response = requests.post(
    url="https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID/sink",
    headers={
        "Authorization": "Bearer $ACCESS_TOKEN",
        "Content-Type": "text/csv"
    },
    data=open("data.csv")
)

print(response.json())

Guides

Below are some guides relevant to this API:

• Beam Guides