# Get an Analysis

## Get an Analysis

> Get an existing Analysis.

```json
{"openapi":"3.1.0","info":{"title":"PredictHQ Beam API","version":"1.0.0"},"tags":[{"name":"Analyses"}],"servers":[{"url":"https://api.predicthq.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"$API_KEY","description":"Enter your PredictHQ API key. The Bearer prefix is added automatically.\n\nWhen calling the API directly, send: `Authorization: Bearer <YOUR_API_KEY>` as documented at [https://docs.predicthq.com/api/overview/authenticating](https://docs.predicthq.com/api/overview/authenticating)\n"}},"schemas":{"AnalysisResponse":{"type":"object","properties":{"name":{"description":"Name of the Analysis.","type":"string","minLength":1,"title":"Name"},"location":{"$ref":"#/components/schemas/LocationResponse"},"rank":{"description":"Specifies which rank type was set to use when calculating event impacts and anomaly detection.","$ref":"#/components/schemas/RankResponse"},"user_id":{"description":"Identifier of the user who owns the Analysis.","type":"string","title":"User Id"},"access_type":{"description":"Access level for the Analysis.","$ref":"#/components/schemas/AccessType"},"status":{"description":"Status of the Analysis.","$ref":"#/components/schemas/AnalysisStatus"},"readiness_status":{"$ref":"#/components/schemas/AnalysisReadinessStatus"},"readiness_checks":{"$ref":"#/components/schemas/AnalysisReadinessChecks"},"processing_completed":{"description":"Status of the Analysis processing stages. All stages will be present here and are reset to `false` whenever the\nAnalysis is refreshed (i.e., processing has been initiated) then set to `true` when that stage of the\nprocessing is\ncompleted.","$ref":"#/components/schemas/AnalysisProcessingCompleted"},"demand_type":{"$ref":"#/components/schemas/DemandTypeResponse"},"group_ids":{"description":"IDs of the groups this Analysis belongs to.","type":"array","items":{"type":"string"},"title":"Group Ids"},"tz":{"description":"The time zone of the Analysis in [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)\nformat.\n\n**Note**: this field is populated automatically based on the location of the Analysis.","type":"string","title":"Tz"},"create_dt":{"description":"Date and time when the Analysis was created (ISO 8601).","type":"string","format":"date-time","title":"Create Dt"},"update_dt":{"description":"Date and time when the Analysis was last updated (ISO 8601).","type":"string","format":"date-time","title":"Update Dt"},"processed_dt":{"description":"Date and time when the Analysis processing completed (ISO 8601).","type":"string","format":"date-time","title":"Processed Dt"},"external_id":{"description":"External identifier associated with the Analysis (optional, user-defined).","type":"string","title":"External Id"},"label":{"description":"Comma-separated list of labels that can be used to search and filter analyses.","type":"array","items":{"type":"string"},"explode":false,"style":"form","title":"Label"},"saved_location":{"$ref":"#/components/schemas/SavedLocationResponse"}},"required":["name"],"title":"AnalysisResponse"},"LocationResponse":{"description":"Location of the Analysis.\n\nSupports one of the following location options:\n  - `saved_location_id`\n  - `geopoint` with `radius` and `unit`","type":"object","properties":{"geopoint":{"$ref":"#/components/schemas/GeoPointResponse"},"radius":{"description":"Must be an integer or a float number up to 2 decimal places. It represents the radius of the event search around\nyour `geopoint` to use for time series modelling and correlation. We **strongly recommend** using the\n[Suggested Radius API](https://docs.predicthq.com/api/suggested-radius/get-suggested-radius) to find a\nsuitable radius for your location/industry.","type":"number","minimum":0,"title":"Radius"},"unit":{"description":"The unit for `radius` where\n  - `m` is meters\n  - `km` is kilometers\n  - `ft` is feet\n  - `mi` is miles","type":"string","enum":["m","mi","km","ft"],"title":"Unit"},"saved_location_id":{"description":"The ID of a previously created Saved Location for your analysis as documented at\n[Saved Locations API](https://docs.predicthq.com/api/saved-locations/create-a-saved-location)","type":"string","minLength":1,"title":"Saved Location Id"}},"title":"LocationResponse"},"GeoPointResponse":{"type":"object","properties":{"lat":{"type":"string","pattern":"^[-+]?([1-8]?\\d(\\.\\d+)?|90(\\.0+)?)$","title":"Lat"},"lon":{"type":"string","pattern":"^[-+]?(180(\\.0+)?|((1[0-7]\\d)|([1-9]?\\d))(\\.\\d+)?)$","title":"Lon"}},"required":["lat","lon"],"title":"GeoPointResponse"},"RankResponse":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/RankTypeResponse"},"levels":{"$ref":"#/components/schemas/RankLevelsResponse"}},"required":["type"],"title":"RankResponse"},"RankTypeResponse":{"type":"string","enum":["phq","local"],"title":"RankTypeResponse"},"RankLevelsResponse":{"type":"object","properties":{"phq":{"$ref":"#/components/schemas/RankLevel"},"local":{"$ref":"#/components/schemas/RankLevel"}},"additionalProperties":false,"title":"RankLevelsResponse"},"RankLevel":{"type":"object","properties":{"min":{"type":"integer","maximum":100,"minimum":0,"title":"Min"},"max":{"type":"integer","maximum":100,"minimum":0,"title":"Max"}},"required":["min"],"title":"RankLevel"},"AccessType":{"type":"string","enum":["full","limited"],"title":"AccessType"},"AnalysisStatus":{"type":"string","enum":["active","deleted"],"title":"AnalysisStatus"},"AnalysisReadinessStatus":{"description":"The value of this field determines whether or not the Analysis has successfully completed processing.\n\nWhen you upload data for an Analysis the `readiness_status` will be set to `pending` until processing has\ncompleted.","type":"string","enum":["pending","failed","ready","stale"],"title":"AnalysisReadinessStatus"},"AnalysisReadinessChecks":{"description":"Beam performs a number of validation checks on the data provided. The results of some of those checks are\nstored in this field.\n\nWe don't recommend relying on the values in this field as the structure may change without warning. Instead, refer\nto the `readiness_status` field to determine whether or not the Analysis is ready (i.e. has completed\nprocessing successfully).","type":"object","properties":{"date_range":{"$ref":"#/components/schemas/AnalysisDateRange"},"error_code":{"type":"string","title":"Error Code"},"missing_dates":{"type":"array","items":{"type":"string"},"title":"Missing Dates"},"validation_response":{"type":"object","additionalProperties":true,"title":"Validation Response"},"best_practice":{"type":"boolean","default":false,"title":"Best Practice"},"best_practice_checks":{"$ref":"#/components/schemas/BestPracticeChecks"}},"title":"AnalysisReadinessChecks"},"AnalysisDateRange":{"type":"object","properties":{"start":{"type":"string","format":"date","title":"Start"},"end":{"type":"string","format":"date","title":"End"}},"required":["start","end"],"title":"AnalysisDateRange"},"BestPracticeChecks":{"type":"object","properties":{"industry":{"type":"boolean","default":false,"title":"Industry"},"rank":{"type":"boolean","default":false,"title":"Rank"},"radius":{"description":"Must be an integer or a float number up to 2 decimal places. It represents the radius of the event search around\nyour `geopoint` to use for time series modelling and correlation. We **strongly recommend** using the\n[Suggested Radius API](https://docs.predicthq.com/api/suggested-radius/get-suggested-radius) to find a\nsuitable radius for your location/industry.","type":"boolean","default":false,"title":"Radius"}},"title":"BestPracticeChecks"},"AnalysisProcessingCompleted":{"type":"object","properties":{"correlation":{"type":"boolean","default":false,"title":"Correlation"},"feature_importance":{"type":"boolean","default":false,"title":"Feature Importance"},"value_quant":{"type":"boolean","default":false,"title":"Value Quant"}},"title":"AnalysisProcessingCompleted"},"DemandTypeResponse":{"description":"Indicates the detected type of the uploaded demand data as well as other user-defined information about\nthe demand data.","type":"object","properties":{"industry":{"$ref":"#/components/schemas/Industry"},"interval":{"description":"Demand interval for analyses in the group. Possible values: day, week.","default":"day","$ref":"#/components/schemas/Interval"},"week_start_day":{"description":"Week start day (e.g. sunday, monday). Only present for weekly Analysis Groups.","$ref":"#/components/schemas/Weekday"},"unit_descriptor":{"description":"The description of the unit of demand, which specifies the type or measure being quantified (e.g.,\n\"Occupancy Rate\", \"Sales\", \"Number of Transactions\").","type":"string","default":"Sales","title":"Unit Descriptor"},"currency_code":{"default":"USD","$ref":"#/components/schemas/CurrencyCode"},"unit_currency_multiplier":{"description":"The multiplier used to adjust the unit of demand to its equivalent value in the specified currency.","type":"number","default":1,"title":"Unit Currency Multiplier"}},"title":"DemandTypeResponse"},"Industry":{"description":"The industry of the demand data being analysed by Beam. Choosing the right industry is important as this will\ndetermine the type of features used in the Analysis and will impact the accuracy of the results.","type":"string","default":"other","enum":["accommodation","cpg","tourism","marketing","parking","restaurants","retail","transportation","other"],"title":"Industry"},"Interval":{"type":"string","enum":["day","week"],"title":"Interval"},"Weekday":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"title":"Weekday"},"CurrencyCode":{"description":"The ISO 4217 standard code representing the currency corresponding to the units of demand.","type":"string","default":"USD","enum":["USD","EUR","GBP","AUD","CAD"],"title":"CurrencyCode"},"SavedLocationResponse":{"description":"Saved Location object at the time of processing the Analysis.","type":"object","properties":{"name":{"description":"The user defined name of the Saved Location set in the create location call.","type":"string","title":"Name"},"formatted_address":{"description":"The address of the location. This can be supplied when creating a location.\nIf it's not supplied it will be populated by a reverse geocode.","type":"string","title":"Formatted Address"},"geojson":{"description":"An object containing the geographic information about the saved location. Represents the geometry in the GeoJSON\nformat.","$ref":"#/components/schemas/GeoJsonResponse"},"h3":{"description":"A list of H3 indices that cover the saved location (if applicable).","type":"array","items":{"type":"string"},"title":"H3"},"place_ids":{"description":"An array of place IDs (from the Places API) for locations that are defined as covering an area (e.g. city, state,\ncountry) rather than a point and radius.","type":"array","items":{"type":"integer"},"title":"Place Ids"},"place_hierarchies":{"type":"array","items":{"type":"string"},"title":"Place Hierarchies"},"places":{"description":"A list of Geonames Places corresponding to the saved location. Usually a single item, but always a list.","type":"array","items":{"$ref":"#/components/schemas/PlaceResponse"},"title":"Places"},"subscription_valid_types":{"description":"The list of subscription types that this location is valid for.\nPossible values: `events`, `broadcasts`, `features_api`.\n\nIt is possible to create locations outside of what your subscription has access to; in this case this field \nwill be empty and you will not be able to view events for the location.","type":"array","items":{"$ref":"#/components/schemas/SubscriptionValidType"},"title":"Subscription Valid Types"},"location_id":{"description":"The autogenerated identifier for the saved location.","type":"string","title":"Location Id"}},"required":["location_id"],"title":"SavedLocationResponse"},"GeoJsonResponse":{"type":"object","properties":{"type":{"type":"string","title":"Type"},"properties":{"$ref":"#/components/schemas/GeoJsonProperties"},"geometry":{"$ref":"#/components/schemas/GeoJsonGeometry"}},"required":["type","geometry"],"title":"GeoJsonResponse"},"GeoJsonProperties":{"type":"object","properties":{"radius":{"description":"Must be an integer or a float number up to 2 decimal places. It represents the radius of the event search around\nyour `geopoint` to use for time series modelling and correlation. We **strongly recommend** using the\n[Suggested Radius API](https://docs.predicthq.com/api/suggested-radius/get-suggested-radius) to find a\nsuitable radius for your location/industry.","type":"number","exclusiveMinimum":0,"title":"Radius"},"radius_unit":{"$ref":"#/components/schemas/RadiusUnit"}},"required":["radius","radius_unit"],"title":"GeoJsonProperties"},"RadiusUnit":{"type":"string","enum":["m","km","mi","ft"],"title":"RadiusUnit"},"GeoJsonGeometry":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/GeoJsonGeometryType"},"coordinates":{"type":"array","minItems":1,"title":"Coordinates"}},"required":["type","coordinates"],"title":"GeoJsonGeometry"},"GeoJsonGeometryType":{"type":"string","enum":["Point","Polygon","MultiPolygon","LineString","MultiLineString"],"title":"GeoJsonGeometryType"},"PlaceResponse":{"type":"object","properties":{"place_id":{"type":"integer","title":"Place Id"},"type":{"type":"string","title":"Type"},"name":{"type":"string","title":"Name"},"county":{"type":"string","title":"County"},"region":{"type":"string","title":"Region"},"country":{"type":"string","title":"Country"},"geojson":{"$ref":"#/components/schemas/GeoJsonResponse"}},"required":["place_id","type","name","geojson"],"title":"PlaceResponse"},"SubscriptionValidType":{"type":"string","enum":["broadcasts","events","features_api"],"title":"SubscriptionValidType"},"HTTPError":{"type":"object","properties":{"error":{"type":"string","title":"Error"}},"required":["error"],"title":"HTTPError"}}},"paths":{"/v1/beam/analyses/{analysis_id}":{"get":{"operationId":"get_analysis_public_analyses__analysis_id__get","summary":"Get an Analysis","description":"Get an existing Analysis.","parameters":[{"name":"analysis_id","in":"path","description":"An existing Beam Analysis ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}}},"403":{"description":"Bearer token scope insufficient"},"404":{"description":"Analysis not found"}},"tags":["Analyses"]}}}}
```

## Examples

{% tabs %}
{% tab title="curl" %}

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

{% endtab %}

{% tab title="python" %}

```python
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())
```

{% endtab %}
{% endtabs %}

## OpenAPI Spec

The OpenAPI spec for Beam API can be [found here](https://api.predicthq.com/docs/?urls.primaryName=Beam+API).

## Guides

Below are some guides relevant to this API:

* [Beam Guides](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/getting-started/guides/beam-guides)