Get an Analysis

Get an existing Analysis.

Request

HTTP Request

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

Path Parameters

Parameter Description

Parameter	Description
`analysis_id`	An existing Beam Analysis ID.

analysis_id

An existing Beam Analysis ID.

Response

Response Fields

Field Description

Field	Description
`name` string	Name of the Analysis. E.g. `My Location Analysis 1`
`create_dt` string	The creation date time for the Analysis in ISO 8601 format format. E.g. `2022-04-26T11:46:24+00:00`
`update_dt` string	The last update date time for the Analysis in ISO 8601 format format. E.g. `2022-04-26T11:46:24+00:00`
`processed_dt` string	The date time the Analysis was last processed in ISO 8601 format format. E.g. `2022-04-26T11:46:25+00:00`
`user_id` string	The ID of the user who created the Analysis. This is present for Analyses created in Control Center. For Analyses created via the API this field will not be present. E.g. `hjqkKozgS8mm`
`external_id` string	External ID. Used to identify this Beam Analysis using an ID from another system.
`label` array	Labels to categorize the Analysis.
`access_type` string	Indicates whether or not your subscription has access to the provided location. We allow creating Analyses for any location, even locations outside of your subscription. However, for locations outside of your subscription the `access_type` will be set as `limited` and certain functionality might not be available. Possible values: `full` `limited` E.g. `full`
`location` object	Location of the Analysis. E.g. `{ "location": { "geopoint": { "lat": "-36.849761", "lon": "174.7628903" }, "radius": 1.2, "unit": "km" } }`
`rank` object	Specifies which rank type was set to use when calculating event impacts and anomaly detection. E.g. `{ "rank": { "type": "phq", "levels": { "phq": { "min": 51 } } } }`
`demand_type` object	Indicates the detected type of the uploaded demand data as well as other user-defined information about the demand data. Fields: `interval` - `day` or `week` `week_start_day` - e.g. `sunday`, `monday` etc. Only displayed for weekly analyses `industry` - user selected industry of the demand data.
`tz` string	The time zone of the Analysis in TZ Database format. E.g. `Pacific/Auckland` Note: this field is populated automatically based on the location of the Analysis.
`readiness_checks` object	Beam performs a number of validation checks on the data provided. The results of some of those checks are stored in this field. We don't recommend relying on the values in this field as the structure may change without warning. Instead, refer to the `readiness_status` field to determine whether or not the Analysis is ready (i.e. has completed processing successfully). E.g. `{ "readiness_checks": { "date_range": { "start": "2017-01-01", "end": "2017-12-31" }, "validation_response": { "missing_data_percentage": 0.0, "consecutive_nan": 0 } } }`
`readiness_status` string	The value of this field determines whether or not the Analysis has successfully completed processing. When you upload data for an Analysis the `readiness_status` will be set to `pending` until processing has completed. Possible values: `pending` `failed` `ready` E.g. `ready`
`processing_completed` object	Status of the Analysis processing stages. All stages will be present here and are reset to `false` whenever the Analysis is refreshed (i.e., processing has been initiated) then set to `true` when that stage of the processing is completed. E.g. `{ "processing_completed": { "correlation": true, "feature_importance": true } }`
`status` string	Status of the Analysis. Possible values: `active` E.g. `active`

name string

Name of the Analysis. E.g. My Location Analysis 1

create_dt string

The creation date time for the Analysis in ISO 8601 format format.

E.g. 2022-04-26T11:46:24+00:00

update_dt string

The last update date time for the Analysis in ISO 8601 format format.

E.g. 2022-04-26T11:46:24+00:00

processed_dt string

The date time the Analysis was last processed in ISO 8601 format format.

E.g. 2022-04-26T11:46:25+00:00

user_id string

The ID of the user who created the Analysis. This is present for Analyses created in Control Center. For Analyses created via the API this field will not be present.

E.g. hjqkKozgS8mm

external_id string

External ID. Used to identify this Beam Analysis using an ID from another system.

label array

Labels to categorize the Analysis.

access_type string

Indicates whether or not your subscription has access to the provided location.

We allow creating Analyses for any location, even locations outside of your subscription. However, for locations outside of your subscription the access_type will be set as limited and certain functionality might not be available.

Possible values:

full
limited

E.g. full

location object

Location of the Analysis. E.g.

{
  "location": {
    "geopoint": {
      "lat": "-36.849761",
      "lon": "174.7628903"
    },
    "radius": 1.2,
    "unit": "km"
  }
}

rank object

Specifies which rank type was set to use when calculating event impacts and anomaly detection. E.g.

{
  "rank": {
    "type": "phq",
    "levels": {
      "phq": {
        "min": 51
      }
    }
  }
}

demand_type object

Indicates the detected type of the uploaded demand data as well as other user-defined information about the demand data.

Fields:

interval - day or week
week_start_day - e.g. sunday, monday etc. Only displayed for weekly analyses
industry - user selected industry of the demand data.

tz string

The time zone of the Analysis in TZ Database format.

E.g. Pacific/Auckland

Note: this field is populated automatically based on the location of the Analysis.

readiness_checks object

Beam performs a number of validation checks on the data provided. The results of some of those checks are stored in this field.

We don't recommend relying on the values in this field as the structure may change without warning. Instead, refer to the readiness_status field to determine whether or not the Analysis is ready (i.e. has completed processing successfully). E.g.

{
  "readiness_checks": {
    "date_range": {
      "start": "2017-01-01",
      "end": "2017-12-31"
    },
    "validation_response": {
      "missing_data_percentage": 0.0,
      "consecutive_nan": 0
    }
  }
}

readiness_status string

The value of this field determines whether or not the Analysis has successfully completed processing.

When you upload data for an Analysis the readiness_status will be set to pending until processing has completed. Possible values:

pending
failed
ready

E.g. ready

processing_completed object

Status of the Analysis processing stages. All stages will be present here and are reset to false whenever the Analysis is refreshed (i.e., processing has been initiated) then set to true when that stage of the processing is completed.

E.g.

{
  "processing_completed": {
    "correlation": true,
    "feature_importance": true
  }
}

status string

Status of the Analysis. Possible values:

active

E.g. active

Example response

Below is an example response:

{
    "name": "Analysis 1",
    "create_dt": "2023-03-01T23:03:19.403859+00:00",
    "update_dt": "2023-03-01T23:49:39.464011+00:00",
    "processed_dt": "2023-03-01T23:43:52.253150+00:00",
    "user_id": null,
    "external_id": "id1",
    "label": ["label1", "label2", "label3"],
    "location": {
        "geopoint": {
            "lat": "-36.849761",
            "lon": "174.7628903"
        },
        "radius": 1.2,
        "unit": "km"
    },
    "demand_type": {
        "interval": "week",
        "week_start_day": "monday",
        "industry": "restaurants"
    },
    "rank": {
        "type": "phq",
        "levels": {
            "phq": {
                "min": 51
            }
        }
    },
    "tz": "UTC",
    "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
        }
    },
    "processing_completed": {
        "correlation": true,
        "feature_importance": true
    },
    "access_type": "full",
    "status": "draft"
}

Examples

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

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/beam/analyses/<analysis_id>",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    }
)

print(response.json())

Guides

Below are some guides relevant to this API:

Beam Guides

PreviousSearch Analyses NextUpdate an Analysis

Last updated 1 month ago