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` - Miles `m` - Meters `km` - 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 Rank `aviation` - Aviation Rank Optionally, 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`

Action

POST /v1/beam/analyses/$ANALYSIS_ID/sink

Example

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

Response

HTTP/1.1 202 Accepted

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: `draft` `active` `deleted` E.g. `?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: `pending` `failed` `ready` E.g. `?status=pending,ready`
sort string optional	Comma separated list (`<sort1>,<sort2>`) used to sort Beam analyses. Possible values: `name` - Ascending Order `created` - Ascending Order `updated` - Ascending Order `-name` - Descending Order `-created` - Descending Order `-updated` - Descending Order E.g. `?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.

Action

POST /v1/beam/analyses/$ANALYSIS_ID/refresh HTTP/1.1

Example

curl -X POST https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID/refresh \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

Response

HTTP/1.1 202 Accepted

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: `NO_IMPACT` `WEAK` `MEDIUM` `SIGNIFICANT`
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: `0` `1` `2` `3`
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.