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:
​Beam Data Science Guide​

Parameter	Description
`analysis_id`	An existing Beam Analysis ID.

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`

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.

Partially Update an Analysis

Get Feature Importance

Last modified 2mo ago