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

Parameter	Description
`analysis_id`	An existing Beam Analysis ID.

analysis_id

An existing Beam Analysis ID.

Request Headers

Header Value

Header	Value
`Content-Type`	Must be one of the following: `text/csv` `application/x-ndjson` `application/json` `application/x-ldjson` (deprecated) Note: `application/x-ldjson` has been deprecated in favor of `application/x-ndjson`. However the data format is exactly the same (newline delimited JSON). We recommend using `application/x-ndjson`

Content-Type

Must be one of the following:

text/csv
application/x-ndjson
application/json
application/x-ldjson (deprecated)

Note: application/x-ldjson has been deprecated in favor of application/x-ndjson. However the data format is exactly the same (newline delimited JSON). We recommend using application/x-ndjson

Request Body

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

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

Header	Value
`Content-Type`	`text/csv`

Content-Type

text/csv

Column Types:

Column Description

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`

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

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

Header	Value
`Content-Type`	`application/x-ndjson`

Content-Type

application/x-ndjson

JSON Fields:

Field Description

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`

date string required

ISO8601 Date format (YYYY-MM-DD) E.g., 2023-01-01

demand string required

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

Header	Value
`Content-Type`	`application/json`

Content-Type

application/json

JSON Fields:

Field Description

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`

date string required

ISO8601 Date format (YYYY-MM-DD) E.g., 2023-01-01

demand string required

Response

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

An unsuccessful HTTP response code could be returned for several reasons. In addition to an error message, there may also be a code field when applicable. The table below outlines the meaning of several error codes that may be returned.

Code Description

Code	Description
`content_type_invalid`	The `Content-Type` header is unsupported.
`data_validation_failed`	The format of the data uploaded is incorrect.
`json_no_data`	An empty JSON body was uploaded.
`json_invalid_format`	The uploaded JSON is formatted incorrectly. Please ensure JSON data is correctly UTF-8 encoded and that there are no invalid escape sequences.
`ndjson_no_data`	An empty NDJSON body was uploaded.
`ndjson_invalid_format`	The NDJSON body is formatted incorrectly. Please ensure NDJSON data is correctly UTF-8 encoded and that there are no invalid escape sequences.
`csv_invalid_row`	The uploaded CSV has an invalid row.
`csv_invalid_header`	The uploaded CSV headers are incorrect. Please use `date,demand`.
`csv_no_data`	The uploaded CSV is empty or only has headers set.
`csv_invalid_format`	The uploaded CSV is formatted incorrectly. Please ensure CSV data is correctly UTF-8 encoded and that there are no invalid escape sequences.
`start_date_invalid`	The earliest date in the uploaded demand data is before `2017-01-01`.
`end_date_invalid`	The latest date in the uploaded demand data is more than 1 year into the future.
`duplicate_rows`	The uploaded demand data contains duplicate dates. Please remove all duplicates before uploading.
`no_data`	There is no demand data.
`weekly_demand_date_check_failed`	The weekly demand dates do not start on the same weekday.
`below_minimum_threshold`	There are not enough data points in the uploaded demand data.
`constant_demand_column`	The demand column is constant.
`exceeding_missing_data_percentage`	There are too many missing demand values.
`exceeding_consecutive_missing_data_volume`	There are too many consecutive missing demand values.
`high_variance_difference_rate`	The variance of the uploaded demand data is too large to be processed.
`unexpected_error`	An unexpected error occurred.

content_type_invalid

The Content-Type header is unsupported.

data_validation_failed

The format of the data uploaded is incorrect.

json_no_data

An empty JSON body was uploaded.

json_invalid_format

The uploaded JSON is formatted incorrectly. Please ensure JSON data is correctly UTF-8 encoded and that there are no invalid escape sequences.

ndjson_no_data

An empty NDJSON body was uploaded.

ndjson_invalid_format

The NDJSON body is formatted incorrectly. Please ensure NDJSON data is correctly UTF-8 encoded and that there are no invalid escape sequences.

csv_invalid_row

The uploaded CSV has an invalid row.

csv_invalid_header

The uploaded CSV headers are incorrect. Please use date,demand.

csv_no_data

The uploaded CSV is empty or only has headers set.

csv_invalid_format

The uploaded CSV is formatted incorrectly. Please ensure CSV data is correctly UTF-8 encoded and that there are no invalid escape sequences.

start_date_invalid

The earliest date in the uploaded demand data is before 2017-01-01.

end_date_invalid

The latest date in the uploaded demand data is more than 1 year into the future.

duplicate_rows

The uploaded demand data contains duplicate dates. Please remove all duplicates before uploading.

no_data

There is no demand data.

weekly_demand_date_check_failed

The weekly demand dates do not start on the same weekday.

below_minimum_threshold

There are not enough data points in the uploaded demand data.

constant_demand_column

The demand column is constant.

exceeding_missing_data_percentage

There are too many missing demand values.

exceeding_consecutive_missing_data_volume

There are too many consecutive missing demand values.

high_variance_difference_rate

The variance of the uploaded demand data is too large to be processed.

unexpected_error

An unexpected error occurred.

Examples

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

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

PreviousCreate an Analysis NextSearch Analyses

Last updated 1 month ago