Upload Demand Data

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

Upload Demand Data

post

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.

Authorizations

BearerAuth

AuthorizationstringRequired

Enter your PredictHQ API key. The Bearer prefix is added automatically.

When calling the API directly, send: Authorization: Bearer <YOUR_API_KEY> as documented at https://docs.predicthq.com/api/overview/authenticating

Path parameters

analysis_idstringRequired

An existing Beam Analysis ID.

Header parameters

Content-Typestring · enumRequired

Content type of the uploaded payload.

• text/csv — CSV format with date and demand columns.
• application/x-ndjson — newline-delimited JSON, one {"date": ..., "demand": ...} object per line.
• application/json — a JSON array of {"date": ..., "demand": ...} objects.
• application/x-ldjson — deprecated, please use application/x-ndjson.

Example: text/csvPossible values:

Body

application/jsonapplication/x-ldjsonapplication/x-ndjsontext/csv

A single demand data point consisting of a date and a positive numeric demand value.

datestring · dateRequired

ISO8601 Date format (YYYY-MM-DD)

Example: 2023-01-01

demandnumberRequired

Number value (float or integer, must be a positive number).

Example: 12.235

Responses

202

Successful Response

No content

400

Bad Request

application/json

401

Unauthorized

application/json

403

Bearer token scope insufficient

application/json

404

Analysis not found

application/json

409

Data conflict

application/json

post/v1/beam/analyses/{analysis_id}/sink

HTTPcURLJavaScriptPython

POST /v1/beam/analyses/{analysis_id}/sink HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37

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

application/jsonapplication/x-ldjsonapplication/x-ndjsontext/csv

No content

Error Codes

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
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

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

python

OpenAPI Spec

The OpenAPI spec for Beam API can be found here.

Guides

Below are some guides relevant to this API:

• Beam Guides