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.