Create an Analysis

Creating an Analysis is the first step in understand which types of events impact your demand.

Request

HTTP Request

POST https://api.predicthq.com/v1/beam/analyses

Request Headers

Header	Value
Content-Type	application/json

Request Body

Field	Description
name string required	Name of an analysis. E.g. My Location Analysis 1
location.* object required	Contains geopoint, radius and unit to represent the location of your data to create the analysis. geopoint contains lat and lon which are coordinates for your analysis, e.g. if you are creating an analysis for a store in Seattle you'd specify the latitude and longitude of your store. radius must be an integer or a float number up to 2 decimal places. It represents the radius of the event search around your geopoint to use for time series modelling and correlation. We strongly recommend using the Suggested Radius API to find a suitable radius for your location/industry. unit is the unit for radius and must be one of: m - meters km - kilometers ft - feet mi - miles E.g. { "geopoint": { "lat": "-36.849761", "lon": "174.7628903" }, "radius": 1.22, "unit": "km" }
demand_type.* object optional	Provides information about the demand type of the analysis. industry is the industry of the demand data being analysed by Beam. Choosing the right industry is important as this will determine the type of features used in the Analysis and will impact the accuracy of the results. The default value is "other". Must be one of the following: accommodation cpg tourism marketing parking restaurants retail transportation other currency_code is the ISO 4217 standard code representing the currency corresponding to the units of demand. The default value is "USD". Must be one of the following: USD EUR GBP AUD CAD unit_currency_multiplier is a multiplier used to adjust the unit of demand to its equivalent value in the specified currency. Default value of 1. unit_descriptor is a description of the unit of demand, which specifies the type or measure being quantified (e.g., "Occupancy Rate", "Sales", "Number of Transactions"). The default value is "Sales". E.g. { "demand_type": { "industry": "restaurants", "currency_code": "USD", "unit_currency_multiplier": 1, "unit_descriptor": "Sales" } }
external_id string optional	External identifier for the location. If you have an ID for the location/store/property in your other platforms, use the same ID here to easily link this specific Beam Analysis to the location. E.g. { "external_id": "abc123" }
label string optional	Comma-separated list of labels that can be used to search and filter Beam analyses. E.g. { "label": ["label1", "label2", "label3"] }
rank.* object required	Specifies which rank type to use when calculating event impacts and anomaly detection. Currently, only PHQ rank is supported (also known as "Rank") so this value should be set to "phq" as shown below. { "type": "phq" } Possible rank type values: phq - PHQ Rank Optionally, specify the minimum rank level to use when calculating event impacts. Note: We strongly recommend not setting the rank levels and instead letting Beam define the best rank levels based on your industry. E.g. { "type": "phq", "levels": { "phq": { "min": 51 } } }

Response

Example response

Below is an example response:

{
  "analysis_id": "2iJcUzm3-ZE"
}

Examples

curl

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"
        },
        "demand_type": {
            "industry": "restaurants"
        },
        "rank": {
            "type": "phq"
        }
    }
    EOF
    )

python

import requests

response = requests.post(
    url="https://api.predicthq.com/v1/beam/analyses",
    headers={
        "Authorization": "Bearer $ACCESS_TOKEN",
        "Accept": "application/json"
    },
    json={
        "name": "Analysis 1",
        "location": {
            "geopoint": {
                "lat": "-36.849761",
                "lon": "174.7628903"
            },
            "radius": 1.2,
            "unit": "km"
        },
        "demand_type": {
            "industry": "restaurants"
        },
        "rank": {
            "type": "phq"
        }
    }
)

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