Get Correlation Results

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

⚠️ Please note we have deprecated some fields in this endpoint. The deprecated fields are not intended to be used to get current feature values for use in forecasting or other use-cases. They're a snapshot of some of the data from the time the correlation process was run, so for any other purposes are immediately out-of-date. Please fetch the latest data from Features API instead.

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.features object ⚠️ Deprecated	A json object containing all non-zero features for a given date.
dates.features.<feature>.count number ⚠️ Deprecated	The number of events corresponding to this <feature> for a given date.
dates.features.<feature>.sum number ⚠️ Deprecated	The sum of the values of this <feature> for a given date.
dates.phq_impact_sum number ⚠️ Deprecated	The sum of all phq_impact features for a given date
dates.phq_spend_sum number ⚠️ Deprecated	The sum of all phq_spend features for a given date
dates.phq_attendance_sum number ⚠️ Deprecated	The sum of all phq_attendance features for a given date
dates.phq_rank_sum number ⚠️ Deprecated	The sum of all phq_rank features for a given date

Example response

Below is an example response:

{
    "model_version": "1.1.0",
    "version": 0,
    "dates": [
        {
            "date": "2021-01-01",
            "actual_demand": 5893.0,
            "baseline_demand": 1642.8505673206673,
            "remainder": 4250.149432679333,
            "impact_significance": "MEDIUM",
            "impact_significance_score": 2
        },
        {
            "date": "2021-01-02",
            "actual_demand": 4273.0,
            "baseline_demand": 4373.972146649381,
            "remainder": -100.9721466493811,
            "impact_significance": "NO_IMPACT",
            "impact_significance_score": 0
        },
    ]
...
}

Examples

curl

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"

python

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:

• https://github.com/predicthq/gitbook-tech-docs/blob/main/docs/getting-started/guides/beam-guides/README.md