Links

Correlate an Analysis

Retrieve results of the correlation of our event data with your transactional demand data.

Request

HTTP Request

GET https://api.predicthq.com/v1/beam/analyses/$analysis_id/correlate

Path Parameters

Parameter
Description
analysis_id
An existing Beam Analysis ID.

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

Response

Response Fields

Field
Description
count number
The number of Beam decomposition dates returned.
dates array
An array of Beam decomposition dates.
dates.date date
The date of the Beam decomposition.
dates.actual_demand number
The actual demand for a given date.
dates.baseline_demand number
The expected demand for a given date.
dates.remainder number
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
Enum specifying how unusual the remainder is for a given date. Possible values:
  • NO_IMPACT
  • WEAK
  • MEDIUM
  • SIGNIFICANT
dates.impact_significance_score number
Number specifying how unusual the remainder is for a given date. This value maps to impact_significance. Possible values:
  • 0
  • 1
  • 2
  • 3
dates.impact number
The total impact of all the event categories for a given date.
dates.categories_impact object
A json object containing all impact categories for a given date.
dates.categories_impact.<category> object
A json object containing impact information for the <category> for a given date.
dates.categories_impact.<category>.count number
The number of events in this <category> for a given date.
dates.categories_impact.<category>.impact number
The impact of events in this <category> for a given date.
dates.categories_impact.<category>.percentage number
The impact percentage composition of this <category> to the total impact of all categories for a given date.
categories_impact object
A json object containing all impact categories for the Beam decomposition date range returned.
categories_impact.<category>.count number
The number of events in this <category> for the Beam decomposition date range returned.
categories_impact.<category>.impact number
The impact of events in this <category> for the Beam decomposition date range returned.
categories_impact.<category>.percentage number
The impact percentage composition of this <category> to the total impact of all categories for the Beam decomposition date range returned.
Example response
Below is an example 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
}
}
}

Examples

curl
python
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"
import requests
response = requests.get(
url="https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID/correlate",
headers={
"Authorization": "Bearer $ACCESS_TOKEN",
"Accept": "application/json"
},
params={
"date.gte": "2022-01-01",
"date.lte": "2022-12-31"
}
)
print(response.json())

Guides

Below are some guides relevant to this API: