Beam API
Beam is a decomposition and correlation engine that can be used to identify the historical impact of events on your own demand indicators (revenue, units sold, guest count, etc.)
The API reference guide below details the Beam endpoints used in creating, reading, updating and deleting analyses, as well as uploading, decomposing and correlating your own demand data via an existing analysis.
Create Analysis
Before you can begin uploading your demand data, you must first define an analysis by its name, location and event rank filters you want to look for.
Use the following parameters described below in the body of your request to create Beam analyses.
Body Parameters
Parameter | Description |
---|---|
name string required |
String representing the name of an analysis. E.g. My Location Analysis 1 |
location.* object required |
This should be the location of your data. We will use this location for our time series modelling and to correlate with events in the specified area.{"geopoint": {"lat": "-36.849761", "lon": "174.7628903"}, "radius": 1.2, "unit": "km"} We recommend using the Suggested Radius API to find a suitable radius for your location/industry. Possible radius units: mi - Milesm - Meterskm - Kilometers |
rank.* object required |
Specifies which rank type to use when calculating event impacts and anomaly detection. If you're unsure which to use we recommend using phq .{"type": "phq"} Possible rank type values: phq - PHQ Rankaviation - Aviation RankOptionally, specify the minimum rank level to use when calculating event impacts. E.g. {"type": "phq", "levels": {"phq": {"min": 51}}} |
tz string optional |
Time zone of the location in TZ Database format. E.g. Pacific/Auckland |
Action
POST /v1/beam/analyses
Example
curl -X POST https://api.predicthq.com/v1/beam/analyses \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
--data @<(cat <<EOF
{
"name": "Analysis 1",
"location": {
"geopoint": {
"lat": "-36.849761",
"lon": "174.7628903"
},
"radius": 1.2,
"unit": "km"
},
"rank": {
"type": "phq"
},
"tz": "UTC"
}
EOF
)
Response
{
"analysis_id": "2iJcUzm3-ZE"
}
Upload Demand Data to an Analysis
Use the following parameters described below in the body of your request to upload demand data for Beam analyses.
Beam requires a specific json
, csv
or x-ldjson
format, otherwise the response will return an error. Check the respective reference fields below for examples of the correct formats.
Body Parameters
Content Type | Description |
---|---|
application/json | The request body should contain a JSON object representing a single data point, only a single data point can be uploaded per request. E.g. {"date": "2016-01-01", "demand": 12.235} |
application/x-ldjson | The request body should contain a list JSON objects representing multiple data points, one data point per line. E.g. {"date": "2016-01-01", "demand": 12.235} {"date": "2016-01-02", "demand": 12} {"date": "2016-01-03", "demand": "2"} |
text/csv | The request body should contain comma separated values representing multiple data points. E.g. date,demand 2017-01-01,18 2017-01-02,2004 2017-01-03,2011 |
Search Analysis
Use the following parameters described below to search for Beam analyses.
Query Parameters
Parameter | Description |
---|---|
status string optional |
Comma separated list (<status1>,<status2> ) used to filter Beam analyses by their status.Possible values:
?status=draft,active |
readiness_status string optional |
Comma separated list (<readiness_status1>,<readiness_status2> ) used to filter Beam analyses by their readiness status.Possible values:
?status=pending,ready |
sort string optional |
Comma separated list (<sort1>,<sort2> ) used to sort Beam analyses.Possible values:
?sort=name,created |
limit number optional |
Limits the length of the Beam analyses list returned. The default limit is 10 .E.g. ?limit=20 |
offset number optional |
Specifies starting offset of the Beam analyses list returned. The default offset is 0 .E.g. ?offset=3 |
Action
GET /v1/beam/analyses
Example
curl -X GET https://api.predicthq.com/v1/beam/analyses?status=draft&sort=updated \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
"count": 1,
"analyses": [
{
"name": "Analysis 1",
"location": {
"geopoint": {
"lat": "-36.85088270000001",
"lon": "174.7644881"
},
"radius": 10,
"unit": "km"
},
"rank": {
"type": "phq",
"levels": {
"phq": {
"min": 51
}
}
},
"status": "draft",
"create_dt": "2021-08-19T23:46:49.172401+00:00",
"update_dt": "2021-08-20T00:20:19.770461+00:00",
"user_id": "user_id",
"access_type": "full",
"processed_dt": "2021-08-19T23:50:53.456047+00:00",
"readiness_status": "ready",
"readiness_checks": {
"date_range": {
"start": "2021-01-01",
"end": "2021-12-31"
},
"validation_response": {
"missing_data_percentage": 0.0,
"consecutive_nan": 0
}
},
"tz": "Pacific/Auckland",
"analysis_id": "analysis_id"
}
]
}
Get Analysis
Retrieve an existing Beam analysis by making a GET
request
Put Analysis
Replace an existing Beam analysis by making a PUT
request.
Ensure that the request body contains all the required fields specified in create analysis and that the Beam analysis exists.
Patch Analysis
Apply partial modifications to an existing Beam analysis by making a PATCH
request.
Ensure that the request body contains no additional fields other than the ones specified in create analysis and that the Beam analysis exists.
Delete Analysis
Delete an existing Beam analysis by making a DELETE
request.
GET
Action
GET /v1/beam/analyses/$ANALYSIS_ID
Example
curl -X GET https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
"name": "Analysis 1",
"location": {
"geopoint": {
"lat": "-36.849761",
"lon": "174.7628903"
},
"radius": 1.2,
"unit": "km"
},
"rank": {
"type": "phq",
"levels": {
"phq": {
"min": 51
}
}
},
"status": "draft",
"create_dt": "2023-03-01T23:03:19.403859+00:00",
"update_dt": "2023-03-01T23:49:39.464011+00:00",
"user_id": null,
"access_type": "full",
"processed_dt": "2023-03-01T23:43:52.253150+00:00",
"readiness_status": "ready",
"readiness_checks": {
"date_range": {
"start": "2017-01-01",
"end": "2017-12-31"
},
"validation_response": {
"missing_data_percentage": 0.0,
"consecutive_nan": 0
}
},
"tz": "UTC"
}
PUT
Action
PUT /v1/beam/analyses/$ANALYSIS_ID
Example
curl -X PUT https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
--data @<(cat <<EOF
{
"name": "Analysis 2",
"location": {
"geopoint": {
"lat": "-36.849761",
"lon": "174.7628903"
},
"radius": 1.2,
"unit": "km"
},
"rank": {
"type": "phq"
},
"tz": "UTC"
}
EOF
)
Response
HTTP/1.1 204 No Content
PATCH
Action
PATCH /v1/beam/analyses/$ANALYSIS_ID
Example
curl -X PATCH https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
--data @<(cat <<EOF
{
"name": "Analysis 2",
}
EOF
)
Response
HTTP/1.1 204 No Content
DELETE
Action
DELETE /v1/beam/analyses/$ANALYSIS_ID
Example
curl -X DELETE https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
HTTP/1.1 202 Accepted
Correlate Analysis
Use the following parameters described below to retrieve correlation data.
Query Parameters
Parameter | Description |
---|---|
date.* string required |
Filters out correlation data not included in the date range. The date parameter must have an upper (lt or lte ) and lower (gt or gte ) bound suffix.The accepted format for this parameter is YYYY-MM-DD E.g. ?date.gt=2017-01-01&date.lte=2017-12-01 |
limit number optional |
Limits the length of the Beam decomposition list returned. The default limit is 30 .E.g. ?limit=20 |
offset number optional |
Specifies starting offset of the Beam decomposition list returned. The default offset is 0 .E.g. ?offset=3 |
Action
GET /v1/beam/analyses/$ANALYSIS_ID/correlate?date.gte=2022-01-01&date.lte=2022-12-31
Example
curl -X GET https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID/correlate?date.gte=2022-01-01&date.lte=2022-12-31 \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
"model_version": "0.5.0",
"version": 0,
"dates": [
{
"date": "2020-01-01",
"actual_demand": 4637.25,
"baseline_demand": 6768.664221719573,
"remainder": -2131.414221719573,
"impact_significance": "SIGNIFICANT",
"impact_significance_score": 3,
"impact": 0.0,
"categories_impact": {
"community": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"concerts": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"festivals": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"performing_arts": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"sports": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"conferences": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"expos": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"public_holidays": {
"count": 1,
"impact": 0,
"percentage": 0.0
},
"school_holidays": {
"count": 1,
"impact": 0,
"percentage": 0.0
},
"observances": {
"count": 0,
"impact": 0,
"percentage": 0.0
}
}
}
],
"count": 1,
"categories_impact": {
"community": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"concerts": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"festivals": {
"count": 4,
"impact": 11606.0,
"percentage": 17.201719282644138
},
"performing_arts": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"sports": {
"count": 6,
"impact": 16366.0,
"percentage": 24.25670668445235
},
"conferences": {
"count": 0,
"impact": 0,
"percentage": 0.0
},
"expos": {
"count": 14,
"impact": 39498.0,
"percentage": 58.54157403290351
},
"public_holidays": {
"count": 79,
"impact": 0,
"percentage": 0.0
},
"school_holidays": {
"count": 387,
"impact": 0,
"percentage": 0.0
},
"observances": {
"count": 10,
"impact": 0,
"percentage": 0.0
}
}
}
Refresh Analysis
Refresh an existing Beam analysis in a ready
or pending
state by making a POST
request.
Correlate Fields
Below are the fields returned by the Beam correlate endpoint.
JSON Schemas are available for the Beam correlate endpoint and for a single correlation:
Field | Description |
---|---|
count number read-only |
The number of Beam decomposition dates returned. |
dates array read-only |
An array of Beam decomposition dates. |
dates.date date read-only |
The date of the Beam decomposition. |
dates.actual_demand number read-only |
The actual demand for a given date. |
dates.baseline_demand number read-only |
The expected demand for a given date. |
dates.remainder number read-only |
The difference between the actual_demand and the baseline_demand for a given date. This value may be positive or negative. |
dates.impact_significance string read-only |
Enum specifying how unusual the remainder is for a given date.Possible values:
|
dates.impact_significance_score number read-only |
Number specifying how unusual the remainder is for a given date. This value maps to impact_significance .Possible values:
|
dates.impact number read-only |
The total impact of all the event categories for a given date. |
dates.categories_impact json read-only |
A json object containing all impact categories for a given date. |
dates.categories_impact.<category> json read-only |
A json object containing impact information for the <category> for a given date. |
dates.categories_impact.<category>.count number read-only |
The number of events in this <category> for a given date. |
dates.categories_impact.<category>.impact number read-only |
The impact of events in this <category> for a given date. |
dates.categories_impact.<category>.percentage number read-only |
The impact percentage composition of this <category> to the total impact of all categories for a given date. |
categories_impact json read-only |
A json object containing all impact categories for the Beam decomposition date range returned. |
categories_impact.<category>.count number read-only |
The number of events in this <category> for the Beam decomposition date range returned. |
categories_impact.<category>.impact number read-only |
The impact of events in this <category> for the Beam decomposition date range returned. |
categories_impact.<category>.percentage number read-only |
The impact percentage composition of this <category> to the total impact of all categories for the Beam decomposition date range returned. |