> This is part 1 of 2 of the full documentation (pages 1–100 of 179).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.predicthq.com/llms-full.txt/1
> Page index: https://docs.predicthq.com/llms.txt

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.predicthq.com/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

---

# Overview

Docs, guides, and API references to help you build with PredictHQ.

Everything you need to integrate PredictHQ into your models, pipelines, and AI systems.

<a href="https://docs.predicthq.com/getting-started/api-quickstart" class="button primary">API Quickstart</a> <a href="https://docs.predicthq.com/api/" class="button secondary">API Reference</a>

## Core APIs

The core APIs are:

* [Events API](https://docs.predicthq.com/api/events/search-events) - Structured, deduplicated real-world events for discovery, explainability, and building trust in AI-driven decisions
* [Features API](https://docs.predicthq.com/api/features/get-features) - Pre-built, model-ready demand features aggregated from real-world events
* [Forecasts API](https://docs.predicthq.com/api/forecasts/overview) - Event-driven demand forecasts without building or maintaining your own model
* [Beam API](https://docs.predicthq.com/api/beam/overview) - Identify the real-world events that materially move your demand
* [Saved Locations API](https://docs.predicthq.com/api/saved-locations/overview) - Define and manage reusable business locations for consistent querying across Events, Features, Beam, and Forecasts APIs

## How it fits together

Start with [How to use PredictHQ](https://docs.predicthq.com/getting-started/how-to-use-predicthq) - the recommended integration paths by job, from model training to grounding AI systems. PredictHQ APIs work as a pipeline, not in isolation: the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) shows the recommended production architecture, from location setup through to forecasting and explainability.

## Example

Use your Beam Analysis ID to pull model-ready ML features for any date range - the API applies location, filters, and feature selection automatically:

```python
import requests

response = requests.post(
    url="https://api.predicthq.com/v1/features/",
    headers={
        "Authorization": "Bearer $API_TOKEN",
        "Accept": "application/json"
    },
    json={
        "beam": {
            "analysis_id": "$ANALYSIS_ID"
        },
        "active": {
            "gte": "2026-06-01",
            "lte": "2026-06-30"
        }
    }
)

print(response.json())
```

## AI & agents

These resources cover building with AI:

* [Build with AI](https://docs.predicthq.com/ai/build-with-ai) - Connect any MCP-compatible AI assistant to PredictHQ APIs through natural language
* [PredictHQ MCP server](https://docs.predicthq.com/ai/mcp) - Query events, demand intelligence, and all PredictHQ APIs without writing code
* [Bolt](https://docs.predicthq.com/ai/bolt) - AI-native developer environment built into the WebApp

## Resources

These resources support your integration:

* [API Overview](https://docs.predicthq.com/api/overview/authenticating) - Authentication, rate limits, and API conventions
* [Guides](https://docs.predicthq.com/getting-started/guides) - Step-by-step integration guides for core APIs and use cases
* [Python SDK](https://docs.predicthq.com/sdks/python-sdk) - The official Python client for the PredictHQ API
* [Data science notebooks](https://docs.predicthq.com/getting-started/data-science-notebooks) - Jupyter notebooks for Beam, Features API, and demand forecasting
* [System Status](https://www.predicthqstatus.com/) - Live status and incident history for PredictHQ services


# How to use PredictHQ

The recommended integration paths for PredictHQ: train forecasting models on event features, ground AI systems in verified real-world context, or get event-driven forecasts without building a model.

PredictHQ is the real-world context platform powering enterprise AI decisions. You use its verified events, predicted impacts, and demand-calibrated features along a recommended path for each job: train your forecasting models on event features, ground LLMs and agents in verified context at answer time, get event-driven forecasts without building a model, or analyze what drives demand at your locations. This page routes you to the right path and shows how the paths fit together.

## Start with the job you're doing

| Your job                                               | Path                                                                                                         |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| Improve the accuracy of a forecasting model you own    | [Train your models on event features](#train-your-models-on-event-features)                                  |
| Get event-driven forecasts without building a model    | [Get forecasts without building a model](#get-forecasts-without-building-a-model)                            |
| Stop an LLM or AI agent guessing about the real world  | [Ground your AI in verified context](#ground-your-ai-in-verified-context)                                    |
| Understand which events drive demand at your locations | [Understand what drives your demand](#understand-what-drives-your-demand)                                    |
| Show operators the events behind a demand shift        | [Events API](https://docs.predicthq.com/api/events/search-events) with `beam.analysis_id` for explainability |

Whichever path you take, the first two steps are the same, and they calibrate everything downstream:

1. Create a [Saved Location](https://docs.predicthq.com/api/saved-locations/overview) for each business location using `origin_geojson` - Predicted Impact Area is calculated automatically, defining where events actually affect that location.
2. Run [Beam](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam), PredictHQ's relevancy engine, with your historical demand data. The resulting `analysis_id` scopes every downstream call to the event categories and thresholds that drive demand at that location.

## Train your models on event features

For data science teams who own a forecasting model and want it more accurate.

Retrieve model-ready features from the [Features API](https://docs.predicthq.com/api/features/get-features) keyed by your `beam.analysis_id`: historical windows to train on alongside your demand history, and future-dated windows at every forecast run. Because events are known in advance, the future values are real demand signals rather than estimates - no zero-filling the forecast horizon.

Using a pre-trained time series foundation model instead? There is no training step - supply features covering both your demand history and the forecast horizon as covariates. See [Using event features with time series foundation models](https://docs.predicthq.com/getting-started/guides/features-api-guides/using-event-features-with-time-series-foundation-models).

Related guides:

* [Which API should I use?](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use)
* [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) - the production architecture

## Get forecasts without building a model

For teams that want event-driven forecast accuracy with rapid time-to-value, without building or maintaining a forecasting pipeline.

Supply historical demand data to the [Forecasts API](https://docs.predicthq.com/api/forecasts/overview) and it trains a model, applies Beam automatically, and returns daily-level forecasts with event impact and explainability built in. A baseline comparison shows the accuracy improvement attributable to PredictHQ data - measured on your own demand.

The Forecasts API also fits multi-model setups: run it as one candidate in a champion-challenger selection or an ensemble alongside your existing forecasts, and let measured accuracy decide which wins each series. Nothing needs replacing to adopt it.

Related guides:

* [Getting started with Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/getting-started)

## Ground your AI in verified context

For ML platform and agent teams whose LLMs or agents make demand-related decisions, where an AI hallucination (a confident, plausible, wrong answer) carries real cost.

Grounding gives a model the real-world facts it lacks at the moment it answers, so it responds from what is true instead of hallucinating. Retrieval-augmented generation (RAG) is one technique for achieving it. PredictHQ supports two grounding architectures; most deployments choose one, and which fits is mostly a governance and maintenance question:

* **Provisioned grounding** - PredictHQ delivers verified event context into your environment (Snowflake, AWS Data Exchange, SFTP, or API sync) and your AI systems retrieve from a store you govern. Choose this when data residency, governance, or retrieval scale matter.
* **On-demand grounding** - your agents query the [PredictHQ MCP server](https://docs.predicthq.com/ai/mcp) on demand and hold no copy of anything. Choose this when zero pipeline maintenance matters, or when you want to be up and running today without waiting on your platform team's roadmap.

Learn more:

* [Grounding with PredictHQ](https://docs.predicthq.com/ai/grounding-with-predicthq) - concepts, architectures, and FAQ
* [Provisioned grounding: retrieval inside your environment](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding) - the reference architecture
* [PredictHQ MCP in agentic workflows](https://docs.predicthq.com/ai/predicthq-mcp-in-agentic-workflows)

## Understand what drives your demand

For analysts and data scientists who need to know which real-world events matter before committing to a build - or need evidence for what happened.

Beam's [Feature Importance](https://docs.predicthq.com/api/beam/analyses/get-feature-importance) results rank the event categories that drive demand at each location and quantify how much of your demand variability is event-driven. PredictHQ explains more than 60 percent of real-world demand variability. Drill into the specific events behind any shift with the [Events API](https://docs.predicthq.com/api/events/search-events) using the same `analysis_id`.

Related guides:

* [Understanding demand variability and event contribution in Beam](https://docs.predicthq.com/getting-started/guides/beam-guides/understanding-demand-variability-and-event-contribution-in-beam)

## How the paths fit together

Training improves your model before it runs. Grounding supplies verified context while it runs. The two never mix - grounding doesn't touch the training model - and the two grounding architectures are alternatives to each other, not to training. Time series foundation models don't change this split; they shrink the training step and move more of the value to inference time.

The paths share the same foundation, so they combine naturally: the Saved Locations and Beam Analyses you set up for a forecasting integration are the same ones that scope a grounding corpus or an agent's MCP queries. Many production deployments run a training path and a grounding path side by side - a model trained on event features, and an AI layer that explains its outputs from verified event context.

## Next steps

Continue with these pages:

* [API quickstart](https://docs.predicthq.com/getting-started/api-quickstart) - make your first call
* [Which API should I use?](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use) - per-task API selection
* [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) - the production reference architecture


# API quickstart

Get your API key, make your first call, and understand how PredictHQ fits into a production integration.

## What you need

Before you start, you need:

1. A PredictHQ account - [log in](https://control.predicthq.com/) or [sign up for free](https://signup.predicthq.com/).
2. An API Key - create one in the next section.

## Create an API key

To create a key:

1. Log in to the [WebApp](https://control.predicthq.com/tokens).
2. Go to **API Tools → API Tokens**.
3. Click **Create Token**.
4. Enter a name.
5. Click **Create**.
6. Click **Copy Token**.
7. Store the token somewhere safe. The WebApp doesn't show it again.

In the `Authorization` header of every API request, use your API key:

```
Authorization: Bearer $API_TOKEN
```

## Make your first call

The Events API returns structured, deduplicated real-world events. To verify your API key is working and to explore what events look like in the response, run this request:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
        "Authorization": "Bearer $API_TOKEN",
        "Accept": "application/json"
    },
    params={
        "place.scope": "5128581",  # New York City
        "category": "concerts,sports,conferences",
        "active.gte": "2026-06-01",
        "active.lte": "2026-06-30",
        "limit": 10
    }
)

print(response.json())
```

{% hint style="info" %}
**Note:** The Events API is for discovery and explainability - understanding which events are happening and why they matter. For demand forecasting and ML, use the Features API instead. See [Which API Should I Use](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use) for guidance on which API to use for your use case.
{% endhint %}

## How PredictHQ APIs work together

A single API call is not a production integration. PredictHQ designed its APIs to work as a pipeline:

1. **Saved Locations** - define your business locations once using `origin_geojson`. PredictHQ calculates Predicted Impact Area automatically and stores it against each location.
2. **Beam** - run a Beam Analysis per location using your historical demand data. Beam identifies which event categories actually drive demand at each location and returns an `analysis_id`.
3. **Features API** - call the Features API with your `analysis_id` to retrieve model-ready ML features, automatically scoped and filtered to your location.
4. **Events API** - use the Events API with your `analysis_id` to retrieve the specific events driving demand - for explainability and operational context.

The [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) shows the full recommended architecture, including refresh cadence and data storage patterns.

## What to do next

**I want to build a demand forecasting model** → Start with [Saved Locations](https://docs.predicthq.com/api/saved-locations/overview), then run [Beam](https://docs.predicthq.com/api/beam/overview), then call the [Features API](https://docs.predicthq.com/api/features/get-features) with your `analysis_id`

**I want event-driven forecasts without building a model** → Go straight to the [Forecasts API](https://docs.predicthq.com/api/forecasts/overview)

**I want to connect an AI assistant to PredictHQ** → Set up the [PredictHQ MCP server](https://docs.predicthq.com/ai/mcp)

**I want to understand the full integration architecture** → Read the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern)


# Tutorials

Tutorials teach by doing: a fixed path with sample data, where we ran every step against the live API before publishing and you finish with a result you produced yourself. No prior PredictHQ knowledge is assumed - a free trial account is enough. Start with this tutorial:

* [Measure the forecast lift on sample data](https://docs.predicthq.com/getting-started/tutorials/measure-the-forecast-lift) - build the recommended integration end to end and finish with a measured accuracy improvement, in about 15 minutes.

Already know what you're building? The [guides](https://docs.predicthq.com/getting-started/guides) cover specific tasks, and [How to use PredictHQ](https://docs.predicthq.com/getting-started/how-to-use-predicthq) routes you to the recommended path for your job.


# Measure the forecast lift on sample data

Build the recommended PredictHQ integration on sample demand data - Saved Location, Beam, model-ready features - and finish with a measured forecast accuracy improvement you produced yourself.

In this tutorial you build the recommended PredictHQ integration end to end, on sample demand data, and finish with a measured accuracy improvement you produced yourself. Along the way you see each piece of the platform do its job: a Saved Location scopes the geography, Beam identifies which events drive the demand, the Features API returns the model-ready features your forecasting model would consume, and a baseline comparison measures what the event features are worth.

It takes about 15 minutes, most of which is waiting for two short processing runs. We ran every step in this tutorial against the live API before publishing - the responses you see come from those runs. The tutorial follows this flow:

```mermaid
flowchart LR
    A["1-Create a<br>Saved Location"] --> B["2-4 Create a Beam Analysis<br>and upload sample demand"]
    B --> C["5 Feature Importance:<br>what drives demand"]
    C --> D["6 Features API:<br>the model-ready table"]
    C --> E["7 Baseline comparison:<br>the measured lift"]
    E --> F["8 Explainability:<br>the events behind it"]
```

## Before you start

You need:

* A PredictHQ account and API token - a free trial account has access to everything this tutorial uses. See the [API quickstart](https://docs.predicthq.com/getting-started/api-quickstart) to create a token.
* Python with the `requests` library (any recent version), or the HTTP client of your choice - every step is a plain HTTP call.
* The retail sample dataset: in your working directory, download [`tutorial_demand_retail.csv`](https://raw.githubusercontent.com/predicthq/gitbook-tech-docs/main/assets/tutorials/measure-the-forecast-lift/tutorial_demand_retail.csv). It contains 18 months of synthetic daily demand for a fictional retail store, modeled on realistic patterns - including holiday closures and demand spikes. This file is fixed for this tutorial so your responses match the ones shown; the [sample datasets](https://docs.predicthq.com/getting-started/guides/beam-guides/sample-demand-data) for each industry are refreshed regularly, so results from them will differ from this tutorial's.

To use your token in every step, set it once:

```python
import requests

TOKEN = "YOUR_API_TOKEN"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}
```

## Step 1: Create a Saved Location

The tutorial's fictional store is on Lower Broadway in Nashville - a district dense with concerts and live events, chosen so the event effect is easy to see. Create a Saved Location for it, supplying only the origin point and the industry - PredictHQ calculates a Predicted Impact Area automatically, the boundary where events actually affect a retail location there. Don't supply a radius: fixed circles include irrelevant events and miss relevant ones. Create the Saved Location:

```python
response = requests.post(
    "https://api.predicthq.com/v1/saved-locations",
    headers=HEADERS,
    json={
        "name": "Tutorial - Nashville Broadway Retail",
        "industry": "retail",
        "origin_geojson": {
            "type": "Feature",
            "geometry": {"type": "Point", "coordinates": [-86.7775, 36.1612]},
        },
    },
)
location_id = response.json()["location_id"]
print(location_id)  # a short ID like "rfiTpN63KVbeuyZemz0zog"
```

Keep the `location_id` - everything else in this tutorial hangs off it.

## Step 2: Create a Beam Analysis

Beam is PredictHQ's relevancy engine: it analyzes your demand data to determine which event categories materially drive demand at this location. Create an Analysis linked to your Saved Location:

```python
response = requests.post(
    "https://api.predicthq.com/v1/beam/analyses",
    headers=HEADERS,
    json={
        "name": "Tutorial - Nashville Broadway Retail",
        "location": {"saved_location_id": location_id},
        "demand_type": {"industry": "retail", "interval": "day", "unit_descriptor": "Sales"},
    },
)
analysis_id = response.json()["analysis_id"]
print(analysis_id)
```

## Step 3: Upload the sample demand data

To give Beam the data it correlates against real-world events, upload the CSV to the Analysis:

```python
with open("tutorial_demand_retail.csv", "rb") as f:
    response = requests.post(
        f"https://api.predicthq.com/v1/beam/analyses/{analysis_id}/sink",
        headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "text/csv"},
        data=f,
    )
print(response.status_code)  # 202 - accepted for processing
```

## Step 4: Wait for Beam to finish

Beam decomposes the demand series and runs feature importance testing. On this dataset it takes about two minutes:

```python
analysis = requests.get(
    f"https://api.predicthq.com/v1/beam/analyses/{analysis_id}", headers=HEADERS
).json()
print(analysis["readiness_status"])  # "pending" while processing, "ready" when complete
```

Run it again until it prints `ready`. If it prints `failed`, or is still `pending` well past five minutes, print the whole `analysis` object - `readiness_checks` reports what the data validation found.

Once it's ready, two things worth noticing in the full `analysis` object:

* `rank` shows Beam set a Local Rank threshold for this location itself - you didn't configure one, and you shouldn't. Manual thresholds override location-specific calibration.
* `readiness_checks` notes four missing dates in the sample data - Thanksgiving and Christmas, when the store was closed. Real demand data has gaps like these, and Beam handles them.

## Step 5: See what drives demand - and what doesn't

Retrieve Beam's Feature Importance results:

```python
response = requests.get(
    f"https://api.predicthq.com/v1/beam/analyses/{analysis_id}/feature-importance",
    headers=HEADERS,
)
for group in response.json()["feature_importance"]:
    print(f'{group["feature_group"]:18} p={group["p_value"]:<8} important={group["important"]}')
```

When we ran this, Beam found eight event groups significant for this location - concerts, conferences, public holidays, performing arts, and severe weather all at p-values of zero - and rejected four. Look at what it rejected:

```
sports             p=0.9999   important=False
```

Sports events don't drive this store's demand - in Nashville, home of the Titans and the Predators. This is the point of Beam: the categories a person would guess into a model aren't necessarily the ones the demand data supports, and every irrelevant category included adds noise. Your own demand data decides, not intuition.

## Step 6: Retrieve the model-ready features

This is the artifact an enterprise integration is built around. Call the Features API with the `beam.analysis_id` - nothing else. It applies the calibrated location boundary, the significant categories from step 5, and the rank thresholds automatically:

```python
response = requests.post(
    "https://api.predicthq.com/v1/features/",
    headers=HEADERS,
    json={
        "beam": {"analysis_id": analysis_id},
        "active": {"gte": "2026-04-01", "lte": "2026-04-24"},
    },
)
print(response.json()["results"][0])
```

The response contains one row per day - 24 in total for this window. The first row from our run:

```json
{
  "date": "2026-04-01",
  "phq_attendance_concerts_retail": {"stats": {"sum": 3561}},
  "phq_attendance_conferences_retail": {"stats": {"sum": 1137}},
  "phq_attendance_performing_arts_retail": {"stats": {"sum": 0}},
  "phq_impact_academic_exam": {"stats": {"sum": 0}},
  "phq_impact_observances_retail": {"stats": {"sum": 0}},
  "phq_impact_public_holidays_retail": {"stats": {"sum": 12}},
  "phq_impact_school_holidays_retail": {"stats": {"sum": 0}},
  "phq_impact_severe_weather_cold_wave_retail": {"stats": {"max": 0}},
  "phq_impact_severe_weather_cold_wave_storm_retail": {"stats": {"max": 0}},
  "phq_impact_severe_weather_flood_retail": {"stats": {"max": 0}},
  "phq_impact_severe_weather_tornado_retail": {"stats": {"max": 0}}
}
```

Each row is a date with one value per Beam-selected feature: Predicted Attendance sums for the significant attendance categories, impact values for holidays and severe weather. Scan forward two rows and Friday 2026-04-03 jumps out: 19,290 predicted concert attendees against Wednesday's 3,561 - exactly the kind of swing a model can't see in demand history alone. In production, you join this table to your demand history to train your model, then call the same endpoint with a **future-dated** window at every forecast run - the events behind these features are announced and scheduled in advance, so a future window carries known signals about what's coming rather than extrapolations of your history. That training-and-serving loop lives in your ML pipeline and is out of scope here; the [Features API reference](https://docs.predicthq.com/api/features/get-features) covers the window mechanics, and the [demand forecasting notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/demand-forecasting-with-event-features.ipynb) shows a worked ML example.

## Step 7: Measure what the features are worth

You could stop here and take the feature table into your own model - in production, that's exactly what happens. But you don't need to build a model to measure the lift. The Forecasts API can train two models on your uploaded demand - one enhanced with PredictHQ features, one baseline without them - and report the accuracy difference. To train both models, run the following code. It creates a model with `generate_baseline` enabled, uploads the same CSV, and starts training:

```python
import csv

response = requests.post(
    "https://api.predicthq.com/v1/forecasts/models",
    headers=HEADERS,
    json={
        "name": "Tutorial - Nashville Broadway Retail",
        "location": {"saved_location_id": location_id},
        "demand_type": {"industry": "retail", "interval": "day"},
        "forecast_window": "7d",
        "generate_baseline": True,
    },
)
model_id = response.json()["model_id"]

with open("tutorial_demand_retail.csv") as f:
    demand = [{"date": row["date"], "demand": float(row["demand"])} for row in csv.DictReader(f)]

response = requests.post(
    f"https://api.predicthq.com/v1/forecasts/models/{model_id}/demand",
    headers=HEADERS,
    json={"demand": demand},
)
print(response.status_code)  # 201 - demand data stored

response = requests.post(
    f"https://api.predicthq.com/v1/forecasts/models/{model_id}/train", headers=HEADERS
)
print(response.status_code)  # 204 - training started
```

Training takes two to three minutes. Check the model until `readiness.status` prints `ready` (if it prints `failed`, the `readiness` object explains why), then read both models' error metrics:

```python
response = requests.get(
    f"https://api.predicthq.com/v1/forecasts/models/{model_id}", headers=HEADERS
)
model = response.json()["model"]
print(model["readiness"]["status"])
print(model["metrics"]["accuracy"])
print(model["metrics"]["baseline_comparison"])
```

From our run:

```json
{
  "accuracy": {"mape": 9.37, "mae": 3661.25, "rmse": 5963.11, "wape": 8.62},
  "baseline_comparison": {"mape_improvement_pct": 26.52, "baseline_mape": 12.75, "baseline_mae": 4415.23, "baseline_rmse": 7169.4, "baseline_wape": 10.39}
}
```

The enhanced model's error (MAPE 9.37) beat the baseline (12.75) - a 26.5% improvement, and a like-for-like comparison on the same demand data attributes the difference to the event features.

Don't read that number as a benchmark. This store sits in a deliberately event-exposed district, and the demand data is synthetic - the result demonstrates the measurement workflow, not a claim about your business. When we ran this exact workflow on the same demand data at other locations, the measured lift ranged from about 1% to 26%: event exposure is a property of the location. That's the point of measuring instead of assuming - this workflow tells you what events are worth at your locations, on your own demand data.

## Step 8: See the events behind the forecast

The lift has names. Retrieve the forecast with explainability - and note the date range: the sample data ends on 2026-04-24, so the forecast covers the week after that. Without an explicit date range this endpoint defaults to today onward and returns nothing:

```python
response = requests.get(
    f"https://api.predicthq.com/v1/forecasts/models/{model_id}/forecast",
    headers=HEADERS,
    params={
        "date.gte": "2026-04-25",
        "date.lte": "2026-05-01",
        "include": "phq_explainability",
    },
)
for day in response.json()["results"]:
    events = day.get("phq_explainability", {}).get("events") or []
    top = max(events, key=lambda e: e.get("local_rank") or 0, default=None)
    print(day["date"], round(day["forecast"]), "-", top["title"] if top else "no events")
```

From our run:

```
2026-04-25 48119 - Ben Rector with Nashville Symphony
2026-04-26 43662 - Hayley Williams
2026-04-27 40102 - Snarky Puppy
2026-04-28 37587 - Severe Thunderstorm
2026-04-29 37158 - Hayley Williams
2026-04-30 39329 - RAYE
2026-05-01 50026 - Spring Exams
```

The demand drivers are real, verifiable events: concerts with Local Ranks in the high 70s and 80s, a severe thunderstorm at Local Rank 86, and university spring exams. Every forecast traces back to observable real-world activity - the same explainability your operators and stakeholders get in production.

## Clean up

The tutorial resources are yours to keep exploring with, or delete them:

```python
requests.delete(f"https://api.predicthq.com/v1/forecasts/models/{model_id}", headers=HEADERS)
requests.delete(f"https://api.predicthq.com/v1/beam/analyses/{analysis_id}", headers=HEADERS)
requests.delete(f"https://api.predicthq.com/v1/saved-locations/{location_id}", headers=HEADERS)
```

## What you built

You ran the recommended integration workflow end to end: a Saved Location with an automatically calibrated Predicted Impact Area, a Beam Analysis that identified which event categories drive this demand (and which don't), the model-ready feature table your own forecasting model would consume, and a measured, like-for-like accuracy comparison. What that measurement is worth is relative to the business: at enterprise scale, even a fraction of a percent less forecast error can mean millions of dollars in better staffing, inventory, and pricing decisions.

With your own demand data, the path is identical - one Saved Location and one Beam Analysis per location, refreshed monthly. To run it again closer to home first, pick [your industry's sample dataset](https://docs.predicthq.com/getting-started/guides/beam-guides/sample-demand-data) and change the `industry` value (steps 1, 2, and 7), the file name (steps 3 and 7), and the date windows (steps 6 and 8) to fit the dates in your file. Your results will differ from the ones shown here.

## Where to go next

Continue with these pages:

* [How to use PredictHQ](https://docs.predicthq.com/getting-started/how-to-use-predicthq) - the recommended path for your job, from model training to grounding AI systems
* [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) - the production architecture: local feature storage, refresh cadences, explainability
* [Which API should I use?](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use) - per-task API selection
* [Using event features with time series foundation models](https://docs.predicthq.com/getting-started/guides/features-api-guides/using-event-features-with-time-series-foundation-models) - if your models are pre-trained rather than trained in-house


# Core concepts

The ideas the rest of the docs build on. If you read nothing else before integrating, read these - most integration mistakes come from skipping them.

Recommended order:

1. [Event-driven demand](https://docs.predicthq.com/getting-started/core-concepts/event-driven-demand) - why real-world events move demand, and the four challenges any integration has to solve
2. [What is Beam?](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam) - the relevancy engine that calibrates everything downstream
3. [What is the Features API?](https://docs.predicthq.com/getting-started/core-concepts/what-is-the-features-api) - model-ready signals instead of raw event aggregation
4. [Which API should I use?](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use) - the right tool per task, including grounding
5. [Data Leakage in Backtesting](https://docs.predicthq.com/getting-started/core-concepts/data-leakage-in-backtesting) - why forward-looking features evaluate honestly

[Guide to protecting PredictHQ data](https://docs.predicthq.com/getting-started/core-concepts/guide-to-protecting-predicthq-data) covers the obligations that come with using the data.

For the recommended path by job - training, grounding, managed forecasts, or demand analysis - start with [How to use PredictHQ](https://docs.predicthq.com/getting-started/how-to-use-predicthq).


# Event-driven demand

Using real-world events to improve forecasting and operational decisions introduces structural challenges around scope, relevance, usability, and trust.

Using real-world events to improve forecasting and operational decisions introduces structural challenges. These challenges are not unique to PredictHQ. Any organization attempting to integrate event data into live systems will encounter them.

They typically surface only after implementation has begun, and they are often underestimated at the start.

There are four recurring problem areas:

* Scope
* Relevance
* Usability
* Trust

Understanding these challenges clarifies why event data alone is insufficient for production use.

## Scope

The first problem is defining where events actually matter.

Event impact is not uniform across geography or industry. A fixed radius may be too wide, introducing noise, or too narrow, missing material demand drivers. Scope is practical, not theoretical. It determines which events are even considered candidates for impact.

In dense urban areas, demand effects may be highly localized. In regional or rural contexts, effects may extend much further. Travel behavior, population density, venue clustering, and industry type all influence how far demand impact travels.

Incorrect scope decisions are easy to make and difficult to unwind. If scope is poorly defined, downstream modeling and feature engineering are compromised.

**How PredictHQ addresses scope:**

* [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area) returns an industry and location-specific boundary calibrated against real demand and event data. Unlike a fixed radius, it accounts for travel behavior, population density, venue clustering, and industry type - returning a polygon or radius that reflects where event-driven demand impact actually occurs.
* The recommended workflow is to use [Saved Locations](https://docs.predicthq.com/api/saved-locations/overview). When you create a location using `origin_geojson` without specifying a `geojson` area, PredictHQ calculates Predicted Impact Area automatically and stores it against that location. You can then reference it by `location_id` across Events, Features, Forecasts, and Beam - without managing the boundary yourself.

## Relevance

Not all events within scope materially affect demand.

Event-driven demand is sparse and heavy-tailed. A small number of events drive large spikes. Others create moderate but consistent lift. Multiple event types may activate simultaneously, representing overlapping real-world activity.

Generic feature selection methods are not designed for this structure. Rare spikes can dominate statistical gain metrics. Overlapping signals can distort attribution. Moderate but real effects can be masked. Feature importance can shift depending on which major events fall inside a training window.

Relevance is not a one-time decision. Demand patterns evolve, event behavior changes, and you must revisit calibration regularly.

**How PredictHQ addresses relevance:**

* The [Beam API](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam) calibrates event impact against your historical demand data.
* Beam isolates true event-driven variability and identifies which event types consistently explain it.
* You can rerun calibration as demand evolves, which keeps relevance current.

This reduces noise and ensures that models learn from materially impactful events rather than statistical artifacts.

## Usability

Individual events are not directly consumable by forecasting models or planning systems.

Events must be transformed into structured, numerical signals that reflect timing, scale, duration, and multi-day effects. Without structured guidance, teams often build bespoke feature engineering pipelines that become difficult to maintain and inconsistent across teams.

Operational systems require deterministic, time-series signals that can be integrated directly into models, dashboards, or AI systems without extensive post-processing.

**How PredictHQ addresses usability:**

* The [Features API](https://docs.predicthq.com/getting-started/core-concepts/what-is-the-features-api) converts events into aggregated, model-ready time-series signals.
* It accounts for multi-day events, lead and lag effects, attendance and spend metrics, and category-level aggregation.
* When used with a Beam Analysis ID, feature outputs reflect demand-calibrated impact.

This replaces custom feature engineering with structured, reproducible API calls.

## Trust

Even statistically accurate models can fail operationally if users do not trust them.

Forecast improvements alone rarely drive adoption. Operational teams want to understand why demand is expected to change.

Trust increases when predicted demand shifts can be linked to observable real-world drivers. Concrete explanations anchored to actual events are often more important than marginal improvements in error metrics.

Trust determines time to value. If users hesitate to act on model outputs, operational impact is delayed regardless of model quality.

**How PredictHQ addresses trust:**

* The [Events API](https://docs.predicthq.com/api/events/search-events) provides structured, verifiable event records that can be surfaced alongside forecasts or model outputs.
* When filtered using a Beam Analysis ID, returned events reflect demand-calibrated impact rather than generic event presence.
* You can therefore tie forecast outputs back to specific real-world drivers.

This linkage between model outputs and real-world context strengthens operational confidence.

## From events to production systems

Successfully using real-world events in production systems requires solving all four challenges:

1. Defining practical impact scope
2. Isolating true event-driven demand
3. Transforming events into model-ready signals
4. Providing explainable links between demand and real-world activity

PredictHQ’s APIs map directly to these challenges:

* Scope: [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area) and [Saved Locations](https://docs.predicthq.com/api/saved-locations/overview)
* Relevance: [Beam API](https://docs.predicthq.com/api/beam/overview)
* Usability: [Features API](https://docs.predicthq.com/api/features/get-features) and [Forecasts API](https://docs.predicthq.com/api/forecasts/overview)
* Trust: [Events API](https://docs.predicthq.com/api/events/search-events) (with calibrated filtering)

These are structural problems. They do not disappear with more data or more sophisticated models. They require deliberate design across data, calibration, and delivery layers.

For the recommended production architecture—showing how Saved Locations, Beam, Features API, and Events API fit together with the right refresh cadence and data storage patterns—see the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern).


# What is Beam?

Beam is PredictHQ’s relevancy engine.

It determines which types of real-world events are materially relevant to your business by analyzing your historical demand data - per location.

Event impact varies by geography, industry, and demand profile. The same event type may drive demand in one location and have little effect in another. Beam quantifies this variability and identifies which event signals consistently explain changes in your demand.

The primary output of Beam is a set of Feature Importance results that define demand-relevant event categories and signals for a specific location.

Beam is available [via API](https://docs.predicthq.com/api/beam/overview) and the PredictHQ WebApp, enabling both automated pipelines and exploratory analysis.

## Why use Beam

Integrating event data into forecasting or operational systems introduces a structural statistical challenge.

Event-driven demand is not evenly distributed. It is sparse and heavy-tailed. A small number of events create large spikes, while others generate moderate but consistent lift. Multiple event features often activate simultaneously, representing the same underlying real-world activity. Impact varies by location, season, and demand profile.

This structure breaks many otherwise sound feature selection approaches.

Generic importance methods optimize for statistical gain. In event-driven data, rare spikes can dominate those metrics and inflate weights. When related event features activate together, importance can be split or misattributed. Moderate but real effects can be masked. Feature rankings can shift materially depending on which major events fall within a training window.

The output may appear statistically valid while becoming unstable and difficult to govern at scale.

Beam exists to address this structure.

It is purpose-built to isolate true event-driven demand impact under sparsity, overlap, and large spikes, and to produce stable, repeatable Feature Importance at the individual location level.

Building an internal pipeline requires taking ownership of this entire problem space - including decomposition, overlap handling, stability monitoring, and ongoing recalibration.

Beam provides a calibrated framework designed specifically for the statistical reality of event-driven demand.

## How it works

Beam identifies which event signals correlate with demand variability - location by location.

High-level flow:

1. Provide historical demand data (e.g. bookings, foot traffic, revenue) for one or more locations.
2. Beam decomposes the time series to isolate residual variability beyond trend and seasonality.
3. It evaluates the relationship between that variability and PredictHQ event features, grouped by attributes such as category (e.g. Concerts, Sports, Conferences).
4. It outputs a ranked list of event feature groups that historically impacted demand.

The result is a location-specific calibration of event impact.

## Inputs and outputs

### Inputs

To run Beam, you’ll need:

* Historical demand data:
  * Aggregated daily or weekly values per location
  * Recommended: 6–12 months minimum
  * Required fields: date, demand
* Saved Location:
  * Provides geographic context for event retrieval
  * When you create it from a lat/lon origin, Saved Locations calculates Predicted Impact Area automatically, and that area defines the geographic scope Beam uses

If historical demand data is unavailable, Beam can provide industry-based approximations. These are less precise than location-specific calibration.

### Outputs

Beam returns:

* Feature Importance rankings:
  * Ranked list of the most relevant features grouped into types (e.g. Concerts, Sports, Conferences).
  * Includes statistical significance metrics
* Beam Analysis ID:
  * You can supply it to the Features API or Events API
  * Applies demand-calibrated filtering automatically

## Best practices

When you use Beam, follow these practices:

* **Run Beam before building forecasts** - Identify high-impact event types first, then incorporate those signals into your models.
* **Calibrate per meaningful segment** - Impact varies by location, brand, and concept. Avoid over-fragmentation (e.g. SKU-level) unless supported by sufficient data. We’ve found the best results come from grouping by:
  * Location
  * Brand or concept (e.g. premium vs budget)
  * Product group level (e.g. room types, product categories) - rather than individual SKUs
* **Use Beam Analysis IDs across APIs** - Apply the same calibration consistently when retrieving features or events.
* **Re-run Beam regularly** - Event dynamics evolve. We recommend monthly recalibration for most use cases.

## How Beam integrates with other APIs

Beam enhances other APIs by applying demand calibration to event selection.

### Features API

In your Features API request, use the `beam.analysis_id` to:

* Automatically apply Feature Importance filtering
* Filter down to the most relevant features (e.g. specific categories, rank thresholds, attendance ranges)
* Use the associated Saved Location context

This ensures model inputs reflect calibrated event impact.

### Events API

To apply calibrated filters, use the `beam.analysis_id` parameter:

* Apply category and rank filters derived from calibration
* Restrict results to demand-relevant events
* Maintain consistency with feature generation

### Forecasts API

When using the Forecasts API:

* Beam runs automatically during forecast creation
* Feature selection is based on calibrated event impact
* No manual feature filtering is required

This keeps forecast inputs aligned with historical demand drivers.

## Common pitfalls

Avoid these mistakes:

* **Skipping Beam entirely** - Leads to unstable feature sets and noise.
* **Including all event categories** - More features does not imply better performance.
* **Reusing one Beam Analysis across dissimilar locations** - Impact varies by geography and demand profile.

## Related

For more information, see:

* [Beam API Reference](https://docs.predicthq.com/api/beam/overview)
* [Features API Reference](https://docs.predicthq.com/api/features/get-features) (Beam uses this under the hood)
* [Forecasts API Reference](https://docs.predicthq.com/api/forecasts/overview) (Forecasts uses Beam under the hood)
* [Beam guides](https://docs.predicthq.com/getting-started/guides/beam-guides)

## What to do next

After running Beam, use the Beam Analysis ID with the Features API or Events API to retrieve demand-calibrated signals. For automated forecasting, use the Forecasts API, which applies Beam internally.

For the recommended production architecture, including how Beam fits into a full pipeline with refresh cadence and data storage patterns, see the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern).


# What is the Features API?

The Features API transforms real-world events into structured time-series signals for forecasting, analytics, and other time-dependent models.

Instead of returning individual event records, it produces daily or weekly numerical aggregates grouped by event type (e.g. Concerts, Sports, Public Holidays). Aggregations incorporate Predicted Attendance, Predicted Impact Patterns, spend estimates, and ranking metrics.

Outputs are deterministic, time-aligned feature series scoped to a specific location and date range.

{% hint style="success" %}
**Why use the Features API?**\
We've built up years of expertise in transforming real-world events into meaningful demand signals. Across industries, we’ve consistently seen that naïve aggregation produces noise rather than uplift. The Features API encapsulates that experience - delivering proven, engineered signals that improve forecast accuracy without the heavy lifting.
{% endhint %}

## Why the Features API exists

Individual events are not directly usable in forecasting models.

Correlating demand against individual events also runs into sparsity: a single event's spike rarely gives enough data points to prove anything. Aggregating by category at a daily level gives models the volume of observations that correlation requires.

Events vary in duration, scale, timing, and expected impact. Multi-day events introduce lead and lag effects. Attendance and spend signals must be aggregated consistently. Overlapping events must be handled without distortion.

Naïve aggregation often introduces noise.

The Features API standardizes how event data is transformed into numerical demand indicators. It encapsulates handling of:

* Multi-day event duration
* Lead and lag impact patterns
* Attendance and spend aggregation
* Rank-based filtering
* Category-level grouping

This replaces bespoke event feature engineering pipelines with consistent API outputs.

## What the Features API does

The Features API:

* Aggregates event metrics by category and date
* Distributes attendance across multi-day spans
* Applies Predicted Impact Patterns
* Supports rank-based and attendance-based filtering
* Returns daily or weekly feature values

For example, on a single future day in Sydney, a major sports game, a street fair, a film festival, and an orchestra performance might combine to an aggregate Predicted Attendance of 150,000 across 100 or more events - returned as one model-ready number per category, per day.

It does not determine which features are relevant to your business. Beam handles relevance calibration. The Features API focuses on transforming scoped events into structured numerical signals.

## How it works with Beam

Using a `beam.analysis_id` is the most reliable way to configure the Features API.

When provided, the API:

* Uses the associated Saved Location
* Applies demand-calibrated feature selection
* Enforces category and rank filters derived from Beam

Without Beam, you must define the feature configuration manually.

## Inputs and outputs

### Inputs

The easiest and most reliable way to use the Features API is by providing a `beam.analysis_id`. This automatically applies:

* The correct location and timezone
* A precomputed set of relevant features (from Beam Feature Importance)
* Optimal rank and category filters

Using a `beam.analysis_id` removes the need to manually define your location and feature configuration - it ensures you’re only using features that matter.

If you’re not using Beam, you can also configure inputs manually:

* Location
  * Provide a `saved_location_id` (recommended), `place_id`, or geolocation + radius.
* Time range
  * Start and end date, aligned to local timezone.
* Features to compute:
  * Choose from the full list of available features.
  * Some features have industry-specific variants that use your industry’s Predicted Impact Patterns to better reflect lead/lag behavior.
* Stat types (per feature)
  * For each feature, choose which statistics to compute.
* Granularity
  * Day or week intervals
* Optional filters
  * Filter events included in each feature using `phq_rank` or `local_rank`.

### Outputs

The Features API returns a time series of feature values for each date (or week) in your request, aligned to the timezone of the location.

Each feature includes statistics or level counts depending on the field, in JSON (best for programmatic use) or CSV (best for spreadsheets and BI tools). We designed both formats for downstream use with no extra post-processing. For the exact field structure, column-naming pattern, and available stats, see the [Features API reference](https://docs.predicthq.com/api/features/get-features).

## Best practices

To get the most value from the Features API and avoid noisy or misleading results, follow these practices:

* Use a `beam.analysis_id` whenever possible - This ensures you’re using only features that have proven impact on your business, and saves time configuring filters manually.
* Use `saved_location_id` to define locations - Saved Locations are the most robust way to reference geographies in PredictHQ. They allow consistent use across Beam, Features API, Events API, and Forecasts API.
* Use Predicted Impact Area to define location scope - Predicted Impact Area provides an industry and location-specific boundary calibrated against real demand and event data. The recommended approach is to create a Saved Location using `origin_geojson`, which automatically calculates and stores the Predicted Impact Area - you can then reference it by `location_id` without managing the boundary yourself.
* Segment by meaningful business unit or location - You’ll get the best results when your Beam Analysis and/or Features API requests are scoped to consistent demand signals e.g. a single store, hotel, area, or a product grouping. Avoid going too small (e.g. individual SKUs) or too large (e.g. entire countries or multi-state regions), as the Features API is not designed for large or fragmented geographies.
* Choose the right granularity for your model - Daily granularity works well for high-frequency decisions like staffing or delivery. Weekly works better when individual day fluctuations are less meaningful.
* Filter by event impact - Use thresholds on `phq_rank` or `local_rank` to avoid cluttering your signals with low-impact events.
* Re-run Beam regularly - Event-driven demand patterns shift. We recommend re-running Beam monthly to keep your Feature Importance results fresh and relevant.

## Common pitfalls

Avoid these common pitfalls:

* **Requesting too many features** - Pulling every available feature increases noise and reduces model performance. Use Beam or a curated set of relevant features.
* **Skipping Predicted Impact Area** - Manually defined boundaries often miss key events or include irrelevant ones. Use Predicted Impact Area for each location and industry, ideally via Saved Locations.
* **Too broad or too narrow location scopes** - Very large areas (e.g. states, countries) or very small units (e.g. SKUs) dilute signal. Use Features API for city/suburb/store-scale use cases.

## Related

Related resources:

* [Features API Reference](https://docs.predicthq.com/api/features/get-features)
* [What Is Beam?](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam)
* [Features API guides](https://docs.predicthq.com/getting-started/guides/features-api-guides)

## What to do next

Continue with these steps:

1. [Run Beam](https://docs.predicthq.com/api/beam/overview) (if you haven’t already) - Identify which event features actually drive demand for your business. This gives you a focused feature set to use with the Features API.
2. Set up [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area) - Define the optimal impact boundary for your location and industry. The easiest way is via [Saved Locations](https://docs.predicthq.com/api/saved-locations/create-a-saved-location), which calculates and stores it automatically.
3. Set up [Saved Locations](https://docs.predicthq.com/api/saved-locations/overview) - Define your key business locations once and reuse them across PredictHQ APIs for consistency and easier re-analysis.
4. Make your first [Features API](https://docs.predicthq.com/api/features/get-features) request - To pull a clean time series of impactful event features for your model, use your beam.analysis\_id or saved\_location\_id.
5. See how it fits together in production - The [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) shows how Saved Locations, Beam, the Features API, and the Events API connect as a pipeline, with the right refresh cadence and data storage patterns.
6. Need help? - Check out [Features API guides](https://docs.predicthq.com/getting-started/guides/features-api-guides) or contact support for help tuning your request.


# Which API should I use?

PredictHQ has four core APIs, plus the PredictHQ MCP server for AI assistants and agents. Choosing the right one for each task is the most important decision in any integration - using the wrong API is the most common source of unnecessary complexity and poor results.

## The short answer

| Goal                                                  | API                                                                                                               |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Train or improve a demand forecasting model           | [Features API](https://docs.predicthq.com/api/features/get-features) with `beam.analysis_id`                      |
| Get event-driven forecasts without building a model   | [Forecasts API](https://docs.predicthq.com/api/forecasts/overview)                                                |
| Understand which events are driving demand            | [Events API](https://docs.predicthq.com/api/events/search-events) with `beam.analysis_id`                         |
| Augment an existing forecast with event-aware outputs | [Forecasts API](https://docs.predicthq.com/api/forecasts/overview)                                                |
| Build a dashboard showing upcoming events             | [Events API](https://docs.predicthq.com/api/events/search-events)                                                 |
| Explain a forecast spike to a stakeholder             | [Events API](https://docs.predicthq.com/api/events/search-events)                                                 |
| Identify which event types drive demand at a location | [Beam API](https://docs.predicthq.com/api/beam/overview)                                                          |
| Ground an LLM or agent inside your own environment    | [Events API](https://docs.predicthq.com/api/events/search-events) synced to a local store (provisioned grounding) |
| Give an AI agent on-demand access to verified context | [MCP server](https://docs.predicthq.com/ai/mcp) (on-demand grounding)                                             |

## Features API - for forecasting and ML

Use the Features API when you are building or improving a demand forecasting model, integrating event signals into an ML pipeline, or generating event-driven inputs for staffing, pricing, or inventory decisions.

The Features API produces pre-engineered, attendance-weighted, duration-adjusted, impact-pattern-aware time-series signals. It encapsulates years of domain expertise in transforming raw event data into reliable demand signals. Do not attempt to replicate this by querying the Events API and aggregating manually - naive aggregation introduces noise and degrades model performance.

**Always use `beam.analysis_id`** when calling the Features API. Without it, you must configure feature selection manually - which is error-prone and produces worse results. To use it:

1. Run Beam.
2. Pass the resulting `analysis_id` to the Features API.

{% hint style="warning" %}
The Events API is not a substitute for the Features API in forecasting pipelines. Looping over events, counting them per day, and using that count as a model feature is a common mistake that degrades forecast accuracy.
{% endhint %}

Related resources:

* [Features API Reference](https://docs.predicthq.com/api/features/get-features)
* [What is the Features API?](https://docs.predicthq.com/getting-started/core-concepts/what-is-the-features-api)

## Forecasts API - for ready-to-use event-driven forecasts

Use the Forecasts API when you want accurate, event-driven demand forecasts without building and maintaining your own forecasting model, or when rapid time-to-value is the priority.

The Forecasts API accepts your historical demand data, trains a model, and returns daily-level forecasts with event impact built directly into the output. The Forecasts API applies Beam automatically, so you don't need to configure feature selection manually. The output includes a baseline comparison metric so you can measure the MAPE improvement attributable to PredictHQ data.

The Forecasts API is appropriate whether you are starting from scratch or augmenting an existing forecast. Use it when reducing development time and complexity matters more than owning the underlying model. For teams that require full control over model architecture and feature engineering, the Features API is the recommended alternative.

Related resources:

* [Forecasts API Reference](https://docs.predicthq.com/api/forecasts/overview)
* [Getting started with Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/getting-started)

## Events API - for discovery and explainability

Use the Events API when a user or system needs to see specific individual events - for explainability, dashboards, operational context, or event discovery.

The Events API is for understanding what is happening and why demand shifted on a given day. It is the right tool for surfacing event context alongside forecast results, drilling into which events drove a demand spike, or building an interface that lets operators see upcoming events at their locations.

Use the Events API with `beam.analysis_id` to automatically filter results to the event categories and rank thresholds that are relevant for a given location - the same calibration applied by the Features API.

The Events API is not designed for generating model inputs. Do not loop over events, count them per day, and use those counts as features.

Related resources:

* [Events API Reference](https://docs.predicthq.com/api/events/search-events)

## Beam - for demand calibration

Beam is not a data retrieval API - it is PredictHQ's relevancy engine, which tells you which event types drive demand at each of your locations.

Run Beam before building forecasts or configuring the Features API. The `analysis_id` Beam produces is the key input to both the Features API and Events API, automatically applying the correct location boundary, event category filters, and rank thresholds.

Run Beam once per location and refresh it monthly. It is required for any integration that uses the Features API. For more detail, see:

* [Beam API Reference](https://docs.predicthq.com/api/beam/overview)
* [What is Beam?](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam)

## MCP server - for grounding AI assistants and agents

Use the MCP server when an AI assistant or agent needs verified real-world context on demand - on-demand grounding. It exposes the full API surface through tool calling with the same entitlements as the REST API, and there is no data pipeline to maintain.

To ground AI systems inside your own environment instead (provisioned grounding), sync the Events API into a local store and retrieve from it at answer time - the same store the Standard Integration Pattern uses for explainability.

The MCP server is the grounding path, not the bulk path: for training-scale feature retrieval, use the Features API directly.

Related resources:

* [MCP server](https://docs.predicthq.com/ai/mcp)
* [Grounding with PredictHQ](https://docs.predicthq.com/ai/grounding-with-predicthq)

## Common mistakes

Avoid these common mistakes:

* **Using the Events API for ML features** - The Events API returns individual event records. Aggregating these manually introduces errors in multi-day event handling, lead/lag effects, and rank filtering. Use the Features API instead.
* **Skipping Beam** - Without Beam, you must configure feature selection in the Features API manually. This is error-prone and produces feature sets that are not calibrated to your actual demand patterns.
* **Calling Features API without `beam.analysis_id`** - Without a Beam Analysis, you must manually specify location, features, and rank thresholds. This is valid for early exploration but should not be used in production.

## See also

Related pages:

* [How to use PredictHQ](https://docs.predicthq.com/getting-started/how-to-use-predicthq) - the recommended integration paths, by job
* [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) - how all four APIs fit together in a production architecture
* [API quickstart](https://docs.predicthq.com/getting-started/api-quickstart) - make your first API call
* [Glossary](https://docs.predicthq.com/getting-started/glossary) - definitions for all core concepts


# Data leakage in backtesting: why it doesn't affect forecast accuracy

Real-world events change. A concert gets postponed, a festival is canceled, a venue changes, an attendance estimate gets refined as an event gets closer. Because PredictHQ continuously enriches event records with the latest available information, some customers evaluating PredictHQ ask a reasonable question: **if the event data underlying a feature can change over time, does that mean historical training data contains information that wouldn't have been available at the time, and would that make backtesting results overstate what we'll see in production?**

This is often described as a "data leakage" concern. This page explains what's actually happening, why it's not the leakage it first appears to be for the vast majority of forecasting use cases, and the evidence behind that conclusion.

## The concern, in more detail

Sophisticated forecasting teams building their own models on top of PredictHQ features typically want one guarantee above all: that a feature value pulled today for a historical date reflects only what would have been knowable *at the forecast point*, with no information from after that point mixed in.

The worry usually comes from two observations:

* **PredictHQ updates event records over time.** PredictHQ refines Predicted Attendance, tracks cancellations and postponements, and corrects details as an event approaches or passes.
* **Pulling the same historical feature twice, months apart, can return a different value**, because PredictHQ has updated the underlying event data in the meantime.

If those updates were bleeding *future* information into a *past* forecast point, that would be true data leakage, and it would make backtest accuracy an unreliable stand-in for production accuracy. It's a fair thing to check.

## Point-in-time features vs. true leakage

There's an important distinction between two kinds of change:

* **Changes that happen before your forecast horizon starts.** If you're forecasting five weeks out, and PredictHQ refines an event's attendance estimate four months before the event, both your backtest and your production run would have seen a similarly mature version of that data at the point you actually generate the forecast. This isn't leakage—it's PredictHQ's data getting more accurate over time, the same way it would in production.
* **Changes that would only be known&#x20;*****after*****&#x20;your forecast point.** This is the scenario that would matter: if a feature used to build a training example for a five-week-out forecast only became available two weeks before the event, that's information your production model would never have had at decision time.

Because most events enter PredictHQ's system well ahead of when they happen—commonly three to six months out, and often longer—the updates that follow (postponements, cancellations, attendance refinements, venue changes) are, in practice, absorbed well before most customers' forecast horizons begin. The dynamic nature of real-world events is expected and continuous; the question that actually matters is whether that continuous refinement changes the forecast accuracy you experience, at the horizon you actually operate on.

That's an empirical question, and we set out to answer it directly rather than argue it in the abstract.

## What we measured

We ran an internal study—Backtesting Resiliency—that tracked feature values for the same locations and dates across many weekly snapshots over time, and used those snapshots to compare forecast accuracy computed from "if we'd forecast at this horizon" feature values against the accuracy computed from today's fully up-to-date values. The analysis covered several hundred locations across the US, UK, and Canada, using daily Absolute Percentage Error (APE) as the accuracy measure.

The result: forecast accuracy is stable across horizons.

| Horizon before event | Typical (median) accuracy shift | Tail (80th percentile) accuracy shift |
| -------------------- | ------------------------------- | ------------------------------------- |
| Six weeks or less    | 0 percentage points             | 0 percentage points                   |
| Seven to eight weeks | 0 percentage points             | \~0.1-0.3 percentage points           |
| Nine to 10 weeks     | 0 percentage points             | \~0.5-0.6 percentage points           |

In other words: at six weeks out or closer, the accuracy you'd measure in a backtest is effectively identical to what today's fully-refined data would show—for the majority of locations, there's no measurable difference at all. A small tail difference only starts to appear beyond seven weeks out, and even then it's modest.

Since the large majority of demand forecasting use cases we see run on horizons of six weeks or less, this means **backtesting results are a reliable guide to production performance for the overwhelming majority of PredictHQ customers.**

## Why individual event updates don't move the needle

It can still feel counterintuitive that individual events change constantly, yet aggregate forecast accuracy barely moves. The reason comes down to aggregation.

Forecasting models don't consume individual event records directly—they consume features that aggregate many events together for a given location, day, and category (for example, total Predicted Attendance across all concerts, sports, and festivals happening near a store on a given day). A single event being postponed, canceled, or having its attendance estimate revised is a small perturbation to one input among many contributing to that aggregate. It rarely shifts the aggregate feature enough to change the resulting forecast in any meaningful way.

Individual event-level details are genuinely dynamic—that's what real-world context looks like. What our results show is that this dynamism, once rolled up into the aggregated features models actually use, doesn't translate into meaningful forecast accuracy drift within the horizons that matter for real forecasting decisions.

## What this means in practice

How you apply these results depends on your forecast horizon:

* **For forecast horizons up to about six weeks** (the majority of demand forecasting use cases): treat backtesting results as a direct, reliable proxy for the accuracy you'll see in production. No special handling of point-in-time snapshots is required.
* **For longer horizons (seven or more weeks out):** the effect is still small, but if you're building a model with a longer lead time and want to validate this for your specific use case, talk to your PredictHQ contact—we can help design a backtest that reflects your exact horizon.
* **You don't need to maintain your own historical snapshot of PredictHQ data** purely to guard against this concern. The dynamic updates you'd be trying to protect against are the same updates that make the data more accurate, and they happen well ahead of the point where they'd affect a typical forecast.

## Frequently asked questions

**Does PredictHQ backtesting reflect what I'll see in production?** Yes, for forecast horizons up to around six weeks—which covers most demand forecasting use cases—our internal analysis found no measurable difference between backtested and production-time accuracy.

**If PredictHQ updates event data after an event happens (e.g. actual attendance), doesn't that leak into my historical training data?** Post-event updates refine PredictHQ's records for future accuracy, but they don't change the features that were available at your forecast point for that event. The relevant question is whether a feature value changed *within* your forecast horizon, not whether PredictHQ later updated it after the event occurred—and our results show that within typical horizons, the two produce effectively the same forecast accuracy.

**Should I snapshot PredictHQ data myself to be safe?** It isn't necessary for the vast majority of use cases. If you have a use case with a long forecast horizon or unusually strict point-in-time requirements, reach out to your PredictHQ contact to discuss options.


# Guide to protecting PredictHQ data

It's important to protect PredictHQ data from unauthorized access and usage.

This guide provides ideas on how to protect PredictHQ’s data from unauthorized usage due to what is known as web scraping or screen scraping, specifically when being used in public facing websites.

Web scraping, web harvesting, or web data extraction is data scraping used for extracting data from websites, which automated tools or bots typically perform. Our terms require customers to protect against unauthorized use of our data including by these techniques so carefully consider how you're exposing PredictHQ data and what protections you have in-place to protect it.

## Technical deterrents and protection

You must use any reasonable endeavors to prevent unauthorized access to, or use of PredictHQ Data and, in the event of any such unauthorized access or use, promptly notify PredictHQ. Reasonable endeavors to prevent web scraping may include any of the following (**but are not limited to**):

### Require authentication to view data

Users must log in, or be approved before using the application. This may help detect legitimate users from automated scripts. It also allows more effective monitoring for (and the ability to take action against) any unwanted activity.

### Application design

Effective application design can make it difficult to scrape information or easier to detect scraping. This includes techniques such as limiting the amount of data returned per search, restricting the area of the search, or requiring pagination of results.

### IP address monitoring, limiting, or blocking

Ability to monitor, alert, and report on website activity by IP address allows for the detection of sudden increases in traffic, outliers, or bad actors. Tracking of an IP address allows for the ability to use a blocklist if needed.

### Use of commercial software to protect public-facing content from bots

Many companies offer fully featured solutions to prevent scraping by bots or automated scripts. The major cloud providers (AWS, Azure, and GCP) offer Web Application Firewall (WAF) solutions. In addition to this there are several stand alone solutions, for example Cloudflare or Fastly. These solutions all provide services that include regularly updated blocklists, automatic bot detection, and bot prevention.

### Traffic monitoring

Monitoring of website traffic through capture and analysis of access logs or similar allows for trend monitoring, the configuration of alerts, and early detection of suspicious activity such as increased traffic volumes.

### Use of captcha challenge-response tests, in particular reCaptcha

Captcha or reCaptcha solutions that attempt to identify legitimate human users can help prevent bot usage. Together with IP tracking, the use of a captcha can be triggered only after certain thresholds are met, or for repeated infringements.

### Correct use of the Robots Exclusion Standards (robots.txt file)

Websites can declare if crawling is allowed or not in the robots.txt file and allow partial access, limit the crawl rate, specify the optimal time to crawl, and more. This can be used to prevent web crawlers from scraping data

### Protect or disable any publicly available APIs

Ensure you implement proper security and access controls for any publicly accessible APIs that your website uses, so that only legitimate usage has access.


# Glossary

Definitions of key terms used across PredictHQ’s platform and APIs. Use as a reference.

## Beam

Beam is PredictHQ's relevancy engine: it identifies which types of real-world events materially impact your historical demand at a specific location.

Event-driven demand is sparse and uneven. A small number of events create large spikes, while others generate moderate but consistent lift. Generic feature importance methods are not designed for this structure and can produce unstable or misleading results.

Beam analyzes your historical demand time series to isolate event-driven variability and quantify which event types consistently explain it. The primary output is a set of Feature Importance results - expressed as an `analysis_id` - that automatically configures Features API and Events API calls to use only the event categories, rank thresholds, and location scope that are relevant for that location. Without Beam, feature selection is a manual guess.

Beam Analyses are location-specific and should never be shared across multiple locations. Event impact varies by geography and demand profile, so one Analysis per location is required.

If you operate many locations with a single shared model, Beam Analysis Groups aggregate Feature Importance results across a set of Analyses to produce a consistent feature set. Use this only when a single model requires identical inputs across locations; individual per-location Analyses are preferable in most cases.

Refresh Beam monthly by appending new demand data to the existing Analysis. Do not delete and recreate Analyses - doing so loses accumulated correlation history.

Related resources:

* API Reference: [Beam](https://docs.predicthq.com/api/beam/overview)
* [Beam guides](https://docs.predicthq.com/getting-started/guides/beam-guides)

## Features API

The Features API transforms real-world events into structured, model-ready time-series signals for demand forecasting and ML pipelines.

Rather than returning individual event records, it produces daily or weekly numerical aggregates grouped by event type—concerts, sports, public holidays, school holidays, and more. Aggregations incorporate Predicted Attendance, Predicted Impact Patterns, spend estimates, and ranking metrics, encapsulating the domain expertise required to turn raw event data into reliable demand signals.

The Features API is the recommended integration surface for any use case involving forecasting, ML, staffing, pricing, or inventory decisions. It should be used in place of querying the Events API and constructing features manually—naive event aggregation introduces noise and degrades model performance.

The recommended way to call the Features API is by passing a `beam.analysis_id`, which automatically applies the correct location, rank filters, and feature selection derived from Beam. Without a `beam.analysis_id`, features must be configured manually, which is error-prone and produces worse results.

Related resources:

* API Reference: [Get ML features](https://docs.predicthq.com/api/features/get-features)
* [Features API guides](https://docs.predicthq.com/getting-started/guides/features-api-guides)

## Forecasts API

The Forecasts API delivers event-driven demand forecasts directly, without requiring you to build or maintain your own forecasting models.

You supply historical demand data for a location. The Forecasts API trains a model, applies Beam to identify which event types drive demand at that location, and returns daily-level forecasts enriched with PredictHQ feature attribution and explainability outputs. A baseline comparison metric is included so you can measure the MAPE improvement attributable to PredictHQ data.

The Forecasts API is appropriate when rapid time-to-value is the priority, or when a team does not have the capacity to build and maintain a bespoke forecasting pipeline. For teams that require full control over the underlying model, the Features API with a `beam.analysis_id` is the recommended alternative.

Related resources:

* API Reference: [Overview](https://docs.predicthq.com/api/forecasts/overview)
* [Getting started with Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/getting-started)

## Grounding

Grounding is giving an LLM or agent the real-world facts it does not hold, at the moment it answers, so it responds from what is true instead of what it guesses. Grounding reduces AI hallucinations. Retrieval-augmented generation (RAG) is the most common technique; tool calling at answer time achieves the same outcome.

Grounding with PredictHQ comes in two architectures: **provisioned grounding** - verified context delivered into your environment, retrieved from a store you govern - and **on-demand grounding** - your agents query the PredictHQ MCP server and hold no copy of anything.

Related resources:

* [Grounding with PredictHQ](https://docs.predicthq.com/ai/grounding-with-predicthq)
* [Provisioned grounding: retrieval inside your environment](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding)
* [MCP server](https://docs.predicthq.com/ai/mcp)

## Inference

Inference is the moment a model is used in a live system to produce a prediction or action. It applies equally to models you train yourself and to pre-trained models applied without training, such as time series foundation models used zero-shot.

Either way, a forecast is only as good as the context the model sees at inference. Events are known in advance, so a Features API call with a forward-dated `active` window supplies future-dated demand signals at every forecast run. For models you train, this is the serving half of the loop: the model learned from PredictHQ features, so it needs them at every scoring run. For pre-trained models, inference is where all the context enters: features covering both the demand history and the forecast horizon are supplied as covariates.

For LLMs and agents, retrieving verified context at inference time is grounding - see [Grounding](#grounding).

## Local Rank

Local Rank is PredictHQ’s location-sensitive ranking score that measures an event’s impact relative to its surrounding population density. It ranges from 0 to 100, and PredictHQ presents it on a logarithmic scale, meaning higher scores represent exponentially greater local impact.

Unlike PHQ Rank, which is normalized globally, Local Rank adjusts for how concentrated or sparse a population is in the area surrounding the event. This means that a 5,000-person event in a densely populated city receives a lower Local Rank than a 5,000-person event in a rural or sparsely populated area - because the latter has a proportionally larger impact on local demand and activity.

Local Rank is most useful for identifying events that are significant in context, such as when optimizing logistics, staffing, or marketing at a local level.

Related resources:

* Getting Started Guide: [Local Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/local-rank)

## Loop

Loop is PredictHQ’s event feedback and contribution tool that allows customers to submit missing events and report incorrect attributes on existing events. It serves as a direct input channel to improve event data quality and completeness.

You can use the Loop UI to provide feedback, or use Loop Links - unique URLs generated via API - to enable distributed teams or frontline staff to contribute feedback without requiring full access to PredictHQ’s WebApp.

PredictHQ’s data team reviews all submitted feedback and integrates accepted changes into the platform, enhancing data accuracy and model performance.

Related resources:

* API Reference: [Loop](https://docs.predicthq.com/api/loop/overview)
* [Loop UI](https://loop.predicthq.com/)

## MCP (Model Context Protocol)

MCP is an open standard for connecting AI assistants and agents to external tools and data at inference time. The PredictHQ MCP server exposes the full API surface (events, features, Beam, forecasts, and documentation search) to any MCP-compatible client, with the same entitlements as the REST API.

The MCP server is PredictHQ's on-demand grounding path: agents query for verified real-world context on demand, with no data pipeline to maintain. For training-scale feature retrieval, use the Features API directly.

Related resources:

* [MCP server](https://docs.predicthq.com/ai/mcp)

## PHQ Labels

PHQ Labels are AI-generated sub-category classification tags applied to events, providing more granular and semantically consistent classification than legacy event labels.

Where legacy labels are manually assigned and inconsistent in coverage, machine learning models trained across the full event catalog generate PHQ Labels, which cover all event categories. They enable more precise filtering - for example, distinguishing a charity run from a marathon within the broader sports category, or a product launch from an industry summit within conferences.

PHQ Labels are available via the `phq_labels` field in the Events API response. They are particularly useful if you need fine-grained event segmentation in demand models or operational dashboards.

Related resources:

* Getting Started Guide: [Labels](https://docs.predicthq.com/getting-started/predicthq-data/labels#phq-labels)

## PHQ Rank

PHQ Rank is PredictHQ’s proprietary global ranking score that quantifies the potential relative impact of an event at a global level. It ranges from 0 to 100. PredictHQ calculates it from a blend of signals such as Predicted Attendance, event type, and contextual features that influence demand.

PredictHQ presents the score on a logarithmic scale, meaning that higher scores represent exponentially more impactful events. For example, an event with a PHQ Rank of 90 is significantly more impactful than one with a score of 80.

Related resources:

* Getting Started Guide: [PHQ Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/phq-rank)

## Predicted Attendance

Predicted Attendance is a machine learning-generated estimate of how many people are expected to attend a given event. This prediction is based on a range of signals, including event attributes, location, timing, historical attendance patterns, and similar events. It is a core event-level metric used across the Events API, Features API, and Forecasts API to quantify potential demand impact.

Related resources:

* Getting Started Guide: [Predicted Attendance](https://docs.predicthq.com/getting-started/predicthq-data/predicted-attendance)

## Predicted End Times

Predicted End Time is a machine learning–generated estimate of when an event is expected to end. PredictHQ calculates it using historical patterns from similar events, event type, scheduled start time, and other contextual features such as venue or location.

Predicted End Time is especially useful when the original event data does not include a defined duration or end timestamp. It helps improve time-based demand modeling and enables better filtering, de-duplication, and overlap handling for events that span long periods.

Related resources:

* Getting Started Guide: [Predicted End Times](https://docs.predicthq.com/getting-started/predicthq-data/predicted-end-times)

## Predicted Event Spend

Predicted Event Spend is a model-generated estimate of the total consumer spend—across accommodation, hospitality, and transportation—expected to occur as a result of a specific event. Values are expressed in United States Dollars (USD).

This feature leverages Predicted Attendance, local accommodation demand, third-party economic indicators, and contextual event metadata to produce an event-attributable dollar value. It represents an approximation of spending activity in the area surrounding the event.

Related resources:

* Getting Started Guide: [Predicted Event Spend](https://docs.predicthq.com/getting-started/predicthq-data/predicted-event-spend)

## Predicted Events

Predicted Events are machine-generated event records that have not yet been scheduled or publicly announced, but are predicted to occur based on historical event patterns, demand signals, and venue activity over multiple years. PredictHQ assigns these events a probability-driven occurrence window (time and location) and surfaces them to support long-range planning and forecasting.

Predicted Events have a distinct `state: predicted` and can be queried via the Events API or surfaced in the WebApp using state filters. If a real event is later scheduled that matches the prediction, PredictHQ updates its state automatically (e.g., to `active`) and adds confirmed details, such as start time. If the predicted event does not materialize, the status may transition to `canceled` or `postponed`.

This feature helps prevent gaps in demand models by preemptively accounting for likely-but-unconfirmed events and is particularly useful in high-volume, lead-time-sensitive use cases.

Related resources:

* Getting Started Guide: [Predicted Events](https://docs.predicthq.com/getting-started/predicthq-data/predicted-events)

## Predicted Impact Area

Most integrations start with a fixed radius when scoping events around a location. The problem is that the distance over which events influence demand varies by industry, location type, and how people actually move in that area - a fixed circle is an approximation that can include irrelevant events and exclude relevant ones.

Predicted Impact Area returns a location and industry-specific boundary that reflects where event-driven demand impact actually occurs. PredictHQ calibrates boundaries against real demand and event data across industries and geographies, and accounts for real-world constraints such as bodies of water, terrain, and road networks.

The recommended approach is to create a Saved Location using `origin_geojson` without specifying a `geojson` area—PredictHQ then calculates the Predicted Impact Area automatically and stores it against the location. The resulting `location_id` can be passed directly to Events API, Features API, Beam, and Forecasts API without needing to manage the boundary separately.

Predicted Impact Area replaces the Suggested Radius API for all new integrations.

Related resources:

* API Reference: [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area)

## Predicted Impact Patterns

Predicted Impact Patterns (previously referred to as Demand Impact Patterns) are event-level time series that quantify the expected distribution of impact across days leading up to, during, and following an event. PredictHQ derives these patterns from machine learning models trained on historical demand data (e.g. accommodation bookings, transport usage) and tailors them by event type and industry vertical.

Rather than assuming all impact occurs on the event date, these patterns reflect real-world lead and lag behavior. For example, accommodation demand for a concert may peak one to two days prior to the event and persist after, reflecting typical visitor behavior. Each pattern provides an array of weighted values across a window of time, allowing temporal alignment of event-driven demand signals.

Predicted Impact Patterns are industry-specific and improve upon static or date-anchored features in demand forecasting models. They improve forecast accuracy by encoding time-aware event impact into supervised learning pipelines.

Related resources:

* Getting Started Guide: [Predicted Impact Patterns](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns)

## Real-world context

Real-world context refers to structured, verified representations of real-world activity that materially influence demand - events, venues, performers, and associated quantitative signals such as Predicted Attendance, spend, rankings, and temporal impact patterns.

Within PredictHQ's platform, real-world context flows through a layered architecture:

* **Events API** - structured and deduplicated event records for discovery and explainability
* **Saved Locations + Predicted Impact Area** - geographic scoping calibrated to where impact actually occurs
* **Beam** - demand calibration to identify which events drive demand at each location
* **Features API** - event signals transformed into model-ready time-series features
* **Forecasts API** - event-aware demand forecasts for customers who do not build their own models
* **Grounding (MCP server + Events API)** - verified context retrieved by AI systems at answer time, from a store inside your environment (provisioned grounding) or on demand via MCP (on-demand grounding)
* [Core concepts](https://docs.predicthq.com/getting-started/core-concepts)

## Saved Location

Saved Location is a persistent, user-defined geographic entity consisting of a name and GeoJSON definition of a location. It may optionally include an external ID and a list of labels for filtering or grouping purposes.

Saved Locations serve as reusable identifiers in PredictHQ’s platform, allowing consistent and simplified access to features, events, and forecasts for specific business locations.

PredictHQ recommends Saved Locations for managing location-specific workflows and ensuring consistent geographic definitions across APIs. They eliminate the need to repeatedly supply raw coordinates and help enforce consistency across automated forecasting and feature generation pipelines.

Related resources:

* API Reference: [Saved Locations](https://docs.predicthq.com/api/saved-locations/overview)

## Suggested Radius

**Deprecated.** Suggested Radius was a PredictHQ API that returned a recommended search radius around a point location for a given industry. PredictHQ replaced it with Predicted Impact Area, which provides a more accurate, data-driven geographic boundary that accounts for real-world geography rather than a fixed circle.

Existing integrations using Suggested Radius continue to work, but new integrations should use Predicted Impact Area via Saved Locations instead.

Related resources:

* See: [Get Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area)

## Time series foundation model

Time series foundation models such as Chronos-2, TimesFM, and TimeGPT are pre-trained forecasting models applied zero-shot or with light fine-tuning, with no per-location model training required. They learn temporal patterns across millions of series, which lowers the cost of deploying forecasts at scale.

What they don't learn is real-world drivers. Generic numeric sequences dominate pre-training corpora, so events, holidays, and severe weather are invisible to these models unless supplied as covariates at inference time. Where the model accepts covariates (Chronos-2, TimeGPT, and TimesFM do; the earlier Chronos and Chronos-Bolt models are univariate), PredictHQ features fill that gap: pass Features API output (keyed by a `beam.analysis_id`) covering both the demand history and the forecast horizon.

As forecasting shifts from bespoke trained models toward pre-trained ones, the training step shrinks and inference-time context matters more, not less.

Related resources:

* API Reference: [Get ML features](https://docs.predicthq.com/api/features/get-features)


# Data science notebooks

Jupyter notebooks for training and improving demand forecasting models with PredictHQ event features—Beam calibration, model-ready features, and worked forecasting examples.

PredictHQ features exist to make forecasts more accurate. Adding event features to a demand forecasting model reduces forecast error in a way you can measure and attribute - and what a point of accuracy is worth is relative to your business: at enterprise scale, even a fraction of a percent less forecast error can mean millions of dollars in better staffing, inventory, and pricing decisions. These Jupyter notebooks show how to capture that lift in your own models: calibrating with Beam, retrieving model-ready features, and training and forecasting with them.

If you're new, work through the forecasting workflow notebooks in order - they follow the recommended path: Beam identifies which event categories drive demand at each location, the Features API turns them into model-ready signals, and your model (or the Forecasts API) does the rest. Before you backtest, read [Data Leakage in Backtesting](https://docs.predicthq.com/getting-started/core-concepts/data-leakage-in-backtesting) so historical evaluation reflects what the model sees in production.

## The forecasting workflow

Work through these notebooks in order:

1. [**ML features by location with Beam**](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/identify-location-level-features-with-beam-api.ipynb) - run Beam per location and use Feature Importance to identify the relevant, forecast-ready features.
2. [**ML features by group with Beam Analysis Groups**](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/identify-group-level-features-with-beam-api.ipynb) - an aggregated feature set across several locations, for a single shared model.
3. [**Get features with the Features API**](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/get-features-with-features-api.ipynb) - retrieve model-ready features at scale, keyed by your Beam Analysis. If your data lives in Snowflake, the [Snowflake data science guide](https://docs.predicthq.com/integrations/third-party-integrations/snowflake/snowflake-data-science-guide) covers building features there instead.
4. [**Demand forecasting with event features**](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/demand-forecasting-with-event-features.ipynb) - incorporate the features into a demand forecasting model. Self-contained: it can be run independently of the other notebooks in this workflow.
5. [**Forecasts API**](https://github.com/predicthq/phq-data-science-docs/blob/master/forecasts-api/demand_forecasting_with_phq_forecasts_api.ipynb) - the managed alternative: train a model and get event-driven forecasts without building your own, with a baseline comparison to measure the lift.

## Exploring event categories

Per-category notebook series for exploring the data itself. Each series has three parts: data engineering (extract to a DataFrame), data exploration, and feature engineering.

### Attendance-based events

Conferences, expos, concerts, festivals, performing arts, sports, and community events - see [Attendance-based events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events) for the category reference. The attendance-based events notebooks are:

* [Attendance-based events, part 1: data engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/attended-events/part_1_data_engineering.ipynb)
* [Part 2: Data Exploration](https://github.com/predicthq/phq-data-science-docs/blob/master/attended-events/part_2_data_exploration.ipynb)
* [Part 3: Feature Engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/attended-events/part_3_feature_engineering.ipynb)

### Non-attendance-based events

Observances, public holidays, and school holidays - see [Non-attendance-based events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/non-attendance-based-events). The non-attendance-based events notebooks are:

* [Part 1: Data Engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/unattended-events/part_1_data_engineering.ipynb)
* [Part 2: Data Exploration](https://github.com/predicthq/phq-data-science-docs/blob/master/unattended-events/part_2_data_exploration.ipynb)
* [Part 3: Feature Engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/unattended-events/part_3_feature_engineering.ipynb)

### Severe weather events

For the category reference, see [Severe Weather](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/unscheduled-events#severe-weather). The severe weather notebooks are:

* [Part 1: Data Engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/severe-weather-events/part_1_data_engineering.ipynb)
* [Severe weather events, part 2: data exploration](https://github.com/predicthq/phq-data-science-docs/blob/master/severe-weather-events/part_2_data_exploration.ipynb)
* [Part 3: Feature Engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/severe-weather-events/part_3_feature_engineering.ipynb)

### Academic events

The academic events notebooks are:

* [Part 1: Data Engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/academic-events/part_1_data_engineering.ipynb)
* [Part 2: Data Exploration](https://github.com/predicthq/phq-data-science-docs/blob/master/academic-events/part_2_data_exploration.ipynb)
* [Part 3: Feature Engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/academic-events/part_3_feature_engineering.ipynb)

### Live TV Events

Broadcast sports viewership by county in the United States - see [Live TV Events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/live-tv-events). The Live TV Events notebooks are:

* [Part 1: Data Engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/live-tv-events/part_1_data_engineering.ipynb)
* [Part 2: Data Exploration](https://github.com/predicthq/phq-data-science-docs/blob/master/live-tv-events/part_2_data_exploration.ipynb)
* [Part 3: Feature Engineering](https://github.com/predicthq/phq-data-science-docs/blob/master/live-tv-events/part_3_feature_engineering.ipynb)

### Venues

Events are linked to the venues they occur at - stadiums, conference centers, concert halls - stored as [entities](https://docs.predicthq.com/getting-started/predicthq-data/entities). A major venue near your location is often a key source of demand. The [venues notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/venues/venues-example.ipynb) covers extracting venue information, mapping venues, event types by venue, and estimated capacities.

You can find all our Data Science Notebooks in our [GitHub repo](https://github.com/predicthq/phq-data-science-docs/tree/master).

For the concepts behind the workflow, see [Which API should I use?](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use) Using a pre-trained forecasting model instead of training your own? See [Using event features with time series foundation models](https://docs.predicthq.com/getting-started/guides/features-api-guides/using-event-features-with-time-series-foundation-models)


# PredictHQ data

What's inside a PredictHQ event record and the predicted attributes layered onto it. These attributes are what make the data usable in models and AI systems: verified events enriched with [Predicted Attendance](https://docs.predicthq.com/getting-started/predicthq-data/predicted-attendance), [Predicted End Times](https://docs.predicthq.com/getting-started/predicthq-data/predicted-end-times), [Predicted Event Spend](https://docs.predicthq.com/getting-started/predicthq-data/predicted-event-spend), [Predicted Impact Patterns](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns), and [rankings](https://docs.predicthq.com/getting-started/predicthq-data/ranks).

To understand what kinds of real-world activity are covered, start with [Event categories](https://docs.predicthq.com/getting-started/predicthq-data/event-categories). To understand how impact is scored, read [Ranks](https://docs.predicthq.com/getting-started/predicthq-data/ranks). [Data accuracy](https://docs.predicthq.com/getting-started/predicthq-data/data-accuracy) covers how the data is verified - the property that grounding and forecasting both depend on.


# Data accuracy

We have a rigorous set of models and algorithms to ensure we’re providing a clean and verified data set. Our machine learning models are working day-in and day-out, which is especially crucial for event data, which is changing all of the time.

Every event in our API goes through multiple steps to ensure quality and accuracy. Some example steps are:

**Standardization:** All events follow the same schema for ease of ingestion, comparability, and compatibility.

**Aggregation:** We pull in events and entities from hundreds of different sources and compare them for quality and accuracy.

**Enrichment:** We categorize, label, and add entities to all events to help reduce noise. We also ensure all events have a date, time, and location.

**Spam Filtering:** Bad data is worse than no data at all. We ensure you only have access to events that are actually happening.

30% to 40% of events we receive are spam, add-ons, or duplicates. After filtering, our spam rate is below 0.1% - our quality-control checks consistently measure it at 0%.

**Geocoding:** Every event has a lat/long, allowing for precise mapping. Events also follow identification patterns from the open source Geonames database. For instance, all events in California have multiple IDs, of which 5332921 (the ID for California) is always included. We also provide venue name and formatted address whenever possible.

**De-duplicating:** We combine duplicate records into one reliable event. E.g. Our system may find a football game with 30,000 expected attendees. It finds eight listings of this game from five different sources. Our unique model kicks in and keeps a single event with the aggregated detail from all of the listings.

**Ranking:** See [PHQ Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/phq-rank) and [Local Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/local-rank) for what goes into our rankings. We track accuracy with a variety of metrics and we’re refining daily. The top metrics we track are: Spam rates, number of duplicated events, location, and competitive comparison.


# Event categories

## Attendance-based events

Events with a start and end date and time. PredictHQ models predict attendances for events in these categories:

* Sports
* Conferences
* Expos
* Concerts
* Festivals
* Performing Arts
* Community
* Academic (certain types of Academic events)

{% content-ref url="/pages/WFED4UUxTtSKsn6qYcuO" %}
[Attendance-based events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events)
{% endcontent-ref %}

## Non-attendance-based events

These are events with a start and end date, but are more fluid in impact, such as observances or school holidays:

* Public Holidays
* School Holidays
* Observances
* Politics
* Daylight Savings
* Academic

{% content-ref url="/pages/xZ4DhqIhnetBwz56rH90" %}
[Non-Attendance-based events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/non-attendance-based-events)
{% endcontent-ref %}

## Unscheduled events

Live coverage of breaking events such as severe weather and terrorism. The API updates minute to minute to ensure accuracy. Categories include:

* Airport Delays
* Severe Weather
* Disasters
* Terror Attacks
* Health Warnings

{% content-ref url="/pages/uoUuuQylOYpxMsz76xAM" %}
[Unscheduled events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/unscheduled-events)
{% endcontent-ref %}

## Live TV Events

Televised events that include seven of the top US leagues and the high viewership sports. PredictHQ is the only source of predicted TV viewership. The category is:

* Live TV Events

{% content-ref url="/pages/EqQlerCDu8rVAW0Qe0Ce" %}
[Live TV events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/live-tv-events)
{% endcontent-ref %}


# Attendance-based events

Attendance-based events are gatherings with a start and end date/time, where people come together in one location for entertainment or business.

## Categories

### Sports

A sports competition consists of multiple players or teams. It has a certain theme or goals with its own rules to regulate and a dedicated environment as well.

#### **Labels**

Labels for a sports event provide more information about the type, league, and environment:

1. **Sports type**

   The most common sports types in PredictHQ dataset are: `soccer`, `basketball`, `ice-hockey`, `rugby`, `baseball`.
2. **Sports league**

   The most popular sports leagues in the PredictHQ dataset are: `NFL`, `MLB`, `NHL`, `NBA`.
3. **Sports games environment**

   The general environment where the sports game is held, or the purpose of the sports game, for example:

   * `closed-doors`: When the sports game has no physical audience in attendance. This is most commonly due to COVID-19 restrictions.
   * `outdoors`: Where the sports game is held in an outdoor area.
   * `fundraise`: A community-related sports game for fundraising purposes.
4. **Youth Sports**:
   * These events have the `youth-sport` label
   * These events cover any sports event where competitors are younger than adult age, whether children or adolescents. Youth sports include school sports at primary and secondary level, as well as sports played outside the education system, whether informally or organized. They do not include colleague sports which are separate and can be cound with the `NCAA` label.
   * Sports covered are youth basketball, baseball, softball, and soccer
   * These events are for the US (with a very small amount in Canada)
   * Youth sports include a dynamic ranking model that predicts attendance and rank based on the type of sport, age group, level, gender, population density, student numbers, and other features

#### Date & time

<table><thead><tr><th width="220.33333333333331">Date &#x26; Time Field</th><th width="158" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td></td></tr><tr><td>Start time</td><td align="center">Yes</td><td>Sports games are expected to have a specific start time.</td></tr><tr><td>End time</td><td align="center">Yes</td><td></td></tr><tr><td><a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-end-times">Predicted End Times</a></td><td align="center">Yes</td><td>For sports events where there is no official end time available, PredictHQ predicts end times using our machine learning models and intelligent algorithms.<br><br>PredictHQ’s Predicted End Times feature provides end times in the <code>predicted_end</code> field. When a Predicted End Time is provided, the event’s end time (in the <code>end</code> field) matches the start time (in the <code>start</code> field).</td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: datetime is in UTC.

#### Location

Sports events are usually point events, meaning the latitude and longitude of the event represent the location of the event’s venue. The event can also impact an area or region, for example, the location of the [2016 Rio Summer Olympics](https://events.predicthq.com/events/VMDqfHDg3PAbxL3PXh) is the state of Rio de Janeiro.

#### Entities

Sports events have event group entities and venue entities available.

#### Ranking

**PHQ Rank**

Sports events have PHQ Rank available.

**Local Rank**

Sports events have Local Rank available.

**Predicted Attendance**

Sports events have Predicted Attendance available.

### Conferences

A formal meeting or forum relating to a certain topic between a group of people with shared interests. A major conference, especially an industry-related one, may last for several days and occur with regular frequency. An example of an annually occurring conference is the [ASH Annual Meeting](https://events.predicthq.com/events/2RxTdCucMNcLZSsEqW).

**Labels**

Labels for a conference event provide more information about the event. The most common five labels are:

1. `business`: The conferences for a commercial purpose, for example, [Dreamforce](https://events.predicthq.com/events/HAnRjF9RUX8yFnWuGv) by Salesforce.
2. `education`: The conferences for an educational purpose, for example, [Young Social Innovators of the Year Awards](https://events.predicthq.com/events/XoEPm68yHWWNw9ysDp).
3. `health`: The conferences related to the health industry, for example, [CIOSP - Congresso Internacional de Odontologia de São Paulo](https://events.predicthq.com/events/kJ76dr1RmWPP).
4. `technology`: The conferences related to the technology topic, for example, [FPD China](https://events.predicthq.com/events/YEKd1jV29rjV).
5. `science`: The conferences related to the scientific topic, for example, [IAPM ASM](https://events.predicthq.com/events/RSJcHToM4Jy5MQcHZJ).

#### Date & time

<table><thead><tr><th width="232">Date &#x26; Time Fields</th><th width="144.33333333333331" align="center">Availability</th><th>NOTES</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td></td></tr><tr><td>Start time</td><td align="center">Yes</td><td>Conferences are expected to have a specific start time.</td></tr><tr><td>End time</td><td align="center">Yes</td><td></td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: datetime is in UTC.

#### Location

Conferences events are point events, meaning the latitude and longitude of the event represents the location of the event’s venue. The smaller size conferences are usually held in a hotel, and the large conferences in convention centers.

#### Entities

Conference events have event group entities and venue entities available.

#### Ranking

**PHQ Rank**

Conference events have PHQ Rank available.

**Local Rank**

Conference events have Local Rank available.

**Predicted Attendance**

Conference events have Predicted Attendance available.

### Expos

An industrial exhibition for communicating and trading purpose between business, or a trade fair that connects business and customers.

**Labels**

Labels for an expo event provide more information about the event. The most common five labels are:

1. `education`: The expos for an educational purpose or education-related topics, for example, [Riyadh International Book Fair](https://events.predicthq.com/events/cL7mv3QVd4PAwaRbvU).
2. `technology`: The expos related to topics in technology, for example, [IIMS - Indonesia International Motor Show](https://events.predicthq.com/events/SDxxc8XymZGYWZ6nrX).
3. `performing-arts`: The shows or fairs that have live performances or are art-related, for example, [Wizard World Comic Con](https://events.predicthq.com/events/i3VNEqMuZKpXUoBusH), and [Saint Louis Art Fair](https://events.predicthq.com/events/9uQWg42s8RziqNxPQb).
4. `entertainment`: The shows or fairs for entertainment purposes, for example, [The Big E (The Eastern States Exposition)](https://events.predicthq.com/events/gPmLe5eSMCbjLnYWCg).
5. `career`: A career or job fair that includes a number of businesses as well large numbers of candidates , for example, [HKTDC Education & Careers Expo](https://events.predicthq.com/events/ZkwcdaWxiMtbKZMrPK).

#### Date & time

<table><thead><tr><th width="235">Date &#x26; Time Fields</th><th width="172" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td></td></tr><tr><td>Start time</td><td align="center">Yes</td><td></td></tr><tr><td>End time</td><td align="center">Yes</td><td></td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: datetime is in UTC.

#### Location

Expos events are point events, meaning the latitude and longitude of the event represents the location of the event’s venue. Expos are usually held in venues that can fit a large number of attendees such as a convention center.

#### Entities

Expos events have event group entities and venue entities available.

#### Ranking

**PHQ Rank**

Expos events have PHQ Rank available.

**Local Rank**

Expos events have Local Rank available.

**Predicted Attendance**

Expos events have Predicted Attendance available.

### Concerts

A musical performance where the primary intention of attendance is to see the musical artist or listen to music. Concerts usually last less than one day. Examples are a large [Eminem](https://events.predicthq.com/events/aYR4t59pGHA92FtNgK) concert, or a smaller nightclub event, for example, [Darude At Hq2 Nightclub Atlantic City](https://events.predicthq.com/events/xx8TPFE7XNh5pdxyRX).

**Labels**

All concert events have a `music` label as concert events are expected to be music-related.

#### Date & time

<table><thead><tr><th width="242">Date &#x26; Time Fields</th><th width="120.33333333333331" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td></td></tr><tr><td>Start time</td><td align="center">Yes</td><td>Concerts are expected to have a specific start time</td></tr><tr><td>End time</td><td align="center">Yes</td><td></td></tr><tr><td><a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-end-times">Predicted End Times</a></td><td align="center">Yes</td><td>For concert events where there is no official end time available, PredictHQ predicts end times using our machine-learning models and intelligent algorithms.<br><br>PredictHQ’s Predicted End Times feature provides end times in the <code>predicted_end</code> field. When a Predicted End Time is provided, the event’s end time (in the <code>end</code> field) matches the start time (in the <code>start</code> field).</td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: datetime is in UTC.

#### Location

Concerts events are point events, meaning the latitude and longitude of the event represent the location of the event’s venue.

#### Entities

Concerts events have event group entities and venue entities available.

#### Ranking

**PHQ Rank**

Concerts events have PHQ Rank available.

**Local Rank**

Concerts events have Local Rank available.

**Predicted Attendance**

Concerts events have Predicted Attendance available.

### Festivals

A commonly known day or a period of time when people gather together to celebrate a specific reason; or a day or a period of time consisting of an organized series of shows and entertainment activities Festivals typically occur on a certain frequency. For example, the [Yosakoi Soran Festival](https://events.predicthq.com/events/ScR7u7EZSBuxZ8kK9J) is held annually.

**Labels**

Labels for a festival event provide more information about the festival. The most common five labels are:

1. `music`: Music festivals when a large group of musical artists continuously perform over several days. Music festivals are usually held at a dedicated venue that can fit a large number of attendees, for example, the [Ultra Music Festival](https://events.predicthq.com/events/duHrbmUbpFSgwypGAK).
2. `performing-arts`: The festivals that consist of performing shows such as a costume parade or a fireworks show. Such festivals could feature traditional music, theater, poetry, and art. For example, the [National Festival of Popular Arts in Marrakech](https://events.predicthq.com/events/cxSrjK82oWZGUWUvUJ).
3. `family`: The festivals which are family-friendly and children-friendly, for example, [Magnificent Mile Lights Festival](https://events.predicthq.com/events/vFQK4H3yaujGqwnR4z).
4. `community`: Traditional festivals in the local area. Community festivals are less formal than world-wide festivals and may also include street markets and entertainment activities. The [Odunde Festival](https://events.predicthq.com/events/dkbGjQW943KSL5hT8b) is an example of a community festival.
5. `food`: Food festivals where communities or businesses trade food products, for example, [Bite of Seattle](https://events.predicthq.com/events/QDgCysY3kMnpoGYFi9).

#### Date & time

<table><thead><tr><th width="253">Date &#x26; Time Fields</th><th width="152.33333333333331" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td></td></tr><tr><td>Start time</td><td align="center">Yes</td><td></td></tr><tr><td>End time</td><td align="center">Yes</td><td></td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: datetime is in UTC.

#### Location

A festival event can be a point event or an area event. The latitude and longitude of a point event represents the location of the venue where the festival takes place. The latitude and longitude of an area event is the geometric center of the area of the festival - either the area impacted by the festival, or an area where the festival takes place since its location is not fixed. An example of a festival without a fixed location is the [Norwich St. Patrick’s Day Parade and Festival](https://events.predicthq.com/events/w5PNZxwvKAKLGXGrae).

#### Entities

Festival events have event group entities and venue entities available.

#### Ranking

**PHQ Rank**

Festival events have PHQ Rank available.

**Local Rank**

Festival events have Local Rank available.

**Predicted Attendance**

Festival events have Predicted Attendance available.

### Performing arts

A show or an exhibition of creative activities for an audience, for example, [a circus show](https://events.predicthq.com/events/EHKbvvKhLnVonwUUbD).

**Event types**

The most common five types of performing-arts events are:

1. **General Theater**

   Stage plays, for example, [The Nutcracker ballet show](https://events.predicthq.com/events/wunsQfMcMgbB2wXedq).
2. **Comedy club**

   Standup comedy shows, for example, [Eddie Izzard - Wunderbar World Tour](https://events.predicthq.com/events/k2bibyMXE4B42EECnv).
3. **Concert**

   Musical plays, for example, A [symphony](https://events.predicthq.com/events/MeswVtp3dMccSx5jEs), or an [opera](https://events.predicthq.com/events/ah6hg4UorgsaJ2PSFY), etc.
4. **Family Theater**

   Shows or plays where the main audience are children, for example, [Magic On Ice](https://events.predicthq.com/events/8QJfuDQeqrKQftBnB3), a [dubbing show](https://events.predicthq.com/events/sjg2xuf27oeLQLrbpt), etc.
5. **Cultural Performances**

   Traditional or cultural activities, for example, [Sewing & Quilt Expo](https://events.predicthq.com/events/NCErdrvw9R69ocqES9), a [poetry slam](https://events.predicthq.com/events/CEE7SzC2CmrWSbbDe4), etc.

#### Date & time

<table><thead><tr><th width="238">Date &#x26; Time Fields</th><th width="150.33333333333331" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td></td></tr><tr><td>Start time</td><td align="center">Yes</td><td>Performing-arts events are expected to have a specific start time</td></tr><tr><td>End time</td><td align="center">Yes</td><td></td></tr><tr><td><a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-end-times">Predicted End Times</a></td><td align="center">Yes</td><td>For performing arts events where there is no official end time available, PredictHQ predicts end times using our machine-learning models and intelligent algorithms.<br><br>PredictHQ’s Predicted End Times feature provides end times in the <code>predicted_end</code> field. When a Predicted End Time is provided, the event’s end time (in the <code>end</code> field) matches the start time (in the <code>start</code> field).</td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: datetime is in UTC.

#### Location

Performing-arts events are point events meaning the latitude and longitude of the event is for the location of the event’s venue. Venues for these events are usually theaters, playgrounds, or clubs, etc.

#### Entities

Performing-arts events have event group entities and venue entities available.

#### Ranking

**PHQ Rank**

Performing-arts events have PHQ Rank available.

**Local Rank**

Performing-arts events have Local Rank available.

**Predicted Attendance**

Performing-arts events have Predicted Attendance available.

### Community

This category includes various types of events, for example, a [college event](https://events.predicthq.com/events/7diCQtRZ5XQdso27v3), a [community party](https://events.predicthq.com/events/pS49Cvk4tiSPKdEAJ8), an [auction](https://events.predicthq.com/events/iC5BK62w3z9CLpqvif), or a [fan meeting](https://events.predicthq.com/events/CnNAFhLqffMQMsqg4R).

**Labels**

Labels for a community event provide more information about the event. The most common five labels are:

1. `music`, `concert`: Social events with musical activity, for example, a [karaoke at a bar](https://events.predicthq.com/events/TvzBomhs9m6JAdKRr3).
2. `family`: Community events which are children and family-friendly, for example, a [book club breakfast in the library](https://events.predicthq.com/events/3pTSHhuXjQErhg9nwu).
3. `food`: Social events about food or have food provided, for example, a [wine tasting event](https://events.predicthq.com/events/hk9SqnMEk2ywVAyQb9).
4. `education`: Informal training workshops or clubs that consist of a group of people that share the same interest, for example, an [installation art workshop](https://events.predicthq.com/events/9sGedbBiSzq74ERvkS).
5. `fundraiser`: Community [fundraising](https://events.predicthq.com/events/U7nFaVDxKEh6RAD5UD) events.

#### Date & time

<table><thead><tr><th width="243">Date &#x26; Time Fields</th><th width="141.33333333333331" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td></td></tr><tr><td>Start time</td><td align="center">Yes</td><td></td></tr><tr><td>End time</td><td align="center">Yes</td><td></td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: datetime is in UTC.

#### Location

A community event is a point events meaning the latitude and longitude of the event represents the location of the event’s venue.

#### Entities

Community events have event group entities and venue entities available.

#### Ranking

**PHQ Rank**

Community events have PHQ Rank available.

**Local Rank**

Community events have Local Rank available.

**Predicted Attendance**

Community events have Predicted Attendance available.

### Academic

PredictHQ captures Academic Events from an individual higher education institute’s academic calendar. They outline the general undergraduate activities, for example instruction period, break, exams, graduation, social, etc.

Note:

* Academic Events cover institutions where full-time undergraduate enrollment (or FTE, full-time equivalent) is over 5,000. The student number is campus-based instead of the overall enrollment across different locations.
* Academic Events cover institutions in the United States of America.

**Labels / event types**

The Academic Events category has six main event types affecting students’ activities. PredictHQ retrieves the dates from the official academic calendar and/or estimates them based on the pattern. PredictHQ adds an `estimated` label to the estimated dates. The event types are:

1. **Academic-session**:
   * The compulsory academic session for students to graduate upon completion.
   * Session starts on the first day of instruction and ends on the last day of instruction.
   * Orientation, reading days, and exams are not included.
   * PredictHQ labels session events with `academic` and `academic-session`.
   * Intensive session, the optional academic session between the normal sessions for earlier graduation where the compulsory term is not applied, is also included in this event type.
2. **Exam**:
   * The exam period for the academic session.
   * Exam starts on the first day of the exam period and ends on the last day of the exam period
   * No separate exam period for the intensive session.
   * Reading days are not included.
   * PredictHQ labels exam events with `academic` and `exam`.
3. **Holiday**:
   * The break/holiday period between the sessions or within the sessions.
   * Holiday events consist of:
     * Fall break
     * Thanksgiving break
     * Winter break
     * Spring break
     * Summer break
   * Holiday events don’t cover the public holidays such as Labor day, Easter holiday, Martin Luther King Jr. Day, etc as we already have the public holiday and observance categories.
   * Holiday events cover the Thanksgiving break because institutions may have a different schedule, e.g. nine days vs four days.
   * Holiday events start on the day after the instruction / exam finishes and ends before the following instruction starts.
   * Winter and summer breaks may overlap with intensive sessions as the break will affect the majority of students while the intensive session only affects a few.
   * PredictHQ labels holiday events with `academic` and `holiday`.
4. **Graduation**:
   * Graduation (also called commencement) date for undergraduate students.
   * Graduation events may have a specific start time where applicable.
   * Graduation venues may be outside the campus.
   * Graduation events include the institute’s name in the title.
   * PredictHQ labels graduation events with `academic` and `graduation`.
5. **Social**:
   * Social events cover homecoming where alumni come back to the campus to visit.
   * Homecoming events may last up to a week.
   * PredictHQ labels social events with `academic` and `social`.

#### Date & time

<table><thead><tr><th width="230.33333333333331">Date &#x26; Time Fields</th><th width="138" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td>End date is the same as the start date when it’s not available, e.g. an one day graduation event has end date same as start date</td></tr><tr><td>Start time</td><td align="center">Yes</td><td>Available for graduation and social events only. This is an optional data point and may not always be provided.</td></tr><tr><td>End time</td><td align="center">Yes</td><td>Available for graduation and social events only. This is an optional data point and may not always be provided.</td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: datetime is in UTC.

#### Location

PredictHQ tracks academic events as events with a scope of locality. In terms of geographic information we return a latitude/longitude for the event and the address of the event. However, Academic events can apply to an entire campus or a specific location, e.g. an academic session applies to the whole campus, and a point event, e.g. graduation happens at a specific location. Use labels to distinguish these different types of events. `graduation` and `social` event are point events, `academic-session`, `holiday`, `exam` impact the whole area of the campus.

#### Entities

The Academic events have venue entities available.

#### Ranking

**PHQ Rank**

Academic events have PHQ Rank available, and how it indicates impact depends on the event type:

* Session, exam, and holiday types use student numbers (FTE) to indicate the event’s impact as the events apply on the whole campus.
* Intensive sessions use 30% of the total student numbers (FTE) to indicate the event’s impact as the events apply to only a small population.
* Graduation and social events use the actual number of attendees to indicate the impact.

**Local Rank**

Academic events have Local Rank available.

**Predicted Attendance**

Academic events have Predicted Attendance available for all event types. Predicted Attendance for `academic-session`, `exam`, and `holiday` event types is based on student population, e.g. the amount of students enrolled in the term. Predicted Attendance on `graduation` and `social` events are based on the number of people in attendance at the event.


# Non-Attendance-based events

Non-attendance-based events are events with a start and end date, but are more fluid and distributed in impact, such as observances or school holidays.

## Categories

**Note**: All Public Holidays, Observances, and School Holidays events contain polygon information. The API returns polygon information in the `geo` field. See our [guide to polygons](https://docs.predicthq.com/getting-started/guides/geolocation-guides/overview) for more details.

### Public holidays

A holiday generally established and recognized by law when most businesses and schools are closed. E.g. most countries celebrate New Year’s Day on January 1st.

#### **Labels**

Labels for a public holiday event provide more information about the holiday. The most common five labels are:

1. `holiday-national`: When the day is celebrated on a country level, e.g. the entire country was celebrating [Martin Luther King Jr. Day](https://events.predicthq.com/events/rXRfgke2wuD2zv55H7) on Jan 18, 2021
2. `holiday-local-common`: When the holiday is celebrated in only some regions of the country. E.g. only five out of 13 provinces and territories of Canada ([British Columbia](https://events.predicthq.com/events/KAojdY57MdQqYKYJvf), [Alberta](https://events.predicthq.com/events/joBsZRtPMSCPaD9sTQ), [Ontario](https://events.predicthq.com/events/zG3Egb83333QcyviRL), [New Brunswick](https://events.predicthq.com/events/KoTZox2GDtA4nx3CBR), and [Saskatchewan](https://events.predicthq.com/events/uhTw7zBFdZjdPDSJHb)) celebrate Family Day on the first Monday in February.
3. `holiday-local`: When the holiday is region-specific, e.g. only Texas state celebrates [Texas Independence Day](https://events.predicthq.com/events/kjqFBZH2qbzrswecDv) on Mar 2, 2021
4. `holiday-religious`: When the holiday is celebrated for a religious reason, e.g. there are about 44 countries that celebrate [Eid al-Adha](https://events.predicthq.com/events/pYQSFxFcYgJJdzo3uc) Day
5. `holiday-christian`: When the holiday is Christian related, e.g. [Corpus Christi](https://events.predicthq.com/events/3768MLSMzkSPo6HPjQ).

#### Date & time

<table><thead><tr><th width="224.33333333333331">Date &#x26; Time Fields</th><th width="154" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">No</td><td>Same as the start date. A public holiday event is a single-day event. There are no multi-day events under the public-holidays category. The holiday breaks into individual days if it’s celebrated over multiple days, e.g. there are four days off in Japan during the New Year period, the four corresponded records are: <a href="https://events.predicthq.com/events/rxdV0A0GKg16">December 31 Bank Holiday</a>, <a href="https://events.predicthq.com/events/8fuH3RGXNfmVs2UGAm">New Year's Day</a>, <a href="https://events.predicthq.com/events/bwJoHe5AtFZpRHWQ9j">January 2 Bank Holiday</a>, <a href="https://events.predicthq.com/events/M4bAQVNwHuv3qwTsvd">January 3 Bank Holiday</a></td></tr><tr><td>Start time</td><td align="center">No</td><td></td></tr><tr><td>End time</td><td align="center">No</td><td></td></tr><tr><td>Timezone</td><td align="center">No</td><td></td></tr></tbody></table>

Note: We use datetime in the local timezone. E.g. New York is celebrating New Year’s Day on January 1st EST, while San Francisco is also celebrating New Year’s Day on January 1st but in PST.

#### Location

Public holidays have a scope that is at the area level. The scope is either at the region or country level. The latitude and longitude is pointing to the center of the region or country.

#### Entities

Public holidays have event group entities available.

#### Ranking

**PHQ Rank**

Public holidays have one of two PHQ Rank values:

* National holidays or common local holidays have a PHQ Rank of 90 to indicate the popularity/impact on the country
* Local holidays have a PHQ Rank of 70 as there is less impact on the area compared to a national holiday.

**Local Rank**

Public holidays events have Local Rank available.

**Predicted Attendance**

Public holidays have no Predicted Attendance available as the rank/impact only reflect its influence on the area, instead of the number of people are celebrating this holiday.

### School holidays

School holiday events represent the general date range in an area where the schools are closed for the term/semester break. E.g. [Easter School Holidays](https://events.predicthq.com/events/tbZtoYD9mnArGQs5RW) in Bavaria, Germany is from March 27th, 2021 to April 11th, 2021.

**Note**: The School holidays category covers the holiday dates in primary schools and secondary schools. School holidays for higher education institutions are under the [Academic Events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events#academic) category.

**Predicted school holiday events**

PredictHQ provides global estimates for School Holiday events that are not yet confirmed, predicting events up to three years into the future.

We mark these predicted events with a `predicted` value in the event's `state` field, and they always occur in the future.

Predicted School Holiday events contain the same data attributes as confirmed events, which have a `state` value of `active`.

**Labels**

All school holidays events have both `school` and `holiday` labels. Some events may have an `estimated` label when there is no date available from the official source but a pattern from the previous years can be used to estimate the holiday dates.

#### Date & time

<table><thead><tr><th width="216.33333333333331">Date &#x26; Time Fields</th><th width="137" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td>We include the weekend before a school holiday if the school holiday starts on a Sunday or Monday</td></tr><tr><td>End date</td><td align="center">Yes</td><td>We include the weekend after a school holiday if the holiday ends on a Friday or Sunday</td></tr><tr><td>Start time</td><td align="center">No</td><td></td></tr><tr><td>End time</td><td align="center">No</td><td></td></tr><tr><td>Timezone</td><td align="center">No</td><td></td></tr></tbody></table>

Note: We use datetime in the local timezone.

#### Location

School holiday is an area event, it scopes to either locality, localadmin, county, region, or country level, i.e. majority schools in that region commence break in that period. For example, we scope school holidays in the United States to the county level, e.g. [Clark County School District - Spring Break](https://events.predicthq.com/events/G9dAga9g8vcacTgmB9) while school holidays in New Zealand are scoped to the country level which means we have one school holiday for the entire country, e.g. [Spring School Holidays](https://events.predicthq.com/events/SPVWqTnhTqry2rLDvf). We scope school holidays in the UK to either region, county, or the local council (localadmin) level.

The latitude and longitude is pointing to the center of the region or country.

<table><thead><tr><th width="287">Geo-scope Level</th><th>Countries</th></tr></thead><tbody><tr><td>Country</td><td>Azerbaijan, Monaco, Bulgaria, Liechtenstein, Brazil, Latvia, Moldova, Bosnia and Herzegovina, Hungary, Mexico, Ukraine, Vietnam, South Korea, Japan, Croatia, New Zealand, Turkey, Slovakia, Russia, Greece, Lithuania, United Arab Emirates, Hong Kong, Serbia, Armenia, Taiwan, Malta, Republic of Ireland, Iceland, Albania, Finland, Montenegro, Kosovo, Fiji, Belarus, Estonia, Kazakhstan, Slovenia, Thailand, Israel, Poland, Singapore, Cyprus, India, Romania, Switzerland, Andorra, Portugal, Czech, Malaysia, Belgium, Indonesia, Denmark, North Macedonia, Georgia</td></tr><tr><td>Region</td><td>Netherlands, Spain, Luxembourg, Sweden, South Africa, Austria, Australia, Italy, France, Norway, Germany, Canada, China, United Arab Emirates, Chile</td></tr><tr><td>County</td><td>United States</td></tr><tr><td>Region/County/Local-admin</td><td>United Kingdom</td></tr></tbody></table>

#### School holidays in the United Kingdom

Our school holidays data goes to a more granular detailed level for the United Kingdom than for other countries. Our school holidays data includes local council level school holidays for England, Wales, North Ireland, and Scotland.

{% hint style="warning" %}
**Note**

Our school holidays granularity changed in September 2021 to move from the country level for England, Wales, Scotland, and Northern Ireland to the local council level.
{% endhint %}

For the granular school holiday data for the United Kingdom we have historic data from September 2017 onward. We update school holidays every week.

We have events for 212 school districts in the UK including 157 districts for England. For the UK per year we have the following number of events:

* 1200-1300 events per School Period (E.g. Sep 2021 - June 2022),
* 1400-1500 events per Year (E.g. 2021 covers part of both the 2020-2021 and 2021-2022 school periods)

Here are some examples of the school holidays for the United Kingdom:

* [Nottinghamshire - Summer Half Term Holidays for 2018](https://events.predicthq.com/events/EfdV6SwVXSAb4NFoYE)
* [Bristol - Spring Holidays for 2019](https://events.predicthq.com/events/8dV2ArT6rYjYT9r3YB)
* [Swindon - Spring Holidays for 2020](https://events.predicthq.com/events/9a6672HwVphSkWLNuM)
* [Northern Ireland - Winter Holidays for 2018](https://events.predicthq.com/events/DBWg3Pr9hGfVPppYBv)
* [Cardiff - Summer Holidays for 2019](https://events.predicthq.com/events/3ScDNL4SENDGjxZr5x)
* [Glasgow - Autumn Half Term Holidays for 2020](https://events.predicthq.com/events/7wVaYTguF8K7qzwyKk)

To find school holidays that impact your location you can use the standard features of our Events API - as follows:

* You can perform a lat/lon and radius search using the within parameter on the API. The location can be a store, hotel, or any other location with a lat/lon. Search for events around that location - such as 5 kilometers around a location in Leeds.
* To find events impacting a geographic location, use the places parameter in the Events API - for example all events impacting Bristol or all events impacting Kent.
* Alternatively, if you are downloading the data into a data lake you can use our location scopes from the place\_hierarchies field with the [places hierarchy endpoint](https://docs.predicthq.com/api/places/get-place-hierarchies) to retrieve events that impact a geographic location.

See also the [FAQs for district-level school holidays](#faqs-for-district-level-school-holidays)

#### School holidays in the United States

Our school holidays data goes to a more granular detailed level for the United States (US) than for other countries. We define school holidays at a district level for the US. See our [school holidays category page](https://www.predicthq.com/intelligence/data-enrichment/event-categories/school-holidays) for an overview of our school holidays data.

There are around 98,469 public schools in the US in around 13,000 school districts. We provide school holidays at a school district level for the US. We have approximately 55,000 - 58,000 school holiday events per year.

For the district school holiday data for the US we have historic data from September 2018 onward. We update school holidays every week. For school holidays before September 2018 they are shown at the state level.

{% hint style="info" %}
**Note**

Our school holidays granularity changed in October 2021 to move from the state level to the district level.
{% endhint %}

<div data-full-width="false"><figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FUWJLYTDLa1JQOyhd6sKc%2Fschool-holidays-us-district-comparison-white.png?alt=media&amp;token=98ee3e0e-e610-4581-b70e-47490567b88c" alt="Comparison of US school holidays at the state level and at the district level"><figcaption></figcaption></figure></div>

We rank our school holidays based on student numbers in the school district.

Here are some examples of the school holidays for the United States:

* [New York City School District - Christmas Break](https://events.predicthq.com/events/3W5n3HjxNnV6VVqiH5)
* [Chicago Public Schools - Summer Break](https://events.predicthq.com/events/EJqeXqBWMYhEW2sDXs)
* [Miami-Dade County Public Schools - Christmas Break](https://events.predicthq.com/events/9JUxNe7qv5QB6un23m)
* [Clark County School District - Spring Break](https://events.predicthq.com/events/G9dAga9g8vcacTgmB9)
* [Broward County Public Schools - Thanksgiving Break](https://events.predicthq.com/events/J7qZdCiQPGMjCMEkWy)
* [Prince William County Public Schools - Fall Break](https://events.predicthq.com/events/7bNtEWAe6Mke2eZ7BZ)

To find school holidays that impact your location you can use the standard features of our Events API and our WebApp to find events that impact your location - as follows:

* You can perform a lat/lon and radius search using the within parameter on the API. The location can be a store, hotel, or any other location with a lat/lon. Search for events around that location - such as 5 kilometers around a location in Leeds.
* To find events impacting a geographic location, use the places parameter in the Events API - for example all events impacting Bristol or all events impacting Kent.
* You can search in the WebApp for a location (this uses the places parameter behind the scenes) to find school holidays for a location.
* Alternatively, if you are downloading the data into a data lake you can use our location scopes from the place\_hierarchies field with the [places hierarchy endpoint](https://docs.predicthq.com/api/places/get-place-hierarchies) to retrieve events that impact a geographic location.

#### FAQs for district-level school holidays

These Frequently asked questions apply to district level school holidays (for the US and UK):

1. **Does the data include private school holidays as well?** The data set does not cover private schools. Private schools select their own calendars and are not necessarily governed by school district dates. That being said, some private schools might follow similar calendars.
2. **Does the data recognize if school holidays are changed due to covid-based government decisions?** The data recognizes changes as soon as possible. The events have an update date/time on them so we fetched updates based on these dates. We update events weekly.
3. **What date range does the event signal? Are there start and end times to the school holiday?** The date range is the total length of the event. That being said, if the school holidays start on a Sunday or Monday, the weekend before that school holiday is included in the total event time. The same applies to the end date. We include the weekend after a school holiday if the holiday ends on a Friday or Sunday.
4. **What location is given to the event?** A school holiday is an area event, it scopes to either locality, county, region, or country level. For example, we scope school holidays in the United States to the district level, which means we have school holidays per district, while we scope school holidays in New Zealand to the country level which means we have one school holiday for the entire country, e.g. [Spring School Holidays.](https://events.predicthq.com/events/SPVWqTnhTqry2rLDvf) We scope school holidays in the UK to the local council level. The latitude and longitude are pointing to the center of the country, region, county, or locality.
5. **Teacher Only Days -** We do not include teacher-only days.

#### Geoscoping

We geoscope the places hierarchy information for school holidays as described in our [geographic info guide](https://docs.predicthq.com/getting-started/guides/geolocation-guides/overview). These events can have multiple hierarchies if they are close to a major hierarchy (within a radius of 50km). This means for example school holidays in Surrey have a scope for Surrey and a scope for Greater London as they are near Greater London.

If you use the `place.scope` parameter and query for Greater London in this example you get holidays for Surrey too. To limit your search to only London look for areas within London (below Greater London).

#### Entities

School holidays have no entities available

#### Ranking

**PHQ Rank**

We rank school holidays for the United Kingdom (from September 2017) and the United States (from September 2018) based on student numbers. The rank is based on a logarithmic scale to convert student numbers at the local authority level to a PHQ Rank value.

All school holidays for other countries and from the US and UK before the time periods stated earlier, have a PHQ Rank of 90 to indicate the general impact on the region.

**Local Rank**

School holidays events have Local Rank available.

For the United Kingdom (from September 2017) and US (from September 2018) school holidays, We calculate Local Rank by applying a linear transformation to the student percentage of the local authority. We calculate the student percentage by dividing the student numbers of a local authority by its total population.

**Predicted Attendance**

Predicted Attendance for School holidays for the United Kingdom (from September 2017) and the United States (from September 2018) is based on student numbers for the school district. E.g. If the Bristol school district has 66,000 students in 2019 then we would show phq\_attendance as 66,000.

School holidays for the rest of the world, and from the US and UK before the time periods stated earlier, have no Predicted Attendance available as the rank/impact only reflect its influence on the area, instead of a number of people are on school holiday during that period.

### Observances

An Observance is a day that people recognize nationally or internationally, and that a major organization or government usually sets to commemorate a public health or ethical cause of importance on a national or international level. E.g. [Mother’s Day](https://events.predicthq.com/events/XLGbVwXCopCg2rnN89), [New Year’s Eve](https://events.predicthq.com/events/9sHnCzcaMEK3tRu9Wr), [World Cancer Day](https://events.predicthq.com/events/3jHMpFmP4Q5NEjGxMj), etc

**Labels**

Labels for an observance event provide more information about the event. The most common five labels are:

1. `observance-season`:
   * When the observance marks the seasonal change: [June Solstice](https://events.predicthq.com/events/dV6eJatmAjBpT9dwAf), [March Equinox](https://events.predicthq.com/events/kKqJaTbuZhRvZVkQLv), [September Equinox](https://events.predicthq.com/events/bPsTpsswkpRfGq73Fu), [December Solstice](https://events.predicthq.com/events/5eVGwA82bfPEMdHXrM).
   * 227 countries observed these four types of events.
2. `holiday-religious`: When observing a religious holiday mostly celebrated in other cultures but not a major trend among the local population. E.g. Eid al-Fitr is celebrated as a [religious public holiday](https://events.predicthq.com/events/rasnhTdtREXDVNb5aF) in Muslim countries and is [observed](https://events.predicthq.com/events/aY7JYozjyDx35umEwG) in other countries.
3. `holiday-christian`: When observing a Christian-related holiday, e.g. [Epiphany](https://events.predicthq.com/events/cMjzGaEAKnCWLTG4Lc).
4. `observance-united-nations`:
   * The United Nations created international days to promote global awareness and action on some issues. For example, March 22 is[ World Water Day](https://events.predicthq.com/events/NDj4W65XpbLLeA9kPu).
   * The United Nations also observes anniversaries of key events in its history. E.g. May 8th is [Time of Remembrance and Reconciliation for Those Who Lost Their Lives during the Second World War](https://events.predicthq.com/events/nLoWsBHWpVrHuW5FcC).
5. `holiday-hebrew`: When observing a Hebrew-related holiday, e.g. many countries observe [Tu Bishvat](https://events.predicthq.com/events/FRgcTikSuwrJixHDdL).

#### Date & time

<table><thead><tr><th width="231.33333333333331">Date &#x26; Time Fields</th><th width="136" align="center">Availability</th><th>NOTES</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">No</td><td>Same as the start date. An observance event is a single-day event. There are no multi-day events under the observance category. It breaks into individual days if it’s celebrated over multiple days, e.g. the Saturday in the Easter weekend is recognized as Holy Saturday, with the following Sunday is Easter Sunday in Canada</td></tr><tr><td>Start time</td><td align="center">No</td><td></td></tr><tr><td>End time</td><td align="center">No</td><td></td></tr><tr><td>Timezone</td><td align="center">No</td><td></td></tr></tbody></table>

Note: We use datetime in the local timezone E.g. Boston is celebrating Valentine’s Day on February 14th EST, while Los Angeles is also celebrating Valentine’s Day on February 14th but in PST.

#### Location

An Observance is an area event, it scopes to either region or country level, i.e. the whole country or region is observing this day. The latitude and longitude is pointing to the center of the region or country.

#### Entities

Observances have event group entities available.

#### Ranking

**PHQ Rank**

Observances have PHQ Rank values in four bands:

* **Rank 80-90** observances are widely observed and typically associated with consumer spending on gifts, travel, and festivities. Examples include [Valentine's Day](https://events.predicthq.com/events/x957f7DyXpeCubLpWH) and [Christmas Eve](https://events.predicthq.com/events/AtVVBpX4bkXhLDNjBa).
* **Rank 60-79** observances are mostly religious observances, national days, independence days, or cultural and historical dates which have a wide impact. Examples include [Constitution Day](https://events.predicthq.com/events/PmW2kvCVoxQ3AHgAZS) and [Ganesh Chaturthi](https://events.predicthq.com/events/N22YXJKJlGwL).
* **Rank 40-59** observances include observances with the potential for increased localized economic activities such as awareness days, smaller historical observances, and regional celebrations. Examples include [Queensland Day](https://events.predicthq.com/events/4CJKDjxdQb5RCyckrN) and [National Indigenous Peoples Day](https://events.predicthq.com/events/AYd5LmshmHX5zjjc4k).
* **Rank 20-39** observances generally do not have widespread commercialization, public holidays, or significant consumer behavior changes associated with them. Examples include [September Equinox](https://events.predicthq.com/events/wjjJldkg0jGj) and [World Bicycle Day](https://events.predicthq.com/events/Bkgr5cvHLa8ZEGNUbT).

**Local Rank**

Observance events have Local Rank available.

**Predicted Attendance**

Observances have no Predicted Attendance available as the rank/impact only reflects its influence on an area, rather than a specific amount of attendees at a specific location.

### Politics

Politics events include the main dates of elections and referendums around the world.

**Note** the politics category does not cover physically attended events to do with politics such as rallies and debates.

**Labels**

We classify this category into two buckets, using the following labels to identify the type of events:

1. **Election**: The date when the `parliament` or `president` election occurs.
2. **Referendum**: The `referendum` date in the country.

#### Date & time

<table><thead><tr><th width="207.33333333333331">Date &#x26; Time Field</th><th width="136" align="center">Availability</th><th>NOTES</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td>Politics events have only a start date available.</td></tr><tr><td>End date</td><td align="center">No</td><td></td></tr><tr><td>Start time</td><td align="center">No</td><td></td></tr><tr><td>End time</td><td align="center">No</td><td></td></tr><tr><td>Timezone</td><td align="center">No</td><td></td></tr></tbody></table>

Note: We use datetime in the local timezone.

#### Location

Politics events scope to a country level. For example [Election for US Senate](https://events.predicthq.com/events/U9Q6MExfzBmwgjAXBE) in the United States. The latitude and longitude point to the center of the covered area. The place scope identifies the full area of coverage.

#### Entities

Politics events have event group entities available.

#### Ranking

**PHQ Rank**

Politics events have PHQ Rank available. It considers the number of registered voters and turnout in a certain area.

**Local Rank**

Politics events have Local Rank available.

**Predicted Attendance**

Politics events have no Predicted Attendance available as the rank/impact only reflects the influence in the country, rather than a specific amount of attendees at a specific location.

### Daylight savings

Daylight savings is the schedule date when daylight savings start or ends in an area.

**Labels**

We label all daylight savings events `daylight-savings`. The only two types of daylight savings events are: daylight savings begins and daylight savings ends

#### Date & time

<table><thead><tr><th width="221.33333333333331">Date &#x26; Time Field</th><th width="143" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td>Daylight events have only a start date available.</td></tr><tr><td>End date</td><td align="center">No</td><td></td></tr><tr><td>Start time</td><td align="center">No</td><td></td></tr><tr><td>End time</td><td align="center">No</td><td></td></tr><tr><td>Timezone</td><td align="center">No</td><td></td></tr></tbody></table>

Note: Datetime is in UTC

#### Location

Daylight savings is an area event, it scopes to either region or country level, i.e. the whole country or region starts or ends daylight savings on this day. The latitude and longitude is pointing to the center of the region or country.

#### Entities

Daylight savings events have event group entities available.

#### Ranking

**PHQ Rank**

All daylight savings events have a PHQ Rank of 30.

**Local Rank**

Daylight savings events have Local Rank available.

**Predicted Attendance**

Daylight savings events have no Predicted Attendance available.


# Unscheduled events

Live coverage of breaking events such as severe weather and terrorism. The API updates minute to minute to ensure accuracy.

## Categories

### Severe weather

Severe weather is any dangerous meteorological phenomenon with the potential to cause damage, serious social disruption, or loss of human life. Types of severe weather phenomena vary, depending on the latitude, altitude, topography, and atmospheric conditions.

Severe weather warnings or alerts which may lead to disruption. Severe weather alerts include storms, extreme temperature, flood, etc. For example, a [tornado warning](https://events.predicthq.com/events/v3xwuouU62ZEzXhxWC) for southeastern Webster Parish in northwestern Louisiana alerts people that a severe thunderstorm along with damage in the nearby area is likely to occur in the upcoming hour.

Severe weather storm events can change over time. Events like hurricanes, tornados, and other storms move across different locations and change in strength as time goes on. Different warning events in our system can reflect this. It’s possible to have multiple warnings about the same weather condition:

* The bad weather condition lasts longer than expected. For example, a [flood advisory was issued at 11.48 AM](https://events.predicthq.com/events/jZEkmbAYqntSRo4Xgs) in east Tennessee that the potential threat may last until 3 PM. Another [flood advisory issued at 3.02 PM](https://events.predicthq.com/events/fxZjGT5Ehoe7brsCjd) that indicates additional rainfall may occur on the day and the following day, and the road closures will remain in place.
* Multiple areas can be affected. For example, On March 14th, several regions in South Dakota have issued blizzard warnings, such as [Oglala Lakota](https://events.predicthq.com/events/tTjDpN7ZR2WVhzw47o), [Pennington](https://events.predicthq.com/events/ubp47jnAvuwos5fanc), [Fall River](https://events.predicthq.com/events/74ucjeYRYWG89Sw5rS), and [Custer](https://events.predicthq.com/events/6y3py8CPSLfeN29DYq).
* Warnings may be issued hours or days in advance. The event (warning) state changes to `cancelled` if the potential threat no longer exist. For example the storm didn't hit as expected. Past events with an `active` state mean the event has happened.
* PredictHQ updates severe weather data in near real time and refreshes event details every 15 minutes on average.
* PredictHQ provides historical severe weather data that can be used for purposes like training a demand forecasting model.

**Labels**

PredictHQ classifies this category into three buckets with the following labels used to identify the type of severe weather:

1. **Storm**

   `storm`, `tornado`, `blizzard`, `dust`, `hurricane`, `cyclone`, `rain`, `wind`, `typhoon`, `sand`
2. **Extreme temperature**

   `cold-wave`, `heat-wave`, `air-quality`, `snow`
3. **Flood**

   `flood`

#### Date & time

<table><thead><tr><th width="221.33333333333331">Date &#x26; Time Field</th><th width="144" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td></td></tr><tr><td>Start time</td><td align="center">Yes</td><td>The weather warnings’ start time indicate when the warning starts to be effective.</td></tr><tr><td>End time</td><td align="center">Yes</td><td>The weather warnings’ end time indicate when the warning expires.</td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: Datetime is in UTC

#### Location

Severe weather is an area event. with the latitude and longitude is pointing to the center of the impacted area.

#### Entities

Severe weather events have no entities available.

#### Ranking

**PHQ Rank**

Severe weather events have PHQ Rank available.

The PHQ Rank indicates the severity of the bad weather, with using the [Common Alerting Protocol (CAP)](https://en.wikipedia.org/wiki/Common_Alerting_Protocol) data. CAP is an international non-proprietary digital message format for all-hazard emergency events. The benefit of using CAP is there is consistency in how it is implemented in different countries, making it easier to use. CAP alerts can be geographically targeted to a defined warning area.

CAP features evaluate the event from three aspects: urgency, severity, and certainty. For example, a warning about an extreme (severity) weather condition that is likely (certainty) to happen immediately (urgency) has a higher rank. The following table shows the weight of each value of severity, urgency, and certainty when calculating the PHQ Rank.

For example, An event with an urgency of immediate (15), a severity of severe (36), and a certainty of observed (35) would have a PHQ Rank of 86.

<table><thead><tr><th width="148">CAP Type</th><th width="175">Level</th><th width="316">Description</th><th>Weight</th></tr></thead><tbody><tr><td>Urgency</td><td><ul><li>Immediate</li><li>Expected</li><li>Future</li><li>Past</li></ul></td><td><ul><li>Responsive action should be taken immediately</li><li>Responsive action should be taken soon (within next hour)</li><li>Responsive action should be taken in the near future</li><li>Responsive action is no longer required</li></ul></td><td><ul><li>15</li><li>13</li><li>10</li><li>8</li></ul></td></tr><tr><td>Severity</td><td><ul><li>Extreme</li><li>Severe</li><li>Moderate</li><li>Minor</li></ul></td><td><ul><li>Extraordinary threat to life or property</li><li>Significant threat to life or property</li><li>Possible threat to life or property</li><li>Minimal to no known threat to life or property</li></ul></td><td><ul><li>40</li><li>36</li><li>21</li><li>5</li></ul></td></tr><tr><td>Certainty</td><td><ul><li>Observed</li><li>Likely</li><li>Possible</li><li>Unlikely</li></ul></td><td><ul><li>Determined to have occurred or to be ongoing</li><li>Likely</li><li>Possible but not likely</li><li>Not expected to occur</li></ul></td><td><ul><li>35</li><li>31</li><li>10</li><li>0</li></ul></td></tr></tbody></table>

**Local Rank**

Severe weather events have Local Rank available.

**Predicted Attendance**

Severe weather events have no Predicted Attendance available as the rank/impact only reflects its influence on an area, rather than a specific amount of attendees at a specific location.

### Disasters

Disaster events are major adverse events resulting from natural processes of the Earth, for example, earthquakes, volcanoes, tsunamis, etc. PredictHQ also classifies the reduction and/or limitation of social activities forced by the COVID-19 pandemic under the disaster category.

These events tend to be high-impact disasters noticed at a regional or country level.

**Labels**

PredictHQ classifies this category into three buckets with the following labels used to identify the type of disasters:

1. **Hydrological\_geophysical**

   `earthquake`, `avalanche`, `landslide`, `volcano`, `tsunami`, `ashfall`

   1. Note: Earthquake coverage typically includes magnitude 4 and above earthquakes.
2. **Climatological**

   `fire`, `wildfire`, `drought`
3. **Lockdown**

   The government mandated stay-at-home orders during the COVID-19 pandemic that restrict or reduce social activities on different levels. Lockdown events have `health`, `lockdown`, and `disaster` labels. For example, [COVID-19 - Lockdown easing - Portugal](https://events.predicthq.com/events/ydXTVviY5KQty98UfD), [COVID-19 - Stay at home order easing - Michigan - Phase 4](https://events.predicthq.com/events/Vat8acyAFAXQaNNTaK).

#### Date & time

<table><thead><tr><th width="225.33333333333331">Date &#x26; Time Field</th><th width="146" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td>Disaster events may or may not have an end date &#x26; time.</td></tr><tr><td>Start time</td><td align="center">Yes</td><td></td></tr><tr><td>End time</td><td align="center">Yes</td><td></td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: Datetime is in UTC

#### Location

Disaster is an area event with the latitude and longitude pointing to the center of the impacted area.

#### Entities

Disaster events have no entities available.

#### Ranking

**PHQ Rank**

Disaster events have PHQ Rank available, which indicates the severity of the disasters:

* The natural disaster events consider [CAP](https://en.wikipedia.org/wiki/Common_Alerting_Protocol) information, number of injured, deaths, evacuated, etc.
* The lockdown events consider the level of restriction, the maximum number of people allowed in a public social gathering, etc.

**Local Rank**

Disaster events have Local Rank available.

**Predicted Attendance**

Disasters events have no Predicted Attendance available as the rank/impact only reflects its influence on an area, rather than a specific amount of attendees at a specific location.

### Airport delays

Airport delays are events that indicate a scheduled flight getting delayed at a specified airport at a specified time.

**Labels**

All airport delays events have both `airport` and `delay` labels.

#### Date & time

<table><thead><tr><th width="215.33333333333331">Date &#x26; Time Field</th><th width="141" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td></td></tr><tr><td>Start time</td><td align="center">Yes</td><td></td></tr><tr><td>End time</td><td align="center">Yes</td><td>All airport delays events are expected to have an end time as it indicates when the delay is expired.</td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: Datetime is in UTC

#### Location

All airport delays are point events, the latitude and longitude are pointing to the specific airport.

#### Entities

Airport delays have venue entities available.

#### Ranking

**PHQ Rank**

Airport delays events have PHQ Rank available, indicating the severity of the delay that affects passengers’ travel plans:

* Minimal airport delays events have a PHQ Rank of 20.
* Moderate airport delays events have a PHQ Rank of 40.
* Significant airport delays events have a PHQ Rank of 70.
* Severe airport delays events have a PHQ Rank of 90.

**Local Rank**

Airport delays events have Local Rank available.

**Predicted Attendance**

Airport delays events have no Predicted Attendance available as the rank/impact only reflects its influence on an area, rather than a specific amount of attendees at a specific location.

### Health warnings

This category covers events related to infectious diseases. Some events refer to localized outbreaks, some to nationwide epidemics, some to government mandated restrictions due to COVID-19.

Labels

PredictHQ classifies this category into three buckets with the following labels used to identify the type of health warnings:

1. **Epidemic**

   Pandemic, `epidemic`, or `epidemic-hazard`, for example, COVID-19, Cholera, etc
2. **`biological-hazard`**

   Diseases and insect infestations, for example, food poisoning warnings, infection warnings, etc.
3. **Government mandated restrictions**

   There are seven government mandated events in the US on a state level. These events indicate if a government body has mandated that the activity stays open or closed during a specified period of time.

   If no end time is specified on government mandated restriction events, the event has yet to end. The labels are:

   * `bars-open` / `bars-closed` : Bars and other drinking establishment that serves alcoholic beverages are open or closed.
   * `restaurant-open` / `restaurant-closed` : On-site dining facilities are open or closed.
   * `retail-open` / `retail-closed` : On-premise / physical activity of selling goods and services to consumers are open or closed.
   * `recreation-open` / `recreation-closed` : Activity or recreation engaged in out of doors, most commonly in natural settings (gyms, pools, beaches, camping grounds) are open or closed.
   * `entertainment-open` / `entertainment-closed` : an event, performance, location, or activity designed to entertain others (casinos, movie theaters, museums, galleries, and aquariums) are open or closed.
   * `personal-care-open` / `personal-care-closed` : Both physical assistance and/or prompting and supervising the performance of direct personal care tasks as determined by the consumer's needs (salons, barbers, nail salons) are open or closed.
   * `worship-open` / `worship-closed` : Any building where congregations gather for prayer are open or closed.

#### Date & time

<table><thead><tr><th width="224.33333333333331">Date &#x26; Time Field</th><th width="138" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td>Government mandated restrictions may have an end date if it’s available, it should cover the whole period in which restrictions are in place or have been lifted.</td></tr><tr><td>Start time</td><td align="center">Yes</td><td>The pandemic or epidemic hazard events use the official announcement time as the start time.</td></tr><tr><td>End time</td><td align="center">No</td><td></td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: Datetime is in UTC

#### Location

Health warnings events are area events. It may scope to a city, a region, or a country depending on the impact. The latitude and longitude relates to the center of the impacted area.

#### Entities

Health warnings events have no entities available.

#### Ranking

**PHQ Rank**

Health warnings events have PHQ Rank available:

* It considers the severity of the disease, for example, the number of infected, death, area range, etc.
* All government mandated restrictions have a PHQ Rank of 90 as it affects all residents in the impacted area.

**Local Rank**

Health warnings events have Local Rank available.

**Predicted Attendance**

Health warnings events have no Predicted Attendance available as the rank/impact only reflects its influence, rather than a specific amount of attendees at a specific location.

### Terror

An act of terrorism committed using violence against civilians, with the intention/effect of causing mass / widespread fear and intimidation, in order to attain political, religious or ideological goals.

**Note** PredictHQ also includes attempted (but failed) terror attacks. This category focuses more in areas outside of designated warzones, as war zones are in a constant state of conflict.

**Labels**

Labels for a terror event provide more information about the event. The most common five labels are:

1. `attack`: An aggressive and violent act against a person or place with weapons or armed force.
2. `bombing` : The terrorism acts where the main injury or damage is caused by dropping or detonating a bomb somewhere, for example, [Bombing in Lahan, Nepal](https://events.predicthq.com/events/hnCL2axLWVJZyBN2AV).
3. `arson`: The terrorism acts also result in a fire damage, it may it may be combined with a `shooting`, `bombing`, etc.
4. `hostage-crisis`: The terrorism acts when the hostage occurs, for example, [`assassination`](https://events.predicthq.com/events/ywfjG46u6KDmkqqsAa), a terror threat, etc.
5. `shooting`: The terrorism acts where shooting causes the main injury or damage, for example, [Shooting in Sonwar, India](https://events.predicthq.com/events/X6D8sz2i7qWZ3VMpFh). If the shooting is on a larger scale, PredictHQ adds the `mass-shooting` label, for example, [Shooting in Chicago, United States](https://events.predicthq.com/events/FtzZisWG6r8KZRp9Gp).

#### Date & time

<table><thead><tr><th width="212.33333333333331">Date &#x26; Time Field</th><th width="151" align="center">Availability</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td></td></tr><tr><td>End date</td><td align="center">Yes</td><td>Terror events may have an end date and time available.</td></tr><tr><td>Start time</td><td align="center">Yes</td><td></td></tr><tr><td>End time</td><td align="center">Yes</td><td></td></tr><tr><td>Timezone</td><td align="center">Yes</td><td></td></tr></tbody></table>

Note: Datetime is in UTC

#### Location

PredictHQ tracks terror events with a scope of locality. In terms of geographic information we return a latitude/longitude for the event and the address of the event. However, terror events can apply to a wider area, for example, [attempted bombing in Cipinang, Indonesia](https://events.predicthq.com/events/VGG78MrBvgZ4dartjv).

#### Entities

Terror events may have venue entities available such as if the attack happens in a building.

#### Ranking

**PHQ Rank**

Terror events have PHQ Rank available. It indicates the severity of the terrorism act, from the number of injured, fatalities, also if the location is a tourism country vs the war-torn country.

**Local Rank**

Terror events have Local Rank available.

**Predicted Attendance**

Terror events have no Predicted Attendance available as the rank/impact only reflects its influence on an area, rather than a specific amount of attendees at a specific location.


# Live TV events

Live TV Events covers live broadcast sports games with a large number of people watching at a particular time across different counties across the United States.

For example, during the basketball game [Villanova Wildcats vs Baylor Bears](https://events.predicthq.com/events/3pgcB4kTQdLv6FAhCb) on March 27, 2021, there were over 150,000 people in Cook County, Illinois watching the live broadcast of the basketball game, as well as over 130,000 people were watching the game in Los Angeles County, California, etc.

**Note**: Live TV Events covers live games. Live TV Events doesn't include replays of sporting events.

{% hint style="info" %}
Live TV Events provide viewership data that is attached to events in other categories. It covers events in the sports category. Live TV Events is not actually a category itself but consists of rich information on who is watching events in different locations.

Live TV Events shows the number of people watching sports events per county in the US.
{% endhint %}

Live TV Events include live streaming and broadcast TV games (such as MLS Soccer games streamed on Apple TV).

## Coverage

**Event types**

We have two different types of broadcast information. Major sports league viewership uses one model and top viewership sports uses a different approach. This affects how the viewership is calculated and which counties viewership is shown in. For the major sports leagues, viewership per county uses TV schedule information to predict where people will watch a game. Live TV Events shows viewership only for the counties where we predict people will watch a game. Top viewership sports, unlike the major sports leagues games, always show viewership in all counties in the US.

**Seven major sports leagues**

Live TV Events covers all televised sports games from the following seven sports leagues. The broadcasts may have status of either `scheduled` or `cancelled`:

`NFL`, `NBA`, `NHL`, `MLB`, `MLS`, `D1 NCAA Basketball`, `D1 NCAA Football`

**Top viewership sports**

Live TV Events extends coverage to some popular sports games beyond the seven major sports leagues. These are events that have high viewership and are assumed to be televised nationally (in all counties). The broadcasts may have status of either `predicted` or `cancelled`

Top viewership sports are typically one-off events or are finals of their respective competitions, such as the 2019 NCAA Women's Basketball Final:

<table><thead><tr><th width="200.33333333333331">SPORTS TYPE</th><th>SPORTS LEAGUE</th><th>EVENT TYPE</th></tr></thead><tbody><tr><td><code>auto-racing</code></td><td><ul><li><code>nascar</code></li><li><code>indy-car</code></li></ul></td><td><ul><li>NASCAR Cup Series Races</li><li>Indy 500</li></ul></td></tr><tr><td><code>horse-racing</code></td><td><ul><li><code>kentucky-derby</code></li><li><code>preakness-stakes</code></li><li><code>belmont-stakes</code></li></ul></td><td><ul><li>Kentucky Derby Horse Racing</li><li>Preakness Stakes Horse Racing</li><li>Belmont Stakes Horse Racing</li></ul></td></tr><tr><td><code>basketball</code></td><td><ul><li><code>ncaa-women</code></li></ul></td><td>NCAA Women's Basketball Division 1 Tournament Semifinals and Finals</td></tr><tr><td><code>baseball</code></td><td><ul><li><code>ncaa</code></li></ul></td><td>NCAA Baseball World Series Finals</td></tr><tr><td><code>softball</code></td><td><ul><li><code>ncaa-women</code></li></ul></td><td>NCAA Softball World Series Finals</td></tr><tr><td><code>boxing</code></td><td><ul><li><code>boxing</code></li></ul></td><td>Popular boxing games, for example Premier Boxing Champions</td></tr><tr><td><code>mma</code></td><td><ul><li><code>ufc</code></li></ul></td><td>Popular UFC games, for example UFC 246</td></tr><tr><td><code>tennis</code></td><td><ul><li><code>wimbledon</code></li><li><code>us-open</code></li></ul></td><td>Men’s and Women’s Singles Finals</td></tr><tr><td><code>golf</code></td><td><ul><li><code>masters</code></li><li><code>pga-championship</code></li><li><code>us-open</code></li><li><code>pga-tour</code></li></ul></td><td><ul><li>Augusta Masters all days of competition</li><li>PGA Championship all days of competition</li><li>USA Open all days of competition</li><li>Arnold Palmer weekend days of competition</li><li>Genesis Invitational weekend days of competition</li><li>Pebble Beach weekend days of competition</li><li>BMW Championship weekend days of competition</li><li>Farmers Insurance weekend days of competition</li></ul></td></tr><tr><td><code>soccer</code></td><td><ul><li><code>fifa-world-cup-women</code></li><li><code>fifa-world-cup</code></li><li><code>uefa-champions-league</code></li><li><code>concacaf-champions-league</code></li><li><code>concacaf-gold-cup</code></li><li><code>copa-america</code></li></ul></td><td><ul><li>FIFA World Cup Semis onward</li><li>UEFA Champions League Final</li><li>CONCACAF Champions League Final</li><li>CONCACAF Gold Cup Final</li><li>Copa America Final</li><li>UWNST World Cup Playoff matches</li></ul></td></tr></tbody></table>

Note: The sports type column is shown in the `event_label` field in the broadcast record.

**Date range coverage**

Live TV Events via the Broadcasts API covers sports games that started from November 1, 2021, to 90 days in the future (90 days from the current date).

**Location**

Live TV Events are available in the US.

#### Broadcast status

Broadcasts have three possible status values:

* **`scheduled`**\
  For those broadcasts where we know the date, time, and location of a TV broadcast based on TV schedule information. We enrich our data with television listings to determine their televised time and location (county).
* **`predicted`**\
  For these broadcasts where we predict their televised time and location (county). It means we don’t have detailed TV schedule information for the sports event. These events have high viewership and are assumed to be televised nationally (in all counties), they are typically one-off events or are finals of their respective competitions.\
  \
  We calculate viewership per county based on many factors including the amount of sports fans in different counties. This information is not as precise as those with the `scheduled` broadcast status but should give a reasonably accurate prediction of who will be watching these large events. You may want to use the `broadcast_status` parameter to indicate the confidence of a broadcast airing; you can build this as a feature or treat scheduled broadcasts differently from predicted.
* **`cancelled`**\
  The broadcast is no longer scheduled to be televised.

#### Date & time

<table data-header-hidden><thead><tr><th width="188">Date &#x26; Time Field</th><th align="center">Availability - Broadcast</th><th align="center">Availability - Event</th><th>Notes</th></tr></thead><tbody><tr><td>Start date</td><td align="center">Yes</td><td align="center">Yes</td><td><ul><li>Broadcast records have a start date and time in both UTC and local time where the broadcast is scheduled.</li><li>Physical events have a start date and time in both UTC and local time in the event timezone.</li></ul></td></tr><tr><td>End date</td><td align="center">No</td><td align="center">Yes</td><td><ul><li>The Broadcast record doesn’t have an end date or time available.</li><li>Physical events have an end date and time in both UTC and local time in the event timezone.</li></ul></td></tr><tr><td>Start time</td><td align="center">Yes</td><td align="center">Yes</td><td></td></tr><tr><td>End time</td><td align="center">No</td><td align="center">Yes</td><td></td></tr><tr><td>Predicted end time</td><td align="center">No</td><td align="center">Yes</td><td>For sports events where there is no official end time available, we predict end times using our machine learning models and intelligent algorithms. PredictHQ’s Predicted End Times feature provides end times for the physical event in it’s local timezone.</td></tr><tr><td>Timezone</td><td align="center">Yes</td><td align="center">Yes</td><td></td></tr></tbody></table>

#### Location / geopoint

The broadcast record presents the number of people who are watching the live sports game in a county. The latitude and longitude provided with the broadcast record under the geopoint element references the center of the county. For example, the center of Erie County in New York state shown in the later geopoint example.

The associated sports event is taking place in a physical location with the latitude and longitude pointing to the specific location. The venue name and address is also attached on the event record.

You can search the API or our WebApp by places at any [hierarchy level](https://docs.predicthq.com/api/places/get-place-hierarchies). The API returns the results at county level for the county where the place is located. For example, if you search for the broadcast in Bell City, Los Angeles, the API returns all broadcasts in Los Angeles County that match your other criteria.

## Ranking

**Predicted Viewership**

Predicted Viewership is the number of people who watch the live broadcast game in a county. Broadcast records have Predicted Viewership available:

```json
  "geopoint": {
      "lon": -78.77966,
      "lat": 42.75824
  },
```

#### Timeframe for broadcasts

The Live TV Events machine learning models predicted the viewership for sports games before they happen. We generate broadcast records 90 days before a sports game starts. However, we update viewership daily from 14 days before the event starts, providing more accurate data. To get the most accurate data we recommend using the broadcast viewership from 14 days before the event or sooner. You can use the viewership numbers that we generate between 90 days and 14 days before the event as a high-level, less accurate indication of viewership.

#### Physical event details

The Broadcasts API also returns the physical event details accordingly with all available information. You don’t need an event subscription to access relevant information. The physical event details include:

* **Event ID**: `event_id` of the physical event can be used to find all broadcasts nationwide for that specific sport game.
* **Label**: `event.label` for the physical sports event provides more information about the sports type and league. It can be used to find broadcasts for the specific sports type.
* **Entity**: The physical sports events have venue entities available.
* **PHQ Rank**: The physical sports events have PHQ Rank available.
* **Local Rank**: The physical sports events have Local Rank available.
* **Predicted Attendance**: The physical sports events have Predicted Attendance available.

The following example shows a broadcast response with these details:

```json
{
    "count": 1,
    "next": null,
    "previous": null,
    "overflow": false,
    "results": [
        {
            "broadcast_id": "u5aCvebffuNFpGSGNQFiU4",
            "updated": "2020-11-30T06:58:28Z",
            "first_seen": "2020-11-26T01:29:23Z",
            "dates": {
                "start": "2020-02-02T23:30:00Z",
                "start_local": "2020-02-02T15:30:00",
                "timezone": "America/Los_Angeles"
            },
            "location": {
                "geopoint": {
                    "lon": -122.4425,
                    "lat": 37.77823
                },
                "place_hierarchies": [
                    ["6295630","6255149","6252001","5332921","5391997"]
                ],
                "places": [
                    {
                        "place_id": "5391997",
                        "type": "county",
                        "name": "San Francisco County",
                        "county": "City and County of San Francisco",
                        "region": "California",
                        "country": "US"
                    }
                ],
                "country": "US"
            },
            "phq_viewership": 300609,
            "record_status": "active",
            "broadcast_status": "scheduled",
            "event": {
                "event_id": "svbfg9xT4YSVUeeAKp",
                "title": "Super Bowl - 49ers vs Kansas City Chiefs",
                "category": "sports",
                "labels": [
                    "american-football",
                    "nfl",
                    "sport"
                ],
                "dates": {
                    "start": "2020-02-02T23:30:00Z",
                    "end": "2020-02-03T03:11:00Z",
                    "start_local": "2020-02-02T18:30:00",
                    "end_local": "2020-02-02T22:11:00",
                    "predicted_end_local": "2020-02-02T21:25:00",
                    "timezone": "America/New_York"
                },
                "location": {
                    "geopoint": {
                        "lon": -80.23886040000002,
                        "lat": 25.9579665
                    },
                    "place_hierarchies": [
                        ["6295630","6255149","6252001","4155751","4164238","4161298"],
                        ["6295630","6255149","6252001","4155751","4149007","4155966"]
                    ],
                    "country": "US"
                },
                "entities": [
                    {
                        "entity_id": "wVgG7p8ZKRKEPPrNDq4my9",
                        "type": "venue",
                        "name": "Hard Rock Stadium",
                        "formatted_address": "347 Don Shula Dr\nMiami Gardens, FL 33056\nUnited States of America"
                    }
                ],
                "phq_attendance": 65326,
                "phq_rank": 86,
                "local_rank": 100,
                "aviation_rank": 99
            }
        }
    ]
}
```


# Labels

Event labels are succinct descriptive attributes attached to events that can help with granular data selection and feature engineering use cases.

All our events occur within a category. We also have labels that indicate the classification within a category. You can think of it as sub-category level information. Sports is a category in our system but if you want to know what type of sport an event is for, labels indicate it (e.g. `nfl`, `mls`, `nhl`, `nba`, etc)

For example, within the Conferences category, knowing the subject(s) covered within the conference (`science-and-technology`, `educational`, `automotive`, etc.) may help you narrow down on events that are relevant to your business. Keep these points in mind:

* Each event record has two separate label fields (`phq_labels` and the legacy `labels` field).
* All categories have `phq_labels`, which you should use by default.
* You can search event labels by using the `phq_labels` parameter.
* Some `labels` which repeats the category name such as `label: academic` have been removed.

### PHQ Labels

PredictHQ generates PHQ Labels using AI, and they achieve a higher standard of **specificity** and **relevance** in highlighting an event's key themes than the legacy labels.

This field is named `phq_labels`.

PHQ Labels are available for the following categories:

* Concerts
* Conferences
* Expos
* Festivals
* Performing Arts
* Community
* Academic
* Airport-delays
* Daylight-savings
* Disasters
* Health-warnings
* Observances
* Politics
* Public-holidays
* Severe weather
* School-holidays
* Terror
* Sports

#### PHQ Label values

We continuously improve and update PHQ Labels, so the set of values grows over time. The [full list of PHQ Label values](#all-phq-label-values) is on this page, refreshed daily, along with a CSV download. To see which labels appear on the events **within your PredictHQ plan** - and the count of events carrying each - use [Get event counts](https://docs.predicthq.com/api/events/get-event-counts).

Here is an example, for [Taylor Swift and Sabrina Carpenter](https://events.predicthq.com/events/ssZCJhGGKUswicJswa) at the Melbourne Cricket Ground in 2024 it has the following PHQ Labels (pop, country, and rock) in the API response:

```json
"phq_labels": [
  { "label": "pop", "weight": 0.51 },
  { "label": "country", "weight": 0.25 },
  { "label": "rock", "weight": 0.25 }
]
```

You could also use [Query Parameters](https://docs.predicthq.com/api/events/get-event-counts) to retrieve a list and the count of PHQ Labels that match your criteria, e.g. PHQ Labels associated with the sports category or PHQ Labels of events that will be taking place in a specific time and place. Here is an example:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/count",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    ## optional, get PHQ Labels and counts for sports category only
    # params={"category": "sports"}
)


# get PHQ Labels and the count of events having them from the response
phq_labels = response.json().get("phq_labels")

print(phq_labels)
# > {'basketball': 408197,'parade': 14327, ... }


```

You can also see a list of PHQ Labels in the **Labels** field on the [Search events](https://control.predicthq.com/search/events) page of the WebApp:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FMP7n2ALFNlShdNBjQvZD%2FScreenshot%202024-05-09%20at%2010.36.38%E2%80%AFAM.png?alt=media&amp;token=d32c34ad-1032-43a4-8a52-9c6b53338c7a" alt="The Labels field on the WebApp Search events page, showing a list of PHQ Labels"><figcaption><p>The <strong>Labels</strong> field in the WebApp contains a list of PHQ Labels</p></figcaption></figure>

#### All PHQ Label values

The full list of 248 PHQ Label values, refreshed daily from the live API. Prefer a CSV? Download [phq-labels.csv](https://raw.githubusercontent.com/predicthq/gitbook-tech-docs/main/assets/phq-labels.csv).

|                               |                                        |                                      |                          |
| ----------------------------- | -------------------------------------- | ------------------------------------ | ------------------------ |
| `academic-session`            | `academic-social`                      | `agriculture-forestry-and-fisheries` | `air-quality`            |
| `airport`                     | `alcohol`                              | `american-football`                  | `arson`                  |
| `art-and-cultural`            | `ashfall`                              | `assassination`                      | `attack`                 |
| `australian-football`         | `auto-racing`                          | `automotive`                         | `autumn-holiday`         |
| `avalanche`                   | `badminton`                            | `bars-closed`                        | `bars-open`              |
| `baseball`                    | `basketball`                           | `beauty-and-fashion`                 | `bicycle`                |
| `biological-hazard`           | `blizzard`                             | `bombing`                            | `boxing`                 |
| `business`                    | `celebration`                          | `charity`                            | `chemical`               |
| `chemical-accident`           | `christmas-holiday`                    | `circus`                             | `civil`                  |
| `climate-change`              | `closed-doors`                         | `coastal-event`                      | `cold-wave`              |
| `comedy`                      | `comedy-club`                          | `community-event`                    | `concert`                |
| `conference`                  | `construction-and-infrastructure`      | `consumer-goods`                     | `country`                |
| `cricket`                     | `cultural`                             | `cultural-performance`               | `cyclone`                |
| `delay`                       | `design-and-furnishing`                | `digital`                            | `dinner-theatre`         |
| `disaster-warning`            | `disasters-health`                     | `drought`                            | `dust`                   |
| `earthquake`                  | `easter-holiday`                       | `education`                          | `education-and-careers`  |
| `educational`                 | `election`                             | `electronic`                         | `entertainment`          |
| `entertainment-closed`        | `entertainment-open`                   | `epidemic`                           | `epidemic-hazard`        |
| `esports`                     | `estimated`                            | `exam`                               | `execution`              |
| `explosion`                   | `expo`                                 | `extreme-weather`                    | `f1`                     |
| `family`                      | `family-activities`                    | `family-fun`                         | `family-theatre`         |
| `festival`                    | `festivals-and-outdoor-activities`     | `fighting`                           | `financial-services`     |
| `fire`                        | `flood`                                | `fog`                                | `food`                   |
| `food-and-beverage`           | `football`                             | `general-theatre`                    | `golf`                   |
| `graduation`                  | `gymnastics`                           | `hail`                               | `hazardous-surf`         |
| `hazmat`                      | `health`                               | `health-warning`                     | `heat-wave`              |
| `hijacking`                   | `hip-hop-and-rnb-and-soul`             | `hockey`                             | `holiday`                |
| `holiday-christian`           | `holiday-hebrew`                       | `holiday-hindu`                      | `holiday-local`          |
| `holiday-local-common`        | `holiday-muslim`                       | `holiday-national`                   | `holiday-observed`       |
| `holiday-orthodox`            | `holiday-religious`                    | `horse-racing`                       | `hospitality-and-travel` |
| `hostage-crisis`              | `hurricane`                            | `hybrid-session`                     | `ice-hockey`             |
| `in-person-session`           | `industrial`                           | `indycar`                            | `ironman`                |
| `jazz-and-classical`          | `landslide`                            | `legal-and-property-services`        | `lifestyle`              |
| `literature-film-and-theater` | `lockdown`                             | `logistics-and-transportation`       | `lpga`                   |
| `management-and-consulting`   | `manufacturing-and-petroleum-products` | `marathon`                           | `market`                 |
| `mass-shooting`               | `medical`                              | `mining-drilling-and-metalwork`      | `minor-league`           |
| `mlb`                         | `mls`                                  | `mma`                                | `monster-truck`          |
| `motocross`                   | `motogp`                               | `movie`                              | `music`                  |
| `music-and-dance`             | `nascar`                               | `nature-and-outdoor-activities`      | `nba`                    |
| `nba-gleague`                 | `nba-summer-league`                    | `ncaa`                               | `nfl`                    |
| `nhl`                         | `nightlife`                            | `nuclear`                            | `observance`             |
| `observance-local`            | `observance-season`                    | `observance-united-nations`          | `observance-worldwide`   |
| `olympic`                     | `online-session`                       | `other`                              | `outdoor`                |
| `outdoor-sports`              | `parade`                               | `parliament`                         | `performing-arts`        |
| `personal-care-closed`        | `personal-care-open`                   | `pga`                                | `pop`                    |
| `post-season`                 | `pre-season`                           | `president`                          | `rain`                   |
| `rallies`                     | `recreation-closed`                    | `recreation-open`                    | `referendum`             |
| `regular-season`              | `religion`                             | `religion-and-spirituality`          | `restaurant-closed`      |
| `restaurant-open`             | `retail-closed`                        | `retail-open`                        | `rock`                   |
| `rodeo`                       | `rugby`                                | `running`                            | `sand`                   |
| `science-and-technology`      | `shooting`                             | `skating`                            | `snow`                   |
| `soccer`                      | `softball`                             | `sport`                              | `sport-fundraiser`       |
| `sport-marine`                | `sports-and-gaming`                    | `spring-holiday`                     | `stabbing`               |
| `storm`                       | `storm-surge`                          | `summer-holiday`                     | `suspected-attack`       |
| `suspected-bombing`           | `table-tennis`                         | `tennis`                             | `terror-politics`        |
| `terror-tourism`              | `terror-transportation`                | `terror-travel`                      | `textile`                |
| `thanksgiving-holiday`        | `thunderstorm`                         | `tornado`                            | `training`               |
| `transportation`              | `triathlon`                            | `tropical-storm`                     | `tsunami`                |
| `typhoon`                     | `vehicle-accident`                     | `visual-art`                         | `volcano`                |
| `volleyball`                  | `weather-warning`                      | `wellness`                           | `wildfire`               |
| `wind`                        | `winter-holiday`                       | `wnba`                               | `worship-closed`         |
| `worship-open`                | `wrestling`                            | `wwe`                                | `youth-sport`            |

### Labels (legacy)

The API still returns legacy labels to preserve backward compatibility with existing implementations.

This field is named `labels`.

Legacy labels are available for all event categories but are only available to customers who already had access. Download the full list of legacy label values: [legacy-labels.csv](https://raw.githubusercontent.com/predicthq/gitbook-tech-docs/main/assets/legacy-labels.csv).

### Usage

Use labels in:

* [Labels in the Events API](https://docs.predicthq.com/api/events/search-events)


# Entities

Entities are things with defined attributes, such as performers, music bands, venues, sports teams, and more. Our entities system is integral to our verification, enrichment, deduplication, and ranking processes. Entities allow us to accurately estimate attendance and impact given that they are stable as opposed to a moving object such as ticket sales.

For example, a concert will take place in or at a venue entity, where people will watch a performer entity. Our system factors in the popularity of a performer like Beyoncé when we rank her concert. A Beyoncé concert would likely rank much higher than a lesser-known artist.

## **Venue entities**

A venue is a physical location where an event happens. It could be an indoor area, e.g. xx hotel - conference room; or an entire building, e.g. xx stadium; or an outdoor area, e.g. xx park.

PredictHQ provides venues with latitude, longitude, and address to locate the event.

A venue can be found on an event record as an array of entities with the type of `venue`.

All events happening at the same venue have the same latitude/longitude and street address.

The following is an example of the venue entity information returned in the Events API response:

```json
{
  "entity_id": "hH4zrx9zYLiETvNZQrx2de",
  "name": "Moscone Center - West",
  "type": "venue",
  "formatted_address": "800 Howard Street\nSan Francisco, CA 94103\nUnited States of America"
},
```

## **Event group entities**

Stored within the entities section on an event, an event group identifies [recurring events](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-recurring-events) across the PredictHQ events dataset. For example, The (Summer) Olympics repeats every four years around summer time, therefore we would have an event group that is attached to all of our Summer Olympics events.

Events that are associated with event groups have the `recurring` label and also contain an entity with the type of `event-group` within the event data.

See [working with recurring events ](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-recurring-events)for more details.

### Residencies entities

Residencies are a subset of event groups. Residencies describe a type of concert where an artist performs at the same venue for two or more shows. This means that residencies can last for several weeks or months, as long as each instance of a performance by the same artist is within one week (7 days) of one another.

The `residency` label attached to the event group identifies residencies, as in this example:

```json
        {
          "entity_id": "Hi7e2hz97iXk4EwDwNmMdx",
          "name": "Sabrina Carpenter, Taylor Swift at Melbourne Cricket Ground",
          "type": "event-group",
          "category": "concerts",
          "labels": [
            "residency"
          ]
        }
```

## Organization entities

{% hint style="info" %}
Not all plans and subscriptions have access to this type of entity. [Talk to us](https://www.predicthq.com/contact/sales) if you'd like access.
{% endhint %}

Organization entities are groups of people and include sports teams (e.g. Kansas City Chiefs), and bands (e.g. Coldplay).

The following is an example of organization entities showing two sports teams playing in an NFL game event:

```json
{
    "name": "Penn State Nittany Lions",
    "entity_id": "dkDMujewgkq35ytXgE9KEe",
    "type": "organization"
},
{
    "name": "Ohio State Buckeyes",
    "entity_id": "NQ9CEvhtfZBYBFi6pdZE26",
    "type": "organization"
}
```

## People entities

{% hint style="info" %}
Not all plans and subscriptions have access to this type of entity. [Talk to us](https://www.predicthq.com/contact/sales) if you'd like access.
{% endhint %}

People entities include individual performers like singers/musicians (e.g. Beyoncé), or comedians (e.g. Bill Burr). They also include individual sports people like golfers (e.g. Tiger Woods), tennis players (e.g. Roger Federer), motorsports drivers (e.g. Lewis Hamilton), and other types of individuals.

The following is an example of people entities showing performers for a concert:

```json
{
    "entity_id": "35cav6EYSVnsykJ8cTvggTD",
    "type": "person",
    "name": "Lionel Richie"
},
{
    "entity_id": "ksqpXJDQbmBiS6aYeTeANF",
    "type": "person",
    "name": "Billy Joel"
},
{
    "entity_id": "mALZFGmtWQKpm4E6pFskha",
    "type": "person",
    "name": "Sheryl Crow"
}
```

## Getting back all events for an entity with the API

To get back all events linked to an entity you can call the Events API by entity ID. You can use this to find all events at a venue, all instances of a recurring event, or all events linked to a people or organization entity.

For example the entity ID for the "Moscone Center - West" is hH4zrx9zYLiETvNZQrx2de. So if you query the events for that ID you get back all events held at the Moscone Center - West. You can then use other filters to narrow down the time period, ranks, or anything else.

Here is an example of calling the Events API using the Moscone Center - West entity ID:

```
GET https://api.predicthq.com/v1/events?entity.id=hH4zrx9zYLiETvNZQrx2de HTTP/1.1
Accept: application/json
Authorization: Bearer $API_TOKEN
```

Similar to finding all events for an event-group entity for recurring events, first find the ID for the entity. For example, to do that for Dreamforce:

1. Find a Dreamforce event.
2. On that event, look at the event-group entity ID.
3. To call the API, use that entity ID.

## How can I use entities in Snowflake

Snowflake returns entity information in the ENTITIES column. That contains all the entities' information mentioned earlier. You can query that column to find all events for an entity or to retrieve the relevant entities for an event

## What is the difference between labels and entities?

The difference between labels and entities is that labels describe the type of event whereas entities provide a 'link' from an event to a venue, performer, sports team, or other type of entity. Labels tell you what type of sport an event is for (e.g. `nfl`) but they don't tell you what venue the event is held at or if the event is recurring. For concerts or festivals, labels tell you whether the event is a rock music concert but not what band is playing. Entities provide information on the sports team for sports events, bands for music events, and so on.


# Ranks

Two scores quantify an event's expected impact, both on a logarithmic 0-100 scale:

* [PHQ Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/phq-rank) - global impact, normalized worldwide. Use it to compare events across locations.
* [Local Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/local-rank) - impact relative to the surrounding population. Use it to find events that matter locally - a 5,000-person event means more in a small town than a big city.

In practice you rarely set rank thresholds by hand: a Beam Analysis calibrates them per location, and passing `beam.analysis_id` to the Events and Features APIs applies them automatically. For manual starting points, see [Recommended Event Categories and Local Rank Thresholds](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters).


# PHQ Rank

PHQ Rank is a numeric value on a logarithmic scale between 0 and 100 to represent the impact of the event. The larger the value of the rank, the higher the impact of the event.

PHQ Rank has these properties:

* PHQ Rank is independent of the event’s location.
* PHQ Rank for non-attended categories and unscheduled categories are further explained under each category.
* PHQ Rank is comparable between attended events in terms of the event’s size or impact.


# Local Rank

Local Rank is a numeric value on a logarithmic scale between 0 and 100 to represent the impact of an event to its local area. Local Rank may vary even though the PHQ Rank of the events are the same. For example, a conference with 1,000 people in attendance (with PHQ Rank 50) has a [Local Rank of 43 in Hong Kong](https://events.predicthq.com/events/KKtBoCYP3gWPvgGhnp) where the local population density is around 64,000, while a [Local Rank of 65 in Dublin, Ireland](https://events.predicthq.com/events/0lrweBnDZKrr) where the local population density is around 5,000. Local Rank has this property:

* Local Rank is comparable between the attended events in terms of the event’s impact to its local area.


# Predicted Attendance

Predicted Attendance represents the number of people predicted to attend an event.

This value represents the number of people predicted to attend an event. The [Events API response](https://docs.predicthq.com/api/events/search-events) returns the exact Predicted Attendance number as the `phq_attendance` value for attendance-based events.

PHQ Rank also has a value between 0 and 100 that represents how many people will attend an event. For example, an event with a PHQ Rank 50 has around 1,000 attendance.

PHQ Rank, Local Rank, and Predicted Attendance use the following table to translate the numeric value to rank level and tier.

<table><thead><tr><th width="215">PHQ Rank Level</th><th width="213">PHQ Rank Range</th><th>Expected Attendance</th></tr></thead><tbody><tr><td>1 - Minor</td><td>0 - 10<br>11 - 20</td><td>~10<br>~30</td></tr><tr><td>2 - Moderate</td><td>21 - 30<br>31 - 40</td><td>~100<br>~300</td></tr><tr><td>3 - Important</td><td>41 - 50<br>51 - 60</td><td>~1,000<br>~3,000</td></tr><tr><td>4 - Significant</td><td>61 - 70<br>71 - 80</td><td>~10,000<br>~30,000</td></tr><tr><td>5 - Major</td><td>81 - 90<br>91 - 100</td><td>~100,000<br>~300,000+</td></tr></tbody></table>

These mappings are sometimes referred to as ranking bands.

## How PredictHQ calculates Predicted Attendance

PredictHQ calculates Predicted Attendance via machine learning models (ML models) and expert systems in our pipeline. We train our ML models on historical data, and they predict the number of people that are predicted to attend a future event before they happen. Our models use a large number of inputs (called machine learning features) to make an accurate prediction.

PredictHQ monitors the accuracy of their models and periodically retrains them to ensure we retain high-accuracy predictions.

### Examples of models used for Predicted Attendance

We have ML models to predict attendance for all our attended categories. Some types of events within some categories may use expert systems instead of machine learning models. For example, although most of our main sports within the sports category use ML models, Formula 1 race events do not use an ML model.

ML models use machine learning features as inputs to predict attendance. These features are different pieces of data that allow the model to make an accurate prediction based on different factors. For example, the sports teams playing, the type of sport, and the venue a sports game is played all affect the Predicted Attendance. If two very popular sports teams play at a large stadium then they are more likely to have more people attending the game.

The following sections give examples of ML models and the factors they use to predict attendance.

#### Sports model - features used

The sports model uses these ML features to predict how many people will attend a sporting event:

* Teams
* Venue
* Sport
* Duration
* Weekday/Weekend
* Gender
* Recurring Event
* International/Domestic
* Tournament
* And more

#### Concerts model - features used

The concerts model uses these ML features to predict how many people will attend a concert event:

* Music genre
* Record label
* Population density
* Venue capacity
* Performer data
* Ticket sales
* And more

#### Performing arts model - features used

The performing arts model uses these ML features to predict how many people will attend a performing-arts event:

* Type of event
* Venue capacity
* Ticket sales
* Duration
* Start time
* Number of performers
* Population density
* And more

**Conferences model - features used**

The conferences model uses these ML features to predict how many people will attend a conference event:

* Event density
* Venue capacity
* Location
* Duration
* Start time
* Population density
* And more

### Expert systems and other types of models

We also have other specialist models for some types of events. For example, we have a specific model that predicts attendance for Youth Sports that uses features like age groups, student numbers, the number of teams in a tournament, and more to make specific attendance predictions for Youth Sports events.

Where we don’t have models we use the following data to predict attendance:

* Venue capacity
* Maximum Attendance
* Recurring event group attendance
* Provider future attendance
* Provider-specific ranking methods

We also update sports events with actual attendance after they happen (mainly major US sports and major soccer leagues)


# Predicted End Times

Many events don’t have end times, which is critical information for our transport and on-demand customers. For example, for sports events, around 80% or more of source event data doesn’t have a known end time.

This is usually because end times for a sports game or a concert are recorded after the event finishes. Yet many of our transport customers need a Predicted End Time for future scheduled events (which means providing the end time before the event finishes).

The end time and duration of an event is a key piece of information for event data. The goal of this feature is to increase our end-time coverage.

The Predicted End Times feature uses machine learning and our intelligent algorithms to predict event end times. The goal is that you can use the Predicted End Time where an actual known end time is not present.

Predicted End Times covers a subset of categories which are [**sports**](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events#sports)**,** [**concerts**](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events#concerts)**,** and [**performing arts**](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events#performing-arts).

For sports events Predicted End Times covers eight sports (American football, Basketball, Baseball, Ice-hockey, NASCAR, Soccer, Rugby, and Australian rules football).

For performing arts and concerts events all performing arts events that don't have an actual end time have a predicted end time.

You can use Predicted End Times in these example use cases:

* **Workforce Optimization**: For transportation companies if you want to arrange transportation for people leaving an event you can use Predicted End Times.
* **Demand Forecasting**: When forecasting the impact of events in certain time periods the end time of the event is required.

## How Predicted End Times are calculated

We use a combination of methods, and the availability of historical data largely determines which ones we use. For event types with historical data, we use machine learning methods including linear regression and quantile regression.

For sports, these models use features such as gender, season, and leagues. For event types without historical data, we use research-based methods e.g. using the mean, using track and series estimates for NASCAR. As a result, our predictions for these events may be less robust. Across all sports types, we cover Professional, College, and International types, where applicable.

<table data-full-width="true"><thead><tr><th>Category</th><th>Type</th><th>Professional sport</th><th>College sport</th><th>International sport</th><th>Non-sport</th></tr></thead><tbody><tr><td>Sport</td><td>Ice-hockey</td><td>Model-based</td><td>Research-based</td><td>Model-based</td><td>N/A</td></tr><tr><td>Sport</td><td>Rugby</td><td>Model-based</td><td>Model-based</td><td>Model-based</td><td>N/A</td></tr><tr><td>Sport</td><td>Basketball</td><td>Model-based</td><td>Research-based</td><td>Research-based</td><td>N/A</td></tr><tr><td>Sport</td><td>Australian Football</td><td>Model-based</td><td>Model-based</td><td>Model-based</td><td>N/A</td></tr><tr><td>Sport</td><td>American Football</td><td>Model-based</td><td>Model-based</td><td>Research-based</td><td>N/A</td></tr><tr><td>Sport</td><td>Football/Soccer</td><td>Research-based</td><td>Research-based</td><td>Research-based</td><td>N/A</td></tr><tr><td>Sport</td><td>Baseball</td><td>Model-based</td><td>Research-based</td><td>Research-based</td><td>N/A</td></tr><tr><td>Sport</td><td>NASCAR</td><td>Research-based</td><td>Research-based</td><td>Research-based</td><td>N/A</td></tr><tr><td>Performing arts</td><td>All</td><td>N/A</td><td>N/A</td><td>N/A</td><td>Research-based</td></tr><tr><td>Concerts</td><td>All</td><td>N/A</td><td>N/A</td><td>N/A</td><td>Research-based</td></tr></tbody></table>

## Predicted End Times in PredictHQ API

The Events API supports the Predicted End Times feature through the following:

* You can sort events on the Predicted End Time value by using the `sort` parameter with a value of `predicted_end` or `-predicted_end`.
* You can filter on Predicted End Times by specifying a date range with the `predicted_end.*` parameter.
* The Events API returns the Predicted End Time as the `predicted_end` field in the events response data. This field is present only if an actual end time is not available for the event and we have a Predicted End Time. The predicted end date of the event in ISO 8601 format.

**Note**: The Predicted End Time and all other start and end times are in UTC if the event time zone is provided, and in local time otherwise. For example, Independence Day falls on the 4th of July regardless of the timezone and has a null time zone.

#### How to use the API

If an event does not have a valid end time then the predicted\_end field is present in the response. To use Predicted End Times you can implement logic that checks if the predicted\_end field is present. The logic should be: - If the `predicted_end` field is present then use `predicted_end` field value for the event end time. - If the `predicted_end` field is not present use the `end` field for the event end time.

You can also use the `sort` parameter to sort by the end time and the predicted\_end where needed.

Note:

* A Predicted End Time is a predicted value, not an actual end time value. It is based on various machine learning models and statistical methods. We aim to have good accuracy on average but there is a margin of error in the value. Take this into account when you use the value.
* For events that don’t have an end time the Events API sets the end time to the start time in its response.

## Examples

### Event with a Predicted End Time

This event has a `predicted_end` field in its response:

```json
{
    "id": "hHkH8zLEYGA2zBH3ka",
    "title": "NBA - Los Angeles Lakers vs Sacramento Kings",
    "description": "",
    "category": "sports",
    ...
    "start": "2020-04-15T02:30:00Z",
    "end": "2020-04-15T02:30:00Z",
    "predicted_end": "2020-04-15T04:50:00Z",
    "updated": "2019-08-13T06:21:03Z",
    "first_seen": "2019-08-13T02:25:35Z",
    ...
}
```

### Event with a scheduled end time

This event has an actual end time and no `predicted_end` field:

```json
{
    "id": "vaUVM7J4nwfNVngoxy",
    "title": "Washington Nationals vs Los Angeles Dodgers",
    ...
    "start": "2019-10-04T00:37:00Z",
    "end": "2019-10-04T04:01:15Z",
    "updated": "2019-10-07T02:58:30Z",
    "first_seen": "2019-08-06T07:01:03Z",
    ...
}
```


# Predicted Event Spend

PredictHQ’s Predicted Event Spend is a dollar figure that reflects the predicted amount of consumer spend across **accommodation, hospitality,** and **transportation** in a specific area as a result of events happening nearby. At the core of this figure sits our market leading global event coverage, Predicted Attendance, local accommodation demand, third party data, and more which culminate into a contextual and attributable dollar figure that can be used to power both insights and forecasting models.

Predicted Event Spend demonstrates how individual or groupings of events drive massive spending on behalf of visitors and is a reflection of the total amount of additional spending within a defined area as a result of a specific event.

All Predicted Event Spend values are in United States Dollars (USD$).

## Coverage

Predicted Event Spend is available for the following [event categories](https://docs.predicthq.com/getting-started/predicthq-data/event-categories):

* Sports
* Conferences
* Expos
* Concerts
* Festivals
* Performing Arts
* Community

Within each event category, Predicted Event Spend covers the following industries/sectors:

* Accommodation - Hotels, lodgings, and hosts.
* Hospitality - Food and Beverage. Hotel restaurant spend is contained here.
* Transportation - Ground-based public and private transportation.

## Using Predicted Event Spend

You can access Predicted Event Spend here:

* [In the Events API](https://docs.predicthq.com/api/events/search-events)


# Predicted Events

Get insight into events as early as possible, to assess whether they would have an impact on your business.

Predicted Events are events that haven’t been scheduled or even announced yet, but are predicted to occur—based on years of historical event, demand, and venue data. This provides a degree of probability for when and where these events will happen to enable you to plan well before anyone else – at scale.

Predicted Events have their own status, and you can search and retrieve them just as any other event. Stay up to date with changes to event status, so if the event is ultimately scheduled – it moves from a `predicted` event, to an `active` event with confirmed event details, including start times and more. If the predicted event is canceled or postponed, the event status updates to reflect this. You can see this in both the web UI or via API by setting the `state` filter to `predicted`.


# Predicted Impact Patterns

This field shows the impact of leading days (days before the event), lagging days (days after an event), and the days the event occurs. For example, if someone is taking a flight to a location to attend a concert, they are typically not going to be arriving on the day of the event. They will often arrive a couple of days before and check into their hotel before the concert begins. The Predicted Impact Patterns for accommodation reflects the fact that this demand will be felt before the event starts and often after it ends. Predicted Impact Patterns are industry-specific and reflect the varying leading and lagging impact of events on different industries.

{% hint style="success" %}
We recommend that if you operate in the supported industries you use Predicted Impact features instead of the generic features as these result in greater forecast accuracy as they include the impact before an event starts and after it finishes. In our testing we have found significant forecasting accuracy improvements from using Predicted Impact features in demand forecast machine learning models.
{% endhint %}

The following diagram shows Predicted Impact Patterns:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F9kVflaqtBHe0wRROwWEI%2Fimage.png?alt=media&amp;token=489c051b-e2df-4c81-9669-22eb58336116" alt="Diagram of a Predicted Impact Pattern showing impact on leading days before an event, on event days, and on lagging days after it"><figcaption></figcaption></figure>

You can use Predicted Impact Patterns in your demand forecasting so that your machine learning models account for the impact on leading and lagging days. In our testing we have found using Predicted Impact Patterns increases forecasting accuracy.

#### Vertical, type, and category mapping

Predicted Impact Patterns are available for these industry segments and categories:

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

| Impact Type      | Category          |
| ---------------- | ----------------- |
| `phq_rank`       | `public-holidays` |
|                  | `observances`     |
| `phq_attendance` | `community`       |
|                  | `concerts`        |
|                  | `conferences`     |
|                  | `expos`           |
|                  | `festivals`       |
|                  | `performing-arts` |
|                  | `sports`          |
| {% endtab %}     |                   |

{% tab title="Retail" %}

| Impact Type      | Category          |
| ---------------- | ----------------- |
| `phq_rank`       | `public-holidays` |
|                  | `observances`     |
|                  | `severe-weather`  |
| `phq_attendance` | `community`       |
|                  | `concerts`        |
|                  | `conferences`     |
|                  | `expos`           |
|                  | `festivals`       |
|                  | `performing-arts` |
|                  | `sports`          |
| {% endtab %}     |                   |

{% tab title="Hospitality (Restaurants)" %}
Predicted Impact Patterns features for this industry use the name `hospitality` but this category covers food & beverage including restaurants.

| Impact Type      | Category          |
| ---------------- | ----------------- |
| `phq_rank`       | `public-holidays` |
|                  | `observances`     |
| `phq_attendance` | `community`       |
|                  | `concerts`        |
|                  | `conferences`     |
|                  | `expos`           |
|                  | `festivals`       |
|                  | `performing-arts` |
|                  | `sports`          |
| {% endtab %}     |                   |
| {% endtabs %}    |                   |

## Predicted Impact Patterns in the Events API

The [Events API](https://docs.predicthq.com/api/events/search-events) returns Predicted Impact Patterns in the `impact_patterns` field of its response. This shows the Predicted Impact Patterns for each event. The following are the details of the data structure of that field.

`impact_patterns` is an array of impact pattern objects. The same event can have different Predicted Impact Patterns for different industry verticals. It contains the following fields:

* `vertical` - The industry vertical the impact pattern applies to.
* `impact_type` - Indicates the type of impact shown in the impact pattern. This applies to either `phq_rank` or `phq_attendance`, depending on the vertical.

`impacts` is an array of objects with one entry for each day that contains the following values:

* `date_local` - the date in the local timezone of the event.
* `value` - the value of the `impact_type` for that given day. For example, if the `impact_type` was `phq_rank` the value would be the PHQ Rank value on the given day. In the case for `accommodation` or `hospitality` where the `impact_type` is `phq_attendance`, the API returns the `phq_attendance` value in this field.
* `position` - is `leading`, `event_day`, or `lagging`. `leading` are the days before the event occurs, `event_day` are the days the event occurs, and `lagging` are the days after the event has occurred.

For `accommodation` and `hospitality` events:

```json
"impact_patterns": [
    {
        "vertical": "accommodation",
        "impact_type": "phq_attendance",
        "impacts": [
            {"date_local": "2018-02-26", "value": 14250, "position": "leading"},
            {"date_local": "2018-02-27", "value": 14250, "position": "leading"},
            {"date_local": "2018-02-28", "value": 85500, "position": "leading"},
            {"date_local": "2018-03-01", "value": 95000, "position": "event_day"},
            {"date_local": "2018-03-02", "value": 95000, "position": "event_day"},
            {"date_local": "2018-03-03", "value": 95000, "position": "event_day"},
            {"date_local": "2018-03-04", "value": 95000, "position": "event_day"},
            {"date_local": "2018-03-05", "value": 33250, "position": "lagging"},
            {"date_local": "2018-03-06", "value": 4750, "position": "lagging"},
        ],
    }, {
        "vertical": "hospitality",
        "impact_type": "phq_attendance",
        "impacts": [
            {"date_local": "2018-02-26", "value": 16151, "position": "leading"},
            {"date_local": "2018-02-27", "value": 40850, "position": "leading"},
            {"date_local": "2018-02-28", "value": 40850, "position": "leading"},
            {"date_local": "2018-03-01", "value": 95000, "position": "event_day"},
            {"date_local": "2018-03-02", "value": 95000, "position": "event_day"},
            {"date_local": "2018-03-03", "value": 95000, "position": "event_day"},
            {"date_local": "2018-03-04", "value": 95000, "position": "event_day"},
            {"date_local": "2018-03-05", "value": 14250, "position": "lagging"},
        ],
    }
]

```

For `retail` severe weather events:

```json
"impact_patterns": [
    {
        "vertical": "retail",
        "impact_type": "phq_rank",
        "imputed_impact_pattern": true,
        "impact_range_start_dt": "2018-02-03T15:00:00+00:00",
        "impact_range_end_dt": "2018-02-07T14:59:59+00:00",
        "impacts": [
            {"date_local": "2018-02-04", "value": 40, "position": "leading"},
            {"date_local": "2018-02-05", "value": 64, "position": "event_day"},
            {"date_local": "2018-02-06", "value": 50, "position": "lagging"},
            {"date_local": "2018-02-07", "value": 50, "position": "lagging"},
        ],
    }
]

```

## Predicted Impact Patterns in the Features API

You can also use Predicted Impact Patterns with the Features API. The Features API provides pre-built machine learning features for demand forecasting. See the [Features API](https://docs.predicthq.com/api/features/get-features) documentation. For more accurate forecasting results, use the features for your industry. We have a generic feature without Predicted Impact Patterns for sports called `phq_attendance_sports` but that does not include Predicted Impact Patterns so only shows the impact on the days of the event. To use Predicted Impact Patterns with the Features API, use the features for your industry. For example, if you are in the accommodation segment and are using the Features API to find the impact of sports events on your location you would use `phq_attendance_sports_accommodation`. If you were in the Hospitality Segment you would use `phq_attendance_sports_hospitality`.


# Guides

Task-level guides for working with PredictHQ data and APIs, grouped by topic: [geolocation](https://docs.predicthq.com/getting-started/guides/geolocation-guides), [dates and times](https://docs.predicthq.com/getting-started/guides/date-and-time-guides), [Events API](https://docs.predicthq.com/getting-started/guides/events-api-guides), [Features API](https://docs.predicthq.com/getting-started/guides/features-api-guides), [Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides), [Live TV Events](https://docs.predicthq.com/getting-started/guides/live-tv-event-guides), and [Beam](https://docs.predicthq.com/getting-started/guides/beam-guides). Guides for BI tools and data warehouses live with the [integrations](https://docs.predicthq.com/integrations/third-party-integrations) they serve.

Guides answer "how do I do this specific thing." For what to build in the first place, start with [How to use PredictHQ](https://docs.predicthq.com/getting-started/how-to-use-predicthq) and the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) - the guides here fill in the details of whichever path you're on.


# Geolocation guides

How to scope PredictHQ queries to the places your business cares about.

The recommended pattern is one setup step: create a [Saved Location](https://docs.predicthq.com/api/saved-locations/overview) from a lat/lon origin and let Predicted Impact Area calculate the boundary where events actually affect that location - then reference the `location_id` everywhere. The guides in this section cover the underlying mechanics when you need them: [searching by location](https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location), [place hierarchies](https://docs.predicthq.com/getting-started/guides/geolocation-guides/understanding-place-hierarchies), [polygons](https://docs.predicthq.com/getting-started/guides/geolocation-guides/working-with-polygons), and [joining events with Placekey](https://docs.predicthq.com/getting-started/guides/geolocation-guides/join-events-using-placekey).

Avoid hand-picked fixed radii - they include irrelevant events and miss relevant ones. See the [overview](https://docs.predicthq.com/getting-started/guides/geolocation-guides/overview) for how the location methods compare.


# Overview

Geographic information for an event describes where the event is located and the geographic area impacted. This page introduces geographic information available in events:

<table><thead><tr><th width="346">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>geo.geography</code></td><td>Geo data in GeoJSON format for the area impacted by the event.</td></tr><tr><td><code>place_hierarchies</code> and <code>scope</code></td><td>Place where the event is located.</td></tr></tbody></table>

Events also have the `formatted_address` field for [venue entities](https://docs.predicthq.com/getting-started/predicthq-data/entities) with the street address of an event where it is present.

{% hint style="info" %}
The `location` field is deprecated. Use the `geo` field for geographic information.
{% endhint %}

## **Points and areas**

Latitude and longitude coordinates represent a point event's location. An example is this [MLB game](https://events.predicthq.com/events/97iX53YAGnCwF9TGx3) located at `37.77859,-122.38926`.

Area events impact a geographic area such as a region, or an entire country. For example, [Christmas Day in the United Kingdom](https://events.predicthq.com/events/KmzdXpxZEq9M), is a country-wide public holiday.

A polygon can represent area events. The example image shows this [flood warning](https://events.predicthq.com/events/24gdWYbR9M7DzJBVdY) for several rivers in Mississippi, USA.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FgcMMYYhkDm8tkiKsv7qT%2Fflood-warning-example.png?alt=media&amp;token=6b086d9d-d9f8-4a91-8c61-902b0ec74142" alt="Map showing a polygon that outlines the area covered by a flood warning for several rivers in Mississippi, USA"><figcaption></figcaption></figure>

Our APIs offer spatial search parameters to discover all events that impact your locations of interest.

## Basic location

The `geo` field in the Events API response contains the longitude and latitude for point events. The following is an example of the location information for point events in the `geo` field. For a point type geometry object the coordinates are in the order longitude, latitude (as this follows the [geojson standard](https://geojson.org/)). Here is an example:

```
    "geo": {
        "geometry": {
            "coordinates": [
                -88.9746153,
                30.393504
            ],
            "type": "Point"
        },
    ...
    },
```

{% hint style="info" %}
In the `geo.geometry` field we follow the GeoJSON standard which orders coordinates as longitude followed by latitude (i.e., `[longitude, latitude]`).
{% endhint %}

For a point event, its `location` coordinates are where the event occurs. This may be the location of a venue. For example, a [San Francisco Giants MLB game at Oracle Park](https://events.predicthq.com/events/97iX53YAGnCwF9TGx3) has a latitude and longitude of `-122.38926979999997, 37.7785951`, which corresponds to the address of Oracle Park, 24 Willie Mays Plaza.

For an area event that does not have a polygon, its coordinates are the center of the area where the event occurs.

Area events cover either a Geonames Place, for example [Thanksgiving Day](https://events.predicthq.com/events/gEkxDPqErD5n), or a specific geographic area bounded by a geometry (polygon). The next section details geometries and polygons, additional geometric data available in the `geo` field for area events. See [GeoJSON ](#geojson)for more information.

#### Location field (deprecated)

The `location` field was previously used for latitude and longitude information. The `location` field's value contains coordinates in [GeoJSON](https://geojson.org/) order: `[longitude, latitude]`. Note the `geo` field is preferred over the `location` field because the `location` field is deprecated.

## Address data in the geo field

The `geo` field also contains address information. The **address** subfield within the `geo` field can contain the following information:

* `country_code` (required) - two-letter country code
* `formatted_address` (optional) - a fully formatted address which can include street address, locality, postcode, region, and country
* `postcode` (optional)
* `locality` (optional) - indicates the city or town the event occurs in
* `region` (optional) - the region or state at which the event takes place

For attended events when they are linked to a [venue entity](https://docs.predicthq.com/getting-started/predicthq-data/entities#venue) then the address information corresponds to the address of the venue.

Events that cover a larger area (for example non-attended events like holidays) tend to have less address information. For example, a country-wide holiday may only have the country code field in the address field.

This later example shows the address subfield within the `geo` field:

```json
"geo": {
    "geometry": {
        "coordinates": [
            -88.9746153,
            30.393504
        ],
        "type": "Point"
    },
    "placekey": "@8f4-wyy-4y9",
    "address": {
        "country_code": "US",
        "formatted_address": "2350 Beach Blvd, Biloxi, MS 39531, USA",
        "postcode": "39531",
        "locality": "Biloxi",
        "region": "Mississippi"
    }
},
```

## GeoJSON

The `geo` field contains geometry information about an event's location in [GeoJSON](https://geojson.org/) format. Point events have a Point-type geometry, with the coordinates of the event's location (same as the `location` field). Area events may have Polygon or MultiPolygon-type geometries representing the specific area impacted by the event.

Where an area event has a Point-type geometry, it means the event applies to the Geonames Place of the event. The following response shows an event with a Polygon geometry:

```json
{
  "count": 1,
  "results": [
    {
      "id": "268aCtdaPgDJNurMeP",
      "title": "Flood Warning",
      "geo": {
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [-94.15, 39.1599999],
              [-94.17, 39.220000000000006],
              [-93.86, 39.25000000000001],
              [-93.84, 39.18000000000001],
              [-94.05, 39.11000000000001],
              [-94.15, 39.1599999]
            ]
          ]
        }
      }
// other fields omitted...
```

The example event snippet is a [flood warning in Missouri](https://events.predicthq.com/events/268aCtdaPgDJNurMeP). The GeoJSON data in the `geo.geometry` field can be plotted using tools that accept GeoJSON such as [geojson.io](https://geojson.io/). All our events with a Polygon or MultiPolygon display the geometry's shape when viewed in our [WebApp](https://control.predicthq.com/search/events/268aCtdaPgDJNurMeP) or our [Public Event page](https://events.predicthq.com/events/268aCtdaPgDJNurMeP). The following image plots the flood warning event's geometry.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FzFZuS0y9iujtdUHEMrhP%2Fevent-polygon-example.png?alt=media&amp;token=0d31f9fa-b59d-4968-a633-913ab1e8db1a" alt="Plot of the flood warning event&#x27;s polygon geometry on a map"><figcaption></figcaption></figure>

The following image shows an example of an [event with a MultiPolygon geometry](https://events.predicthq.com/events/8qbpLh7PDjK3Crpj6b); you can see it has two polygons for one event.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FD0gIAF3Bl9mgKrPHsqI9%2Fevent-multipolygon-example.png?alt=media&amp;token=57adc18c-edaa-4c44-aa9c-55b966a8325f" alt="Map showing an event with a MultiPolygon geometry made up of two separate polygons"><figcaption></figcaption></figure>

We provide examples and code snippets to plot polygons in a Jupyter notebook in our [Severe-Weather Events Data Exploration](https://github.com/predicthq/phq-data-science-docs/blob/master/severe-weather-events/part_2_data_exploration.ipynb) notebook.

### Simplified polygons

Our raw polygon sources can have extremely detailed geometries which result in large GeoJSON filesizes. Polygons of this nature aren't practical to use for individual events either in the PredictHQ API or a customer's data lake. The complexity of such polygons often result from capturing geographic features that aren't relevant for practical use cases in determining the impact of an event (for example small bodies of water, or small unpopulated islands off a coast).

For this reason, we may pre-process polygons to simplify them to reduce the number of points. This results in smoothing out the shape while retaining the key boundaries of the geographic area of impact.

In the example images, the first polygon is part of a raw polygon before simplification; the second is after simplification. The original GeoJSON data contained about 18000 coordinate points (the JSON data for this alone is around 700kb) to accurately outline individual offshore land masses.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FzS7D5O4dYs3vMHWUzamf%2Fmaine-county-raw.png?alt=media&amp;token=24913b87-606a-404f-8904-475b352e1fa5" alt="Map of a Maine county showing the detailed raw polygon outline, including offshore land masses, before simplification"><figcaption><p>Raw polygon before simplification</p></figcaption></figure>

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FOLMNW205eZXh9hCEENwv%2Fmaine-county-simplified.png?alt=media&amp;token=9cf21939-2e8d-4ed9-9497-61d77d3fb2a5" alt="Map of a Maine county showing the smoothed polygon outline after simplification, with the key boundaries retained"><figcaption><p>Polygon after simplification</p></figcaption></figure>


# Searching by location

Performing a radial search using our Events API's `within` parameter is a common way to find events that impact your locations of interest. See our guide on [radial searches](https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-latitude-longitude-and-radius) and the within search parameter.

A radial search returns events based on their location and geometry type. The following image shows the result of the example radial search performed in our [WebApp](https://control.predicthq.com/search/events/map?category=public-holidays,observances,politics,conferences,expos,concerts,festivals,performing-arts,sports,community,daylight-savings,airport-delays,severe-weather,disasters,terror,academic\&place.scope=6252001\&active.gte=2020-08-06\&active.lte=2020-09-05\&state=active\&within=4mi%4040.6441,-73.9393): A 4-mile radius around a point in Brooklyn, New York, USA - the search area is the blue circle.

| LOCATION AND GEOMETRY TYPE                       | RADIAL SEARCH MATCHING CRITERION                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Point event with Point geometry                  | The API returns the event if its point falls within the specified radius. In the following image, matching point events are the dots within the search area.                                                                                                                                                                                                                                                                   |
| Area event with Polygon or MultiPolygon geometry | The API returns the event if any part of its polygons intersects the specified radius. In the radial search map, matching events with polygons intersect the search area.                                                                                                                                                                                                                                                      |
| Area event with Point geometry                   | The API returns the event if the radial search location (the provided lat,lon coordinates regardless of radius) is a child place of the area event's place. In the radial search map, the dot outside the search area is an area event without a polygon. This event covers all of New York City, and since the radial search's location is in Brooklyn, a child place of New York City, the API also returns this area event. |

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Fxqc5atsGKmidRIg6JtsK%2Fradial-search-control-center.png?alt=media&amp;token=71e83707-1ae7-43ba-a418-d87e04acccdf" alt="A map of a 4-mile radial search around a point in Brooklyn, with the blue search circle, matching point events inside it, and an area event for New York City outside it"><figcaption></figcaption></figure>

When searching for events around a specific business location—a store, hotel, or other fixed site—the recommended approach is to use a [Saved Location](https://docs.predicthq.com/api/saved-locations/overview). When you create a Saved Location from a lat/lon origin, PredictHQ automatically calculates [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area) and stores it as the location boundary. You can then reference that location by `location_id` across the Events API, Features API, and Beam—without managing coordinates or boundaries manually.

If you need a simpler point-and-radius search without a Saved Location, you can use the `within` parameter directly as described earlier. In that case, see the [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area) with `area_type=radius` to get an appropriate radius for your location and industry.

You can also search for events occurring, in particular, Geonames Places using the `place.scope` parameter with Place ids. In our [Severe-Weather Events Data Engineering notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/severe-weather-events/part_1_data_engineering.ipynb), we provide code examples to find Place ids for your locations of interest.<br>


# Find events by latitude/longitude and radius

For this example, we will find conferences and expos that happened within a 2 mile radius of a specific location, in April 2018.

{% hint style="success" %}
It is difficult working out a suitable radius around your location so to make it easier use our [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area) to determine the optimal area around your business.
{% endhint %}

The Events endpoint supports the use of a `within` parameter to allow you to set specific latitude and longitude coordinates and search for events which occur within a radius from that point.

You can use this to find all the *conferences and expos*, `category=conferences,expos`, *within 2 miles* of my location, `within=2mi@-37.80036998,144.9715749`, that happened during *April of 2018*,`active.gte=2018-04-01&active.lte=2018-04-30`:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "within" : "2mi@-37.80036998,144.9715749",
        "active.gte" : "2018-04-01",
        "active.lte" : "2018-04-30",
        "category" : "conferences,expos",
        "sort" : "rank"
    }
)

print(response.json())
```

The following snippet shows part of the results:

```json
{
  "count": 734,
  "results": [
    {
      "id": "SwBTYbfiAHYDdbkUi7",
      "title": "Great Debate: Political Interest Society vs History Society",
      "category": "conferences",
      ...
    }
  ]
}
```


# Find events by place ID

For this example, we want to find all the sports events that happened in Nottingham, England in March of 2018.

To find the events, follow these steps:

1. To get the Nottingham Place ID, make a request to the Places endpoint.
2. To get the events, make a request to the Events endpoint with that Place ID.

The first request finds the Nottingham Place ID by calling the Places endpoint:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/places/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "q": "Nottingham,England"
    }
)

print(response.json())
```

The first result in the response is the correct location we want:

```json
{
    "id": "2641170",
    "type": "locality",
    "name": "Nottingham",
    "county": "Nottingham",
    "region": "England",
    "country": "United Kingdom",
    "country_alpha2": "GB",
    "country_alpha3": "GBR",
    "location": [
        -1.15047,
        52.9536
    ]
}
```

To search for Events happening in that location, use the Nottingham Place ID from the earlier response:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "place.scope" : "2641170",  # Nottingham Place ID
        "active.gte" : "2018-03-01",
        "active.lte" : "2018-03-31",
        "category" : "sports",
        "sort" : "rank"
    }
)

print(response.json())
```

A snippet of the results looks like this:

```json
{
  "count": 19,
  "results": [
    {
      "id": "KWjlX366rrrb",
      "title": "Championship - Nottingham Forest vs Derby County",
      "category": "sports",
      ...
    }
  ]
}
```

We use Geonames data for our Places, so the id *2641170* is also a Geoname ID for the same location. See the [official Geonames site](http://www.geonames.org/) for more information.

Using `place.scope` returns events that apply to the parent and children places of the specified place (e.g. holidays and other events that apply to a country or region). Alternatively you can use `place.exact` to return events that apply to the specified place only.


# Find events by IATA code

For this example, we will use an IATA airport code to search for events around Los Angeles Airport on March the 3rd, 2018.

The `/events` API endpoint supports the use of IATA (three character), ICAO (four character), and UN/LOCODE (five character) airport codes. A CSV file with all supported airport codes and their respective place ids is available to download.

{% file src="/files/ZkhSwDSTdvJ5bh93C7jx" %}

We can use the IATA code for *Los Angeles Airport (LAX)*, `place.scope=LAX`, to find all the *concerts* events, `category=concerts`, which are active on *3rd of March, 2018*, `active.gte=2018-03-03` and `active.lte=2018-03-03`:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "place.scope" : "LAX",
        "active.gte" : "2018-03-03",
        "active.lte" : "2018-03-03",
        "category" : "concerts",
        "sort" : "rank"
    }
)

print(response.json())
```

The following snippet shows the results:

```json
{
  "count": 73,
  "results": [
    {
      "id": "XS5tQbpjKtFeUShTPt",
      "title": "Demi Lovato with DJ Khaled and Kehlani",
      "category": "concerts",
      ...
    }
  ]
}
```


# Find events by country code

For this example, we will find public and school holidays for the United States of America in 2018.

The Events endpoint allows you to specify a particular country by using the `country` parameter. This parameter supports the standard two-character ISO 3166-1 country codes. See the full list of [ISO 3166-1 alpha-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

We use this parameter to find all *holidays*, `category=public-holidays,school-holidays`, which are happening in the *United States of America (US)*, `country=US`, in *2018*, `active.gte=2018-01-01&active.lte=2018-12-31`:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "country" : "US",
        "active.gte" : "2018-01-01",
        "active.lte" : "2018-12-31",
        "category" : "public-holidays,school-holidays"
    }
)

print(response.json())
```

One thing you might notice in the results are multiple events with the same title - this can happen when an event applies to multiple locations or occurs at different times. For example, a public holiday might apply to a number of states but not to the whole country - in this case there would be an event per state. A good indication of what area the event applies to is the `scope` field in the event information. If the event applies to the whole country this value is `country`, otherwise it may be `region`.

The following snippet shows the results:

```json
{
  "count": 468,
  "results": [
    {
      "id": "b6ca61ff6041c05d1e",
      "title": "New Year's Eve",
      "category": "public-holidays",
      ...
    }
  ]
}
```

That’s helpful, but doesn’t tell us which region the event applies to. Using the `place_hierarchies` field in event results we can get more detailed information about the place(s) the event applies to. Each hierarchy is an array of Place IDs, e.g. `["6295630","6255149","6252001","5165418"]` which is *Earth > North America > United States > Ohio*.

We can use the Places endpoint to find information about the Place IDs mentioned in the hierarchy or use the [Understanding place hierarchies](https://docs.predicthq.com/getting-started/guides/geolocation-guides/understanding-place-hierarchies) guide.


# Find events by Placekey

You can do the following with the Placekey filter:

* Match on an entire Placekey to see all events at that specific location. This can be useful when you want to search for events at a venue. E.g. `placekey=222-22t@5yv-j89-g6k`
* Match address without POI name – This is a query for only an address (the first three digits in the What part along with the Where part); not the POI name. E.g. `https://api.predicthq.com/v1/events?placekey=222@5yv-j89-g6k`
* Match on the full @Where part of Placekey to find events nearby. This returns events where the “@Where” part of Placekey matches but the What part may be different. This returns events within the H3 level 10 hex used by Placekey, which covers approximately a 63-meter radius around the location (see the [Placekey whitepaper](https://docs.placekey.io/Placekey_Technical_White_Paper.pdf) for more on H3 hexes). E.g. `https://api.predicthq.com/v1/events?placekey=@5yv-j89-g6k`
* Or perform a partial match on the @Where part of Placekey to find nearby events within a larger area. By a partial match we mean instead of including the entire nine characters of the @Where part of Placekey you can match on five or more characters to include a large area. See [joining POI and non-POI datasets](https://www.placekey.io/tutorials/joining-poi-and-non-poi-datasets-with-placekey). E.g. match the first seven characters: `https://api.predicthq.com/v1/events?placekey=@5yv-j89-g`

## Exact match

For this example, we find events happening at Las Vegas Convention Center in July 2023. This query gives you all events happening at this specific venue but not nearby events.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F6U2EGgJ8iCOC43gy6BjS%2Fplacekey-hex-las-vegas-convention-center.png?alt=media&amp;token=2b1e73a2-b1a6-4ac1-903d-80a6d4af47bf" alt="Map of the Las Vegas Convention Center with the H3 hexagon for its Placekey outlined"><figcaption><p>Placekey example for the Las Vegas Convention Center</p></figcaption></figure>

The following query uses the full Placekey of the venue:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "placekey" : "222-224@5yv-j8d-3qz",
        "active.gte" : "2023-07-01",
        "active.lte" : "2023-07-31",
        "sort" : "rank"
    }
)

print(response.json())
```

A snippet of the results follows:

```json
{
  "count": 15,
  "results": [
    {
      "id": "DzxBJGFXGwKZgRaSRx",
      "title": "Cosmoprof North America",
      "entities": [
        {
          "entity_id": "RKUCrNLMi3Rm7RaMDx3UC4",
          "name": "Las Vegas Convention Center",
          "type": "venue",
          "formatted_address": "3150 Paradise Road\nLas Vegas, NV 89109\nUnited States of America"
        },
        ...
      ],
      "geo": {
        "geometry": {
          "coordinates": [
            -115.15183100000002,
            36.1307069
          ],
          "type": "Point"
        },
        "placekey": "222-224@5yv-j8d-3qz"
      },
      ...
    },
    ...
  ]
}
```

## Partial match

Often, events nearby a location can have an impact on your demand. The distance from your location will depend on the type of business—for example, people may travel further to an event when staying in a hotel versus how far people may travel from an event to a restaurant—and the nature of the location also matters (e.g. urban or more rural). To find events nearby a location match on the `@Where` part of Placekey.

To find events very close to a location, match the full nine characters of the `@Where` part of the Placekey, which finds events very close to that location. Matching on the full `@Where` part of Placekey is like finding events within a 63-meter radius. In fact, it’s a hexagon with an edge length of 66 meters on average but it’s similar to drawing a circle with a 63-meter radius.

To find events that are further away match the first x characters of `@Where` from left to right. So, matching on the full nine characters is similar to a 63-meter radius, matching on the first eight characters of the `@Where` part gives a maximal distance of 443 meters, matching on the first seven characters encompasses a larger distance, and so on.

See the [Placekey documentation ](https://docs.placekey.io/Placekey_Technical_White_Paper.pdf)on “The structure of a Placekey”. The table with the “Length of shared prefix” and the “Maximal distance (meters)” gives you the approximate size of the H3 hex you get when you match the first X characters of the `@Where` part of Placekey. The minimum number of characters you can use when matching on the `@Where` part is five. See also [Joining POI and non-POI datasets with Placekey](https://www.placekey.io/tutorials/joining-poi-and-non-poi-datasets-with-placekey). The following image shows smaller hexes encompassed in larger hexes.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FN1Lhsk1cTOLbDpT0mc0W%2Fhex-levels-example.png?alt=media&amp;token=7cf136f2-44b5-426d-910f-310938be9081" alt="Map showing smaller H3 hexagons nested inside larger hexagons at lower resolutions"><figcaption></figcaption></figure>

Typically for looking at events around a location, we'd recommend looking at the first six to nine characters of Placekey, depending on how large of an area you want to look at.

For example, the following query looks at events around 40 W 23rd St, New York, NY 10010 using the first seven characters of the `@Where` part of Placekey:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "placekey" : "@627-s8h-v",
        "active.gte" : "2023-07-01",
        "active.lte" : "2023-07-31",
        "sort" : "rank"
    }
)

print(response.json())
```

A snippet of the results follows:

```json
{
  "count": 36,
  "results": [
    {
      "id": "88DqYDERmjC5F9iPCH",
      "title": "Anika",
      "entities": [
        {
          "entity_id": "35bsvV3dQeZuzAjZ4Eg4U52",
          "name": "Anika",
          "type": "person"
        },
        {
          "entity_id": "WcWW8e8hpnzXcKuTn9Zc9B",
          "name": "Gramercy Theatre",
          "type": "venue",
          "formatted_address": "127 East 23rd Street\nNew York, NY 10010\nUnited States of America"
        }
      ],
      "geo": {
        "geometry": {
          "coordinates": [
            -73.98502910000002,
            40.7397259
          ],
          "type": "Point"
        },
        "placekey": "zzw-22j@627-s8h-v2k"
      },
      ...
    },
    ...
  ]
}
```

One thing to be aware of is that nearby hexagons may have codes that are not very similar. This occurs when Placekey grid cells are near the edges of larger (i.e., lower resolution) hexagons in H3’s spatial hierarchy. This can mean that sometimes using the first x characters of a Placekey does not return all nearby events.

To account for all events around a radius, see “All neighboring hexes'' in the [Joining POI ](https://www.placekey.io/tutorials/joining-poi-and-non-poi-datasets-with-placekey)tutorial. Or you could convert Placekeys to a latitude and longitude and use a radius query to find nearby events with the [within parameter](https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-latitude-longitude-and-radius) on the Events API. To convert a Placekey to latitude and longitude, use `Placekey_to_geo` in the [Placekey Python library](https://github.com/Placekey/placekey-py).

## Find events near a location in Snowflake

PredictHQ’s Events data shared through [Snowflake Secure Data Sharing](https://docs.predicthq.com/integrations/third-party-integrations/snowflake) includes Placekey, as a separate column, reflecting the physical location where the event is held. There are a few approaches you could take to use this column when it comes to joining your dataset in Snowflake.

You can join PredictHQ’s event tables with your data on the entire Placekey column. This makes sense if your POI data consists of venues where events can be held. If you want to find events happening near the location of your POI locations, you need to join your data with PredictHQ’s Event tables on a [substring](https://docs.snowflake.com/en/sql-reference/functions/substr.html) of the @where part of the Placekey column.

The example below joins a sample PredictHQ Event table on Snowflake that includes Placekey information as a column with SafeGraph “Global Places Sample” POI data (see [SafeGraph data examples](https://www.safegraph.com/data-examples)). In this example, we are trying to perform an Inner Join between the restaurant in the SafeGraph table AND the PredictHQ Events happening nearby. We would only be using the first seven characters (excluding the hyphens) of the @Where part of the Placekey column for this Inner Join. This results in all possible matches between the restaurants and PredictHQ Events nearby them.

You can repurpose the following query with minimal change to use it in relational data warehouses other than Snowflake:

```sql
-- Selecting from PredictHQ’s New York Sample Attended Events data 
-- Creating two new columns inside a CTE that have the first 7 characters (excluding the hyphens) of the Placekey column's @Where part
with new_york_attended_events_with_place_key as (
    select
        *,
        SPLIT_PART(Placekey, '@', -1) as place_key_where,
        LEFT(SPLIT_PART(Placekey, '@', -1), 9) as phq_place_key_where_first_7_chars
    from
        marketplace.predicthq.new_york_attended_events
    where
        placekey is not null
),
 
-- Selecting all the store locations from SafeGraph Global Places Q3 2022
-- Creating two new columns inside a CTE that have the first 7 characters (excluding the hyphens) of the Placekey column's @Where part
safegraph_resturant_stores as (
    select
        *,
        SPLIT_PART(Placekey, '@', -1) as place_key_where,
        LEFT(SPLIT_PART(Placekey, '@', -1), 9) as safegraph_place_key_where_first_7_chars
    From marketplace.safegraph.safegraph_global_places_sample_q3_2022 
)
 
-- Inner joining between PredictHQ’s Events and Safegraph’s Restaurant Locations on the new columns containing the first 7 characters of the Placekey’s @Where part
select
    *
from
    safegraph_resturant_stores as safegraph
    inner join new_york_attended_events_with_place_key phq_events on phq_events.phq_place_key_where_first_7_chars = safegraph.safegraph_place_key_where_first_7_chars
order by
    phq_events.phq_place_key_where_first_7_chars;
```

{% hint style="info" %}
**Use Snowflake to get Placekeys for your address data**

See [How Infutor uses the Placekey external function in Snowflake](https://www.snowflake.com/blog/how-infutor-uses-the-placekey-external-function-to-extend-the-power-of-snowflake/) for details on how to use an External Function in Snowflake to get a Placekey for an address. If you have a data set in Snowflake where you have a lot of address data and you want a structured way to join it with events data and/or POI data you can use this functionality to set a Placekey for all your records. You can then use the information outlined in this article to match events and Placekey data.
{% endhint %}


# Working with location-based subscriptions

{% hint style="info" %}
**Note:** If you have location-based access and make requests to the [Events API](https://docs.predicthq.com/api/events/search-events) or [Features API](https://docs.predicthq.com/api/features/get-features), filter your API calls by a Saved Location ID.
{% endhint %}

You can purchase access to PredictHQ's events in different ways. You can purchase access to geographic areas like cities, states, or countries. Or you can purchase access to a number of locations to get access to specific business locations. Business locations include stores, hotels, restaurants, parking garages, offices, or any other type of location you can think of.

Under the hood, location-based access uses latitude, longitude, and radius to control what you can access. In the UI you can enter a street address for a business location and the product finds the latitude and longitude for that location and sets a [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area) and save the location with those details.

You can purchase location-based access if you have a number of business locations across a region, country, or multiple countries that you want access to but you don't need access to larger geographic areas like cities, states, or countries. For example, you may have a hotel chain with 300 hotels across the US in 20 different states spread between smaller towns and bigger cities. You can purchase location-based access for 300 hotels rather than buying access to full cities or entire states. The same could apply to a chain of restaurants, parking locations, retail stores, or any other business locations.

This guide provides details on how to use PredictHQ APIs when you have purchased location-based access instead of access to larger geographic areas.

The summary of how to use our APIs with location-based access is as follows:

* To create a Saved Location for each of your business locations, use the Saved Locations feature in our WebApp or our [Saved Locations API](https://docs.predicthq.com/api/saved-locations/overview)
* To access events you then use our [Events API](https://docs.predicthq.com/api/events/search-events) and call it using the `saved_location.location_id` filter to access events for your locations. Alternatively, you can also access events using the `/events` call in the [Saved Locations API](https://docs.predicthq.com/api/saved-locations/overview) (see Get a list of events for a location).
* If you add or delete locations ensure you update the location\_id values used to query the API.

This guide is focused on using the APIs. You can also use our WebApp to manage and access locations. See the documentation on the [WebApp](https://www.predicthq.com/support) for more details.

### How to see the number of locations I have access to?

Within the WebApp on the [plans page](https://control.predicthq.com/settings/plans/api) or in the **Location Insights** view you can see how many locations you have purchased and how many you have used.

If you add more locations than you have purchased, you keep access to the extra locations for a limited time. To keep them, upgrade your subscription to purchase more, or remove the locations you added. The PredictHQ team reaches out to discuss your options.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FfZN7JQCeIocLTaYeelZV%2Flocation-insights-number-purchased.png?alt=media&amp;token=06217033-9d9d-4845-a1b1-56ab4ba95e6c" alt="The Location Insights view showing the number of locations purchased and the number used"><figcaption></figcaption></figure>

## How to use the APIs with location-based access

### Setting up your locations

You will have a list of locations for your business. Such as a list of addresses for your stores. The first stage is to find the latitude and longitude (lat/long) of each store. Once you have done that you can create Saved Locations for each using the API.

For example, you could create a file that has a list of lat/longs and names for each store and run a script over the file to create Saved Locations for each.

See the [Saved Locations API documentation](https://docs.predicthq.com/api/saved-locations/overview). To upload a list of locations do the following:

1. Find the lat/long of each location
2. Call the Create Saved Locations endpoint (POST /saved-locations) using `origin_geojson` with the lat/lon for each location. The API calculates Predicted Impact Area automatically and stores it as the location boundary, so no separate API call is needed
3. Store the `location_id` returned for each location

This process only needs to be performed when you initially load in your locations or if locations change (such as a store closes or a new store opens).

### Fetching events for your locations

Once you have uploaded your locations you will have a list of `location_id`'s for each location. To get the latest events for each location you can call the Events API with the `saved_location.location_id` filter to get back events for the location.

Example fetching events using a Saved Location ID:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "saved_location.location_id": "sFlb8HlsLa1j-S4UDEMEkQ"
    }
)

print(response.json())
```

You can use other filters in the Events API to further filter down the response. Use paging to handle multiple pages of results.

Alternatively, you can also access events using the `/events` call in the Saved Locations API (see Get a list of events for a location). To get a list of events for a location make the following call with the location\_id `GET /saved-locations/<location_id>/insights/events`. E.g. `GET /saved-locations/0b6ZrOnTdB2Y7k4zC_9qBg/insights/events`.

See the following example:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/saved-locations/sFlb8HlsLa1j-S4UDEMEkQ/events",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "date_range_type": "next_90d",
        "category": "public-holidays,sports",
        "sort": "-start"
    }
)

print(response.json())
```

You can then use the events or store them in your data store. Ensure you keep events refresh as events are dynamic and can change such as be canceled, postponed, move locations, change dates, and so on. See [Keeping Data Updated](https://docs.predicthq.com/integrations/integration-guides/keep-data-updated-via-api).

For example, you may write code to loop over your list of locations and retrieve updated events for each and update your data store.

Note if you have location-based access you need to supply a value for this filter. If you do not supply a value, the API returns an error.


# Understanding place hierarchies

{% hint style="info" %}
Places associated with our events are [Geonames](https://www.geonames.org/) Features, which can be either an Area, an Administrative Feature, or a Populated Place. Use our [Places API](https://docs.predicthq.com/api/places/search-places) to explore Places data used in our events.
{% endhint %}

The `place_hierarchies` field contains Place ids for an event. The structure is an array of array of ids; ids are strings. For example:

```json
[
  ["6295630", "6255149", "6252001", "5815135", "5799783", "5786882"]  
]
```

The array of ids is ordered, representing a parent-to-child hierarchy of places. In the earlier example, the id 6295630 is the parent place of 6255149; and 6255149 is the parent place of 6252001, and so on. The last id in the list is the place in which the event occurs: 5786882 in the example.

Details for each Place, such as its name can be retrieved from the [Places API](https://docs.predicthq.com/api/places/search-places). For the earlier hierarchy, calling the Places API with `?id=6295630,6255149,6252001,5815135,5799783,5786882` returns:

```json
{
  "count": 6,
  "results": [ // some fields omitted
    {"id": "6295630", "type": "planet", "name": "Earth"},
    {"id": "6255149", "type": "continent", "name": "North America"},
    {"id": "6252001", "type": "country", "name": "United States"},
    {"id": "5815135", "type": "region", "name": "Washington"},
    {"id": "5799783", "type": "county", "name": "King County"},
    {"id": "5786882", "type": "locality", "name": "Bellevue"}
  ]
```

This reveals an event with the earlier `place_hierarchy` occurs in Bellevue, which belongs to King County, which is in Washington state, USA.

The `place_hierarchy` value when understood with the `scope` of an event reveals if an event is a point event or an area event. Point events have a `scope` value "locality"; Area events have "localadmin", "county", "region", or "country".

Point events happen at a point (its coordinate location) in the locality-level place it is scoped to. Example: This [MLB game at Oracle Park](https://events.predicthq.com/events/97iX53YAGnCwF9TGx3) is a point event with `scope`value "locality" and `place_hierarchy` value `[["6295630","6255149","6252001","5332921","5391997","5391959"]]`. 5391959 is the place id of San Francisco City.

Area events without polygons apply to the place it is scoped to, which is either a county-level, region-level, or country-level place. Example: This [Thanksgiving Day](https://events.predicthq.com/events/gEkxDPqErD5n) holiday is an area event with `scope` value "country" and `place_hierarchy` value `[["6295630","6255149","6252001"]]`. 6252001 is the place id of the United States.

Area events with polygons apply to the area the polygon's geometry defines. Places in the event's `place_hierarchies` are those which overlap with the polygon.

Place hierarchies value can be an empty array in some cases.

## Multiple hierarchies

Some events can have multiple hierarchies.

Point events can have up to two hierarchies. The second hierarchy, if it exists, is a nearby major city's hierarchy within a radius of 50km. This [Bite of Seattle community festival](https://events.predicthq.com/events/QDgCysY3kMnpoGYFi9), for example, is scoped to two places. Its `scope` and `place_hierarchies` values are shown later. 7153941 is the place id of Denny Regrade, the neighborhood where the festival takes place; 5809844 is the place id of Seattle, a nearby major city. `{ "scope": "locality", "place_hierarchies": [ ["6295630", "6255149", "6252001", "5815135", "5799783", "7153941"], ["6295630", "6255149", "6252001", "5815135", "5799783", "5809844"] ] }`

Area events have multiple hierarchies if the event applies to multiple counties or regions, or if its polygon overlaps with multiple counties or regions. For example: this [flood warning](https://events.predicthq.com/events/24gdWYbR9M7DzJBVdY) event's polygon overlaps with three counties in the state of Mississippi. Its `scope` and `place_hierarchies` values are shown later. 4421859, 4429877, 4450285 are the respective place ids for Claiborne County, Hinds County, and Warren County, as the following values show:

```json
{
  "scope": "county",
  "place_hierarchies": [
    [
      "6295630",
      "6255149",
      "6252001",
      "4436296",
      "4421859"
    ], [
      "6295630",
      "6255149",
      "6252001",
      "4436296",
      "4429877"
    ], [
      "6295630",
      "6255149",
      "6252001",
      "4436296",
      "4450285"
    ]
  ]
}
```

## Examples

### Fetch place information for place IDs

With a given list of Place IDs, fetch the Place info using the [Places endpoint](https://docs.predicthq.com/api/places/search-places), as in this code:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/places/",
    headers={
        "Authorization": "Bearer $API_TOKEN",
        "Accept": "application/json",
    },
    params={
        "id": "5391959,6252001,7153941,5809844,4421859,4429877,4450285",
    }
)

print(response.json())
```

The response looks like:

```json
{
  "count": 7,
  "results": [ // some fields omitted
    {
      "id": "5391959",
      "type": "locality",
      "name": "San Francisco",
      "country_alpha2": "US",
      "location": [-122.41942, 37.77493]
    },
    {
      "id": "6252001",
      "type": "country",
      "name": "United States",
      "country_alpha2": "US",
      "location": [-98.5, 39.76]
    },
    {
      "id": "7153941",
      "type": "locality",
      "name": "Denny Regrade",
      "country_alpha2": "US",
      "location": [-122.33667, 47.61611]
    },
    {
      "id": "5809844",
      "type": "locality",
      "name": "Seattle",
      "country_alpha2": "US",
      "location": [-122.33207, 47.60621]
    },
    {
      "id": "4421859",
      "type": "county",
      "name": "Claiborne County",
      "country_alpha2": "US",
      "location": [-90.91181, 31.97369]
    },
    {
      "id": "4429877",
      "type": "county",
      "name": "Hinds County",
      "country_alpha2": "US",
      "location": [-90.44282, 32.2667]
    },
    {
      "id": "4450285",
      "type": "county",
      "name": "Warren County",
      "country_alpha2": "US",
      "location": [-90.85201, 32.35723]
    }
  ]
}
```


# Working with polygons

Our Events API uses polygons data in the `geo.geometry` field when [searching](https://docs.predicthq.com/getting-started/guides/geolocation-guides/overview) to provide you with spatially relevant results. Once you have events with polygons, you can use them in your own systems. To do so, your systems will need to support GeoJSON and provide geospatial functionality.

Many datastores support GeoJSON and geospatial queries:

* [Snowflake](https://docs.snowflake.com/en/sql-reference/data-types-geospatial.html)
* [Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/dg/geospatial-overview.html)
* [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-shape.html)[Kibana](https://www.elastic.co/guide/en/kibana/current/maps.html)
* [Azure Cosmos DB](https://docs.microsoft.com/en-us/azure/cosmos-db/sql/sql-query-geospatial-intro)
* [MongoDB](https://docs.mongodb.com/manual/geospatial-queries/)

## Using polygons with offline event data

So far on this page, we have provided details on how to use our API to query for events with `geo` data (including polygons) that impact a given location. This section provides details on how you can download our events and do a geospatial operation on their polygons in the `geo` field. These operations could include filtering which polygons are impacting an area based on an offline sample of data or visualize them inside a Jupyter notebook. This section could be useful depending on what you're trying to do with the `geo` data, for instance, if you are a Data Scientists performing R\&D the following instructions might come in handy. You can always use our data exporter to bulk download events data to CSV or JSONL format.

There are many tools and libraries available to help you process and visualize our polygon events. We have some examples in our [Data Exploration notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/severe-weather-events/part_2_data_exploration.ipynb) which use [GeoPandas](https://geopandas.org/) and [Folium](https://python-visualization.github.io/folium/) libraries in Python to analyze and visualize polygons from our Severe-Weather Events.

You can use [Shapely](https://github.com/Toblerity/Shapely) to parse the event's geometry field and load it as a sheply object. In the following example, we would take a sample event with polygon and load it's geometry field into a shapely Polygon. We also go through this example in our severe-weather datascience docs, so check out [Appendix 2: Parsing geojson with Shapely](https://github.com/predicthq/phq-data-science-docs/blob/master/severe-weather-events/part_2_data_exploration.ipynb) if you prefer a more interactive example. Here is the sample event and the code that parses it:

```python
from shapely.geometry import shape


event = {"id": "268aCtdaPgDJNurMeP",
         "title": "Flood Warning",
         "geo": {
           "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [-94.15, 39.1599999],
                [-94.17, 39.220000000000006],
                [-93.86, 39.25000000000001],
                [-93.84, 39.18000000000001],
                [-94.05, 39.11000000000001],
                [-94.15, 39.1599999]
              ]
            ]
            }
          }
          # other fields omitted...
        }

# retrieving event's geojson field
event_geojson = event['geo']['geometry']

# parsing the geojson object using shape from shapely
parsed_polygon = shape(event_geojson)

# print the shapely polygon object
print(parsed_polygon)

>> POLYGON ((-94.15000000000001 39.1599999, -94.17 39.22000000000001, -93.86 39.25000000000001, -93.84 39.18000000000001, -94.05 39.11000000000001, -94.15000000000001 39.1599999))
```

Shapely has great built-in features, such as `intersects` which we would use to check if a given point (lat, lon) is inside the polygon:

```python
from shapely.geometry import Point

# Define point_1 adn point_2 in (lon, lat) format with shapely's Point
point_1 = Point(-94.096, 39.165)
point_2 = Point(-93.819, 39.131)

# Checked whether the point_1 intersects with event's polygon
parsed_polygon.intersects(point_1)
>> True

# Checked whether the point_2 intersects with event's polygon
parsed_polygon.intersects(point_2)
>> False
```

As the map of the event polygon shows, `point_1` is inside the polygon but `point_2` is not:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FmqRRxAQGdJow4Tp2CLEy%2Fshapely-polygon-intersects.png?alt=media&amp;token=eca0b4ba-85df-477d-8dfb-359f2a39758f" alt="A map of the event polygon with point_1 inside it and point_2 outside it"><figcaption></figcaption></figure>

{% hint style="info" %}
Coordinate reference systems

Both our API and Shapely use World Geodetic System 1984 (WGS84 also called [EPSG:4326](https://epsg.io/4326)) to represent coordinates in a Polygon or Point object by default. If you want to do more complicated GeoSpatial operations on these coordinates beyond what we have discussed here, you might need to project these objects from WGS84 to another Coordinate Reference Systems (CRS) that fits your purpose.
{% endhint %}


# Join events using Placekey

Placekey is a free, universal standard identifier for any physical place, which enables organizations to share the data pertaining to those places. PredictHQ provides Placekeys for events data to allow organizations to join our events data to other datasets that use Placekeys. See the [Placekey website](https://www.placekey.io/) for more information.

A common use of Placekey and events data is to provide additional information about the Point of Interest (POI) where the event took place. POI data provides detailed information about a location such as address, latitude/longitude, and open hours, and can also be enriched with data including spend data to reveal what’s happening at a location. The combination of events and POI data helps clarify exactly what is driving demand at a location. For example, combining events data with spend data to identify what is driving a spike in spend at a particular location.

PredictHQ attaches a Placekey to event records that happen at a particular location. The PredictHQ pipeline looks at the address and other location information like latitude and longitude and attaches the appropriate Placekey based on these values. An example of a Placekey is `222-22t@5yv-j89-g6k`. This is for the following address “The Mirage Theatre, 3400 Las Vegas Boulevard South, Las Vegas, NV 89109”. Events that happen at the Mirage Theatre have this Placekey value.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FK4KnBX3bgxsbIz77WZ8i%2Fplacekey-example.png?alt=media&amp;token=1e680d70-24ac-4044-891a-a04492bd8c7b" alt="Example Placekey 222-22t@5yv-j89-g6k for The Mirage Theatre in Las Vegas"><figcaption></figcaption></figure>

The format of the Placekey is `What@Where`. Take the Mirage Theatre example: `222-22t@5yv-j89-g6k`. For the What component, the first three characters refer to the Address Encoding and the second set of three characters refers to the POI Encoding. The Where part, on the other hand, is made up of three unique character sequences, built upon Uber’s open source H3 grid system. See the [Placekey site ](https://www.placekey.io/how-it-works)for an excellent description of what Placekey is and how it works.

The reason Placekey is useful for joining datasets is because of the general lack of standardization in POI and address data. Addresses are often formatted in different ways. Connecting data by address is difficult, and often inaccurate, and different companies may have different definitions of the latitude, longitude, and area of a location. Using Placekey provides a standard way of representing POI data and lets you join event data with other data sets that also use Placekey.

PredictHQ also [partners with SafeGraph](https://www.predicthq.com/partners/safegraph). Placekey allows you to join events data and SafeGraph data including [SafeGraph Places (POI)](https://www.safegraph.com/products/places), [SafeGraph Geometry](https://www.safegraph.com/products/geometry), and [SafeGraph Spend](https://www.safegraph.com/products/spend).

## Placekey on events

PredictHQ attaches Placekey to event records. The Events API returns it in its response. Other integrations like Snowflake and ADX also return Placekey.

The following is an example of the response from the Public API showing the Placekey for an event happening in Las Vegas:

```json
{
  "count": 1,
  "results": [
    {
      "id": "FKmCVGdpGMxwcFDF36",
      "title": "Shin Lim",
      "entities": [
        {
          "entity_id": "7jpp8Ha4F7LCz4CqaGDJmZ",
          "name": "The Mirage Theatre",
          "type": "venue",
          "formatted_address": "3400 Las Vegas Boulevard South\nLas Vegas, NV 89109\nUnited States of America"
        }
      ],
      "geo": {
        "geometry": {
          "coordinates": [
            -115.1741201,
            36.1214078
          ],
          "type": "Point"
        },
        "placekey": "222-22t@5yv-j89-g6k"
      },
      ...
    }
  ]
}
```

## Placekey support

Placekey has address support for the United States, United Kingdom, and Canada (see [supported countries](https://docs.placekey.io/#b0aa86a5-ec33-45a8-aebf-67c25c5ca0a5)). For these countries, PredictHQ events have both the What\@Where part where the events have sufficient address information. Some events that don’t have address information may just have the @Where part of Placekey.

PredictHQ provides Placekey on attended events from 2020 onwards.

For all other countries where Placekey does not support addresses, these events have the `@Where` part of Placekey. For example, the [Stade Toulousain vs Perpignan](https://events.predicthq.com/events/FYwLVpWzz7k6SRmiZy) event in Toulouse, France has a Placekey of `@7f7-mcy-ndv`. This is very useful and can also be used to find nearby events and to join with POI data.

The following image shows the hexagon area covered by `@7f7-mcy-ndv`:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FyI2WxPPMDG0AGMq57L8P%2Fplacekey-hex-france-example.png?alt=media&amp;token=5b65da2c-1a04-4a5d-8759-9198a0d44d9e" alt="Map of the hexagon area around Toulouse, France, covered by the Placekey @7f7-mcy-ndv"><figcaption></figcaption></figure>

{% hint style="info" %}
Note that attended events that have a polygon representing an area do not use Placekey. For example marathons, parades, and festivals have a geojson polygon representing the area impacted by the event. Placekeys are best suited for events that occur at a specific location rather than events that cover a broad area. See our guide to [using polygons events data](https://docs.predicthq.com/getting-started/guides/geolocation-guides/working-with-polygons) to find polygons events around a location.
{% endhint %}


# Date and time guides

Event time is messier than it looks: events recur, span multiple days, nest under umbrella events, and happen in local timezones. These guides cover the mechanics:

* [Working with recurring events](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-recurring-events)
* [Working with multi-day and umbrella events](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-multi-day-and-umbrella-events)
* [Working with dates, times and timezones](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-dates-times-and-timezones)

If you're building model features, note the Features API handles multi-day attendance distribution and Predicted Impact Patterns for you - these guides matter most when working with individual event records from the Events API.


# Working with recurring events

The Recurring Events feature provides a linkage between recurrences of the same event:

* Events that recur each year on the same day, such as Christmas Day.
* Events that recur each year (or month, or other frequency) but change date and potentially location, such as the American Society of Hematology Annual Meeting.

As well as being able to see that an event is recurring, it’s also possible to find all recurrences of the same event.

{% hint style="info" %}
**Example use cases**

Recurring Events supports use cases such as:

* **Demand Forecasting**: When analyzing previous years transactions or bookings, you can align demand spikes with a recurring event and predict expected demand increases for future years.
* **Labor Optimization**: Knowing why you were busy last year and planning your resource requirements for the same period next year. What if the event changes location? Recurring Events allows you to get this visibility and plan accordingly.
  {% endhint %}

The API represents Recurring Events as an Entity of type `event-group` with recurring info in iCalendar recurring RRULE format.

The following is an example event with a recurring `event-group` Entity:

```json
{
  "count": 1,
  "results": [
    {
      "id": "3HieM5mavYqPikiHPw",
      "title": "ASH Annual Meeting",
      "category": "conferences",
      "entities": [
        {
          "entity_id": "vAtN2UDcxySFtZFwLRvqcN",
          "name": "ASH Annual Meeting",
          "type": "event-group",
          "category": "conferences",
          "labels": [
            "business",
            "conference",
            "event-group",
            "expo",
            "recurring"
          ],
          "description": "The American Society of Hematology (ASH) Annual Meeting & Exposition provides an invaluable educational experience and the opportunity to review thousands of scientific abstracts highlighting updates in the hottest topics in hematology.",
          "recurring": {
            "ical": "DTSTART;VALUE=DATE:20141206\nDURATION:P4D\nRRULE:FREQ=YEARLY;INTERVAL=1"
          }
        }
      ],
      ...
    }
  ]
}
```

## Find all instances of a recurring event

The `entity.id` query parameter allows you to find all Events that are linked to the specified Entity ID. This example uses the "ASH Annual Meeting" recurring `event-group` Entity ID to find all instances of the Event:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "entity.id" : "vAtN2UDcxySFtZFwLRvqcN",
        "sort" : "start"
    }
)

print(response.json())
```

A snippet of the results follows:

```json
{
  "count": 9,
  "results": [
    {
      "id": "6NYlQ7BdJdLy",
      "title": "ASH Annual Meeting",
      "start": "2014-12-06T08:00:00Z",
      "end": "2014-12-10T07:59:59Z",
      ...
    },
    {
      "id": "DGMn5WdRKg6R",
      "title": "ASH Annual Meeting",
      "start": "2015-12-05T05:00:00Z",
      "end": "2015-12-09T04:59:59Z",
      ...
    },
    {
      "id": "l3DQOqMooNQJ",
      "title": "ASH Annual Meeting",
      "start": "2016-12-03T08:00:00Z",
      "end": "2016-12-07T07:59:59Z",
      ...
    },
    {
      "id": "CMAXh5scsAcFyMhgGj",
      "title": "ASH Annual Meeting",
      "start": "2017-12-09T05:00:00Z",
      "end": "2017-12-13T04:59:59Z",
      ...
    },
    {
      "id": "K9z9hS3sXqjH3SmYwq",
      "title": "ASH Annual Meeting",
      "start": "2018-12-01T08:00:00Z",
      "end": "2018-12-05T07:59:59Z",
      ...
    },
    {
      "id": "2RxTdCucMNcLZSsEqW",
      "title": "ASH Annual Meeting",
      "start": "2019-12-07T05:00:00Z",
      "end": "2019-12-11T04:59:59Z",
      ...
    },
    {
      "id": "XDs5aBowsAAopqp5yy",
      "title": "ASH Annual Meeting",
      "start": "2021-12-11T05:00:00Z",
      "end": "2021-12-15T04:59:59Z",
      ...
    },
    {
      "id": "3HieM5mavYqPikiHPw",
      "title": "ASH Annual Meeting",
      "start": "2022-12-10T06:00:00Z",
      "end": "2022-12-14T05:59:59Z",
      ...
    },
    {
      "id": "FFRgbLAfquTFajD3Xq",
      "title": "ASH Annual Meeting and Exposition",
      "start": "2023-12-09T19:00:00Z",
      "end": "2023-12-12T22:00:00Z",
      ...
    }
  ]
}
```

## Find a specific recurrence of an Event

In this example, we find the 2019 instance of the "ASH Annual Meeting":

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "entity.id" : "vAtN2UDcxySFtZFwLRvqcN",
        "start.gte" : "2019-01-01",
        "start.lte": "2019-12-31"
    }
)

print(response.json())
```

A snippet of the results follows:

```json
{
  "count": 1,
  "results": [
    {
      "id": "2RxTdCucMNcLZSsEqW",
      "title": "ASH Annual Meeting",
      "description": "The American Society of Hematology (ASH) Annual Meeting & Exposition provides an invaluable educational experience and the opportunity to review thousands of scientific abstracts highlighting updates in the hottest topics in hematology.",
      "category": "conferences",
      "labels": [
        "conference",
        "expo",
        "health",
        "medical"
      ],
      "rank": 78,
      "local_rank": 100,
      "phq_attendance": 25000,
      "entities": [
        {
          "entity_id": "Urecg72DAWZw5abb9ZExWh",
          "name": "Orange County Convention Center",
          "type": "venue",
          "formatted_address": "9800 International Drive\nOrlando, FL 32819\nUnited States of America"
        },
        {
          "entity_id": "vAtN2UDcxySFtZFwLRvqcN",
          "name": "ASH Annual Meeting",
          "type": "event-group",
          "category": "conferences",
          "labels": [
            "business",
            "conference",
            "event-group",
            "expo",
            "recurring"
          ],
          "description": "The American Society of Hematology (ASH) Annual Meeting & Exposition provides an invaluable educational experience and the opportunity to review thousands of scientific abstracts highlighting updates in the hottest topics in hematology.",
          "recurring": {
            "ical": "DTSTART;VALUE=DATE:20141206\nDURATION:P4D\nRRULE:FREQ=YEARLY;INTERVAL=1"
          }
        }
      ],
      "duration": 345599,
      "start": "2019-12-07T05:00:00Z",
      "end": "2019-12-11T04:59:59Z",
      "updated": "2023-07-07T02:57:03Z",
      "first_seen": "2019-02-21T00:24:36Z",
      "timezone": "America/New_York",
      "location": [
        -81.4697992,
        28.4245227
      ],
      "geo": {
        "geometry": {
          "coordinates": [
            -81.4697992,
            28.4245227
          ],
          "type": "Point"
        },
        "placekey": "zzw-224@8fy-8hr-pgk"
      },
      "scope": "locality",
      "country": "US",
      "place_hierarchies": [
        [
          "6295630",
          "6255149",
          "6252001",
          "4155751",
          "4167060",
          "4178397"
        ],
        [
          "6295630",
          "6255149",
          "6252001",
          "4155751",
          "4167218",
          "4160983"
        ]
      ],
      "state": "active",
      "private": false,
      "predicted_event_spend": 19879000,
      "predicted_event_spend_industries": {
        "accommodation": 14760000,
        "hospitality": 4179000,
        "transportation": 940000
      }
    }
  ]
}
```


# Working with multi-day and umbrella events

How to interpret phq\_attendance for multi-day events and avoid double-counting umbrella events when working with individual event records.

PredictHQ’s events data includes events of different duration, from events that may be less than an hour-long to events that can last more than a week. For our [seven attended event categories](https://www.predicthq.com/intelligence/data-enrichment/event-categories), we expose the actual or Predicted Attendance for events in our phq\_attendance field. The phq\_attendance field works slightly differently for different categories. For many categories, it is the total attendance for an event over its full duration. For other categories (like conferences), it reflects the daily attendance.

For example, the phq\_attendance for a big event like the [2019 Tour de France](https://events.predicthq.com/events/fXHXPzTVW5K9ZWxFnb) is 12,000,000 which represents the total attendance for the full duration of 22 days. It is not the daily attendance. The daily attendance for that event is closer to 545,000 people. Reading 12,000,000 as a single day's attendance would badly misrepresent the event's impact.

PredictHQ also handles cases where one event (child) belongs to another (parent). This type of event is called an Umbrella event. Umbrella events are often multi-day events but can also be single-day events with multiple sessions if the same attendees are expected, for example the games of a rugby sevens tournament. When looking at events it’s important to use either parent events or child events, but not both.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Ft1QQmEQqfNP4Q5FYD0ec%2Fumbrella-events.png?alt=media&amp;token=8c5ea473-2c0f-4374-bc38-8f32390a1fdf" alt="Diagram of an umbrella event, with a parent event spanning the full duration and child events nested within it"><figcaption></figcaption></figure>

This page covers how to interpret these events correctly when working with individual event records - event lists, explainability surfaces, and grounding corpora. For daily or weekly aggregations of any kind - model features, dashboards, analytics - use the [Features API](https://docs.predicthq.com/api/features/get-features), which handles all of the complications on this page for you.

## Multi-day events

### Handling attendance for multi-day events

The [Features API](https://docs.predicthq.com/api/features/get-features) has advanced logic for handling multi-day events. For some categories, phq\_attendance is the daily attendance. For categories that have multi-day events, such as festivals, community events, expos, and sports, the Features API applies additional logic to distribute phq\_attendance to each day.

The following is an example of how phq\_attendance might be distributed for a golf tournament. This is a multi-day sports event so the phq\_attendance of 63,000 is the total attendance across the full duration. The daily attendance is not evenly distributed across the week as higher attendance is expected on the weekend. The Features API deals with distributing attendance across each day and takes into account uneven distributions.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F6wqpuZ4AENCcUrfwylri%2Fchart-sports.png?alt=media&amp;token=2ca99e56-df6a-4c04-92c5-bb86af61eeec" alt="Bar chart of daily attendance for a golf tournament, with higher attendance on the weekend days than on the weekdays" width="375"><figcaption></figcaption></figure>

For supported industries, the Features API goes further: [Predicted Impact Patterns](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns) are daily impact curves derived from machine learning models trained on historical demand data, specific to event category and industry, extending into the lead-up and lag days around an event. This distribution logic is not reproducible with rules of thumb - which is why daily and weekly aggregations belong in the Features API rather than in your own pipeline.

### Interpreting phq\_attendance across categories

Our definition of multi-day events is: events that take place across more than one day, i.e. overlap on more than one calendar day, while single-day events take place within one day, i.e. start and end on the same calendar day.

When reading individual event records, interpret phq\_attendance as follows:

<table><thead><tr><th width="184">Category</th><th>What phq_attendance represents</th></tr></thead><tbody><tr><td>Concerts</td><td>Daily attendance. These events tend to be 1 day or less.</td></tr><tr><td>Performing Arts</td><td>Daily attendance. These events tend to be 1 day or less.</td></tr><tr><td>Conferences</td><td>Daily attendance, not total attendance.</td></tr><tr><td>Expos</td><td>Total attendance across the full event duration.</td></tr><tr><td>Sports</td><td>Total attendance across the full event duration.</td></tr><tr><td>Festivals</td><td>Total attendance across the full event duration.</td></tr><tr><td>Community</td><td>Total attendance across the full event duration.</td></tr></tbody></table>

## Umbrella events

Umbrella events refer to the case where we have a parent event that contains one or more child events. For example, the [United States Formula 1 Grand Prix in 2019](https://events.predicthq.com/events/w7dYyrFwTUQGYE6euv) has child events for [the qualification](https://events.predicthq.com/events/hZ5fGHaxHKgJTBpqyQ), three practice events, [a concert](https://events.predicthq.com/events/N4LWVHvicH5YiCHQKe) that occurs at the Grand Prix, and the [actual race event](https://events.predicthq.com/events/5uRg7CqGu7DTtu4Rfk) (there are 12 child events in total). The parent event is for the entire Grand Prix that runs from the 1st of November to the 3rd of November 2019. Both the parent and child events are part of the wider Umbrella event.

The `parent_event` field indicates child events. Child events have a parent\_event\_id in this field indicating the id of the parent event. For example, the Formula 1 race child event is `5uRg7CqGu7DTtu4Rfk` and the Formula 1 parent event is `w7dYyrFwTUQGYE6euv`. The Formula 1 race child event has the following parent event info:

```json
{
  "id": "5uRg7CqGu7DTtu4Rfk",
  "parent_event": {
    "parent_event_id": "w7dYyrFwTUQGYE6euv"
  },
  "title": "Formula 1 2019 - United States Grand Prix 2019 - Race",
  "category": "sports",
  ...
}
```

{% hint style="info" %}
You cannot find the child event IDs of a parent event via the API.
{% endhint %}

### **Why umbrella events matter**

Any view built from individual event records has to account for Umbrella events, or the attendance of parent events and their child events is double-counted, producing inflated figures. For daily or weekly aggregations of any kind, use the [Features API](https://docs.predicthq.com/api/features/get-features) rather than aggregating records - see [Which API should I use?](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use)

Looking at the earlier [US F1 Grand Prix in 2019](https://events.predicthq.com/events/w7dYyrFwTUQGYE6euv) example, the parent event spanning 3 days has a phq\_attendance of 258,000. The actual race event running for around 3 hours on the 3rd of November has a phq\_attendance of 120,000. If you count both the parent event and the race child event on the 3rd, you overcount the attendance - the same people are represented in both records.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FhTAzxcaUaqqRHL0HI6S6%2Fexample-of-umbrella.svg?alt=media&amp;token=1a7dfbcc-af08-4a41-974b-a5eb5f4047a1" alt="Diagram of the US Formula 1 Grand Prix umbrella event, showing the 3-day parent event and the race child event on the 3rd of November, whose attendance is counted in both records"><figcaption></figcaption></figure>

{% hint style="info" %}
Child event attendance may sometimes reflect more detailed attendance on the individual days of an event, rather than an even share of the parent event's total.
{% endhint %}

Another example can be seen when looking at the daily attendance for events in Las Vegas in 2019. In the following example, there is the [World Rugby Sevens tournament](https://events.predicthq.com/events/iKKgf8suq5D5w89boJ) from the 1st of March 2019 to the 3rd of March 2019. The parent event is for the entire tournament and there are many child events for individual games and rounds in the tournament. By not accounting for Umbrella events you get a massive spike in attendance at that time. A peak of 1.4 million is seen around the 2nd of March because both the parent event and child events are being counted.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F9bK8OrDtp9UAnksF2xMi%2Fgraph-umbrella-events-double-counted.png?alt=media&amp;token=19f0797e-2d17-40a2-9a5a-de0c38c9926b" alt="Chart of daily attendance for events in Las Vegas in March 2019, with a spike of 1.4 million around the 2nd of March because the parent event and child events are both counted"><figcaption><p>Example showing attendance being counted multiple times due to not handling Umbrella Events</p></figcaption></figure>

Once you take into account Umbrella events and remove double counting, the real attendance on that day is closer to 400,000.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Fqbq5FOtGLJoe2W5OdRSP%2Fgraph-umbrella-events-removed.png?alt=media&amp;token=f7a022c0-b4bd-43d4-b82a-9fe62afafbd3" alt="Chart of daily attendance for events in Las Vegas in March 2019 after removing double counting, with attendance of about 400,000 around the 2nd of March"><figcaption><p>Example showing correct attendance due to correct handling of Umbrella Events</p></figcaption></figure>

### **Using the parent filter in the Events API for umbrella events**

See the documentation on the [parent filter](https://docs.predicthq.com/api/events/search-events) for umbrella events.

You can use this filter with the Events API to only get parent events or only retrieve child events from the Events API.

Note that in the API **parent** events includes events that have child events and also events without any child events. So, for the API filter parent events also include non-umbrella events. **Child** events are only those events that have a link to a parent event.

### **Definitions**

This page uses two terms:

* **Parent event** - Spans the full duration of an event and may have child events as part of it. Many parent events will be multi-day events such as the Olympics, a Formula 1 weekend, or a multi-day festival. These events have a parent event for the whole event - like an event for the entire 2020 Olympic Games in Tokyo. Other examples include an event for the entire US Formula 1 or a rugby sevens tournament.
* **Child events** - Individual events that are part of a parent event. For example, day 1 of the 2020 Olympic Games or the “Men’s 100m finals” in the Olympic Games. Or the Formula 1 qualification and practice events. All of these are examples of child events.


# Working with dates, times and timezones

Working with dates, times, and timezones can be hard.This guide aims to clarify how to work with these with PredictHQ data.

## Event start and end local time

The Events API provides event start and end times in UTC and in the event local time format. The date and time fields available are:

* The fields that provide local time are `start_local`, `end_local`, and `predicted_end_local`. These fields have the local time end date of the event in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. This is the local time in the time zone at the event location. See the [Events API Response Fields](https://docs.predicthq.com/api/events/search-events) for more details on these fields.
* The fields `start`, `end`, and `predicted_end` have date values in UTC format.

{% hint style="info" %}
Note that the date fields in the Events API Query Parameters are in UTC. You can use the `tz` suffix to specify a time zone when querying using the date filters.
{% endhint %}

<details>

<summary>Previous guide on converting to local time</summary>

The Events API provides dates and times of events in UTC and in the local time where the event is occurring. If you want to convert the dates into another time zone use the Python example in this section.

The following is an example of converting UTC time to local time using the `pytz` library in Python:

```python
from datetime import datetime
import pytz

# Example dates for an event retrieved from Events API.
# The rest of the event data has been stripped out for brevity.
event = {
  "start": "2023-10-23T13:00:00Z",
  "end": "2023-10-24T12:59:59Z",
  "timezone": "Australia/Sydney",
}

# Function to convert a UTC datetime string to a local datetime string using the given timezone
def convert_to_local(date_str, timezone_str):
    utc_dt = datetime.fromisoformat(date_str.replace("Z", "+00:00"))
    target_tz = pytz.timezone(timezone_str)
    local_dt = utc_dt.astimezone(target_tz)
    return local_dt.isoformat()

event["start_tz_converted"] = convert_to_local(event["start"], event["timezone"])
event["end_tz_converted"] = convert_to_local(event["end"], event["timezone"])

print(event)
```

Dates are a little more complex and the rest of this guide helps you understand how we represent dates in our data.

</details>

## Date concepts

Internally, we have the concept of different date types for events. We don't expose these date types directly, but they surface indirectly and this guide demonstrates how to understand dates, times, and timezones on events. The different date types we refer to internally are:

* Fixed Date
* Fixed Time
* Floating Date

### Fixed Date

This concept refers to events that are known to happen on a certain date (including multi-day events) but the start and end times are not known. We represent these events in UTC, and they have a local start time of 00:00:00 and local end time of 23:59:59 as well as a known timezone, as in the following example:

```json
{
  "start": "2023-10-23T13:00:00Z",
  "end": "2023-10-24T12:59:59Z",
  "timezone": "Australia/Sydney",
  ...
}
```

The event in the earlier example is happening on Tue, 24 Oct 2023 (a single day) and using the `convert_to_local` function from the earlier Python code produces:

```json
{
  "start": "2023-10-23T13:00:00Z",
  "end": "2023-10-24T12:59:59Z",
  
  "start_local": "2023-10-24T00:00:00+11:00",
  "end_local": "2023-10-24T23:59:59+11:00",
  
  "timezone": "Australia/Sydney"
}
```

The `start_local` and `end_local` fields show the event spans the entire day of October 24th, 2023 in the Australia/Sydney timezone.

### Fixed Time

Refers to events covering an exact time range. The start and end times are known (or predicted). We represent these events in UTC, and they have a timezone, as in this example:

```json
{
  "start": "2023-11-09T08:00:00Z",
  "end": "2023-11-09T09:30:00Z",
  "timezone": "Australia/Melbourne",
  ...
}
```

Using the same `convert_to_local` function from earlier we get:

```json
{
  "start": "2023-11-09T08:00:00Z",
  "end": "2023-11-09T09:30:00Z",
  
  "start_local": "2023-11-09T19:00:00+11:00",
  "end_local": "2023-11-09T20:30:00+11:00",
  
  "timezone": "Australia/Melbourne",
}
```

Showing the event is scheduled from 7:00 PM to 8:30 PM on November 9th, 2023 in the Australia/Melbourne timezone.

### Floating Date

Refers to events that happen on a particular date regardless of timezone. E.g., USA Independence Day is 4th of July regardless of timezone. The way we represent this concept is by setting the `timezone` to `null` as in the following example:

```json
{
  "start": "2024-07-04T00:00:00Z",
  "end": "2024-07-04T23:59:59Z",
  "timezone": null,
  ...
}
```

When the `timezone` field is `null` like this you don't need to convert the start/end times.

## Predicted End Times

Many events don't have scheduled end times, for many of these events we provide a `predicted_end_time` field (in UTC) and a `predicted_end_local` (in the time zone of the location of the event). When the `start` and `end` values are exactly the same, we know the start time but not the scheduled end time, so we provide a `predicted_end` value, as in this example:

```json
{
  "start": "2024-09-29T19:05:00Z",
  "end": "2024-09-29T19:05:00Z",
  "predicted_end": "2024-09-29T21:50:00Z",
  "timezone": "America/New_York",
  ...
}
```


# Events API guides

Guides and notebooks for working with event records. [Filtering and finding relevant events](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events) is the worked walkthrough of Events API query mechanics, and the visualization guides cover [heatmap calendars](https://docs.predicthq.com/getting-started/guides/events-api-guides/displaying-events-in-a-heatmap-calendar) and [maps](https://docs.predicthq.com/getting-started/guides/events-api-guides/displaying-events-on-a-map). The per-category notebook series (attendance-based, non-attendance-based, severe weather, academic, live TV, and venues) live in [Data science notebooks](https://docs.predicthq.com/getting-started/data-science-notebooks#exploring-event-categories).

The Events API is for discovery, explainability, and building a grounding corpus - individual verified records your systems and users can inspect. It is not the way to build model features: aggregating events by hand introduces noise, and the [Features API](https://docs.predicthq.com/getting-started/guides/features-api-guides) exists so you don't have to. See [Which API should I use?](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use) if in doubt.


# Filtering and finding relevant events

Learn how to filter and find events relevant to your business using PredictHQ's Events API.

Events such as concerts, expos, and public holidays can shift consumer behavior and [impact demand](https://www.predicthq.com/use-cases/demand-forecasting). Understanding which events are most relevant to a store or location is therefore critical for effective planning and management. By staying ahead of these events, businesses can better prepare for changes in consumer traffic and purchasing patterns, ensuring optimal staffing and inventory levels.

This tutorial will walk through the [Events API](https://www.predicthq.com/apis/event-api) while exploring an example involving a pizzeria interested in identifying major upcoming events. The goal is to learn how to effectively define query parameters, make API calls, and interpret responses.

To monitor upcoming events around your stores or locations without writing queries, use [Saved Locations](https://www.predicthq.com/tools/webapp/saved-locations). In [WebApp](https://control.predicthq.com/location-insights), set up a location to get immediate insights for all created locations. You can also do this securely and at scale from your own environment with the [Saved Locations API](https://docs.predicthq.com/api/saved-locations/overview).

## Getting started

A valid access token is required for calling PredictHQ’s APIs. Refer to the [API quickstart](https://docs.predicthq.com/getting-started/api-quickstart) for guidance on creating an access token and test our APIs with our [API Explorer](https://control.predicthq.com/explorer/events).

## Scenario

Let's take a fictional example: Tom, the owner of Tom’s Pizzeria in Downtown Seattle, Washington, has experienced overwhelming demand on several occasions, resulting in long lines and significant service delays. Suspecting nearby events were the cause of these surges, he sought to better prepare by identifying upcoming major events. To achieve this, Tom is looking into PredictHQ’s Events API to see how he can obtain this information for the next month.

## How-to guide

The following sections guide you through identifying the top 50 upcoming events near Tom’s Pizzeria over the next month. Follow the steps and code snippets to understand how this can be adapted to fit other business scenarios.

### Step 1. Define query parameters for the Events API

Given the volume of events happening all the time, choosing the right query parameters is crucial for identifying relevant events. The next section outlines the most commonly used parameters from the [Events API](https://docs.predicthq.com/api/events/search-events), providing guidance on how to use them along with Tom’s choices:

<details>

<summary>Date range</summary>

To set the date range for the search, use one of these parameters:

* **Active**: To include all events that are ongoing in the date range, use the `active` parameter.
* **Start**: To focus on the start dates of events, set the date range with the `start` parameter.

**Settings for Tom’s Pizzeria**

Tom is interested in events taking place in the month of June 2024. He will configure the search to include active events from June 1st to June 30th, considering the local time zone:

```python
params={
   "active.gte": "2024-06-01",
   "active.lte": "2024-06-30",
   "active.tz": "America/Los_Angeles"
   }
```

</details>

<details>

<summary>Location type</summary>

Define the catchment area for the search. Refer to our [industry recommendations](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters#location-type) for which location type to start with:

* **Saved Location (Recommended)**: Create a [Saved Location](https://docs.predicthq.com/api/saved-locations/overview) for each of your business locations. When you create one from a lat/lon origin, PredictHQ automatically calculates the [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area) and stores it as the location boundary. You can then use `saved_location.location_id` in Events API, Features API, and Beam queries, with no manual boundary management needed.
* **Center Point & Radius**: For a search without a Saved Location, use the `within` parameter with lat/lon and a radius. To get an appropriate radius for your location and industry rather than guessing, use the [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area) with `area_type=radius`.
* **City, State, Country**: For targeted searches across a predefined area e.g. specific cities, states, or countries, use the `place` parameter and provide a place ID. The [Places API](https://docs.predicthq.com/api/places/search-places) can assist in finding correct place IDs.
* **Country-wide**: If your interest spans an entire country, use the `country` parameter and set it to the relevant ISO country code.

**Settings for Tom’s Pizzeria**

Tom creates a Saved Location for his pizzeria at (47.60, -122.33) in the `restaurants` industry. PredictHQ calculates Predicted Impact Area automatically when Tom creates the location, defining the polygon boundary where event-driven demand impact actually occurs for his location. Tom then queries events using `saved_location.location_id`, with no separate area lookup needed:

```python
params={
  "saved_location.location_id": "<location_id>",
  "category": "concerts,sports,festivals,community,performing-arts",
  "state": "active,predicted"
}
```

</details>

<details>

<summary>Event type</summary>

Select the types of events for the search:

* **Relevant Event Categories**: To identify [event categories](https://docs.predicthq.com/getting-started/predicthq-data/event-categories) that are most relevant to your location, use [Beam](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam) in the [WebApp](https://control.predicthq.com/beam) or the [Beam API](https://docs.predicthq.com/api/beam/overview). Alternatively, start with our [industry recommendations](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters#relevant-event-categories) for which categories to start with.
* **Specific Themes**: To focus on particular themes within a category, use the `phq_label` parameter. For example, to find baseball-related events, set `phq_label` to `baseball`.

**Settings for Tom’s Pizzeria**

For a broad initial survey of upcoming events, Tom has chosen to focus on categories that are likely to influence restaurant visits:

```python
params={
  "category": "public-holidays,performing-arts,conferences,concerts,festivals"
  } 
```

Next, Tom plans to use Beam in the [WebApp](https://control.predicthq.com/beam) to help refine these categories further based on actual data-driven insights, tailored to his pizzeria.

</details>

<details>

<summary>Event impact</summary>

Define the event impact for the search:

* **PHQ Rank**: To target events based on their [predicted impact](https://docs.predicthq.com/getting-started/predicthq-data/ranks/phq-rank), use the `rank` parameter, with values ranging from 0 to 100. This is useful for filtering out smaller events, ensuring focus on those likely to impact demand. To set the minimum rank threshold, set `rank.gte` based on our [recommended industry minimums](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters#minimum-phq-rank).
  * The `rank_level` parameter divides the PHQ Rank into five equal bands, for simplified categorization. Levels range from 1 to 5, where 1 represents minor impact, such as a community workshop, and 5 represents major impact, like the Olympics.
* **Local Rank**: To consider the event's impact on the local area, use `local_rank`, which also ranges from 0 to 100. By considering factors like population density, [Local Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/local-rank) helps differentiate the impact of similar-sized events in different locations, such as Aspen, Colorado versus New York City.
  * The `local_rank_level` parameter divides Local Rank into five equal bands, for simplified categorization. Levels also range from 1 to 5, with 1 representing minor impact and 5 representing major impact, similar to the PHQ Rank.
* **Predicted Attendance**: For [attendance-based events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events), impact can be directly measured with `phq_attendance` which is the [number of people predicted to attend an event](https://docs.predicthq.com/getting-started/predicthq-data/predicted-attendance).

**Settings for Tom’s Pizzeria**

To focus his resources efficiently and avoid spending time on smaller, less impactful events, Tom sets a minimum PHQ Rank threshold of 30, which is recommended for his industry:

```python
params={
  "rank.gte": 30
  }
```

</details>

<details>

<summary>Event state</summary>

Track events based on their likelihood of occurring:

* **Event state**: Events with the `active` state have confirmed details including start dates and locations, whereas the details of \`predicted\` events are [subject to change](https://docs.predicthq.com/getting-started/predicthq-data/predicted-events) as more information becomes available. PredictHQ marks events as `deleted` if they are canceled, postponed, or otherwise removed.

Focusing primarily on `active` and `predicted` event states ensures that only events which are relevant and likely to occur are tracked

**Settings for Tom’s Pizzeria**

Tom is interested in all upcoming events in June 2024 and has decided to include `predicted` events as well:

```python
params={
  "state": "active,predicted"
  }
```

</details>

<details>

<summary>Query modifiers</summary>

Optimize search results with these parameters:

* **Limit**: Specify the maximum number of events per page to return, managing the volume of results and focusing on the most relevant events. To navigate to additional results, use the `next` field in the API response (refer to [#handling-paginated-api-responses](#handling-paginated-api-responses "mention") for more details).
* **Sort**: Order the search results according to specific attributes, most commonly event impact such as `rank` or `phq_attendance`, to prioritize high impact events.

**Settings for Tom’s Pizzeria**

Tom is interested in the top 50 upcoming events for June 2024 that could impact his business. He sets the search parameters to not only manage the scope of results but also ensure that the most significant events are returned first:

```python
params={
   "limit": 50,
   "sort": "rank"
   }
```

</details>

{% hint style="info" %}
For detailed information on all query parameters (including those not shown here), consult [Events API](https://docs.predicthq.com/api/events/search-events).
{% endhint %}

### Step 2. Call Events API

With the query parameters configured, call the Events API. This can be done using our [API Explorer](https://control.predicthq.com/explorer/events) or via your preferred tool. The following is an example of Tom's request using Python:

```python
import requests

base_url = "https://api.predicthq.com/v1/events"

headers = {
    "Authorization": "Bearer $API_TOKEN",  # Replace $API_TOKEN with your actual token
    "Accept": "application/json"
}

params = {
    "saved_location.location_id": "<location_id>",  # Use the location_id from the Saved Location created in Step 1
    "category": "public-holidays,school-holidays,conferences,concerts,performing-arts",
    "active.gte": "2024-06-01",
    "active.lte": "2024-06-30",
    "rank.gte": 30,
    "limit": 50,
    "sort": "rank",
    "state": "active,predicted"
}

response = requests.get(base_url, headers=headers, params=params)
if response.status_code == 200:
    print(response.json())
else:
    print(f"Error fetching response: {response.status_code}")
```

#### Handling paginated API responses

The Events API responses come in a paginated format to limit the amount of data sent in a single response. Here's how you can automatically loop through the paginated API responses to collect all available results:

```python
def fetch_all_pages(base_url=base_url, headers=headers, params=params):
    results = []
    next_url = base_url  # Start with the base URL

    while next_url:
        response = requests.get(next_url, headers=headers, params=params)
        params = None  # After the first request, prevent re-sending initial parameters
        if response.status_code == 200:
            data = response.json()
            results.extend(data['results'])
            next_url = data.get('next')  # Update the next_url from the 'next' field in the response
        else:
            print(f"Failed to fetch data: {response.status_code}, Message: {response.text}")
            break

    return results

all_events = fetch_all_pages()
print("Total events fetched:", len(all_events))

```

For information on how to search for events using our SDK, refer to [Python SDK](https://docs.predicthq.com/sdks/python-sdk)

{% hint style="info" %}
For more details, visit:

* [Search events](https://docs.predicthq.com/api/events/search-events)
* [Python SDK](https://docs.predicthq.com/sdks/python-sdk)
  {% endhint %}

### Step 3. Interpret the response

After you call the API, the Events API returns a structured JSON response containing detailed information about the events that match the query parameters. The following is an illustrative example of what the first page of this response might look like, demonstrating initial pagination details and a sample event listing:

<details>

<summary>Example response</summary>

```json
{
  "count": 388,
  "overflow": false,
  "next": "https://api.predicthq.com/v1/events/?active.gte=2024-06-01&active.lte=2024-06-30&category=public-holidays%2Cschool-holidays%2Cconferences%2Cconcerts%2Cperforming-arts&limit=50&offset=50&rank.gte=30&saved_location.location_id=%3Clocation_id%3E&sort=rank&state=active%2Cpredicted",
  "previous": null,
  "results": [
    {
      "relevance": null,
      "id": "4hFctf3GqQ2MS5qYLW",
      "title": "Itzy",
      "alternate_titles": [
        "ITZY 2ND WORLD TOUR 'BORN TO BE'",
        "ITZY at WAMU Theater",
        "Itzy (Concert)"
      ],
      "description": "",
      "category": "concerts",
      "labels": [
        "concert",
        "music"
      ],
      "rank": 62,
      "local_rank": 77,
      "phq_attendance": 4201,
      "entities": [
        {
          "entity_id": "hckgG3yNMg5PRGsL49pNzK",
          "name": "ITZY",
          "type": "organization"
        },
        {
          "entity_id": "3AedBWTgigZjWx9NhwLsvgU",
          "name": "CenturyLink Field - WaMu Theater",
          "type": "venue",
          "formatted_address": "800 Occidental Avenue South\nSeattle, WA 98134\nUnited States of America"
        }
      ],
      "duration": 0,
      "start": "2024-06-07T03:00:00Z",
      "start_local": "2024-06-06T20:00:00",
      "end": "2024-06-07T03:00:00Z",
      "end_local": "2024-06-06T20:00:00",
      "predicted_end": "2024-06-07T07:10:00Z",
      "predicted_end_local": "2024-06-07T00:10:00",
      "updated": "2024-05-15T18:25:53Z",
      "first_seen": "2024-01-26T02:32:24Z",
      "timezone": "America/Los_Angeles",
      "location": [
        -122.3322862,
        47.5933082
      ],
      "geo": {
        "geometry": {
          "coordinates": [
            -122.3322862,
            47.5933082
          ],
          "type": "Point"
        },
        "placekey": "zzw-223@5x4-4vs-mp9"
      },
      "impact_patterns": [
        {
          "vertical": "accommodation",
          "impact_type": "phq_attendance",
          "impacts": [
            {
              "date_local": "2024-06-05",
              "value": 841,
              "position": "leading"
            },
            {
              "date_local": "2024-06-06",
              "value": 4201,
              "position": "event_day"
            },
            {
              "date_local": "2024-06-07",
              "value": 421,
              "position": "lagging"
            }
          ]
        },
        {
          "vertical": "hospitality",
          "impact_type": "phq_attendance",
          "impacts": [
            {
              "date_local": "2024-06-04",
              "value": 85,
              "position": "leading"
            },
            {
              "date_local": "2024-06-05",
              "value": 1051,
              "position": "leading"
            },
            {
              "date_local": "2024-06-06",
              "value": 4201,
              "position": "event_day"
            },
            {
              "date_local": "2024-06-07",
              "value": 127,
              "position": "lagging"
            }
          ]
        }
      ],
      "scope": "locality",
      "country": "US",
      "place_hierarchies": [
        [
          "6295630",
          "6255149",
          "6252001",
          "5815135",
          "5799783",
          "7174408",
          "5809844"
        ]
      ],
      "state": "active",
      "private": false,
      "predicted_event_spend": 325046,
      "predicted_event_spend_industries": {
        "accommodation": 77435,
        "hospitality": 188904,
        "transportation": 58707
      },
      "phq_labels": [
        {
          "label": "pop",
          "weight": 0.53
        },
        {
          "label": "other",
          "weight": 0.47
        }
      ]
    },
    {
      // More results...
    }
  ]
}
```

</details>

#### Key response fields

<details>

<summary>Pagination</summary>

The Events API returns results in a paginated format, where your subscription limits determine the number of events per page. The key fields related to pagination include:

* `count`: The total number of events that match the search criteria.
* `next` and `previous`: URLs that can be used to navigate to the next or previous pages of results, respectively.
* `overflow`: If `true`, this indicates more results are available but cannot be reached through normal pagination due to subscription limits. To reduce the number of results returned, make your search query more specific.

For more comprehensive guidelines on navigating paginated results, refer to [Pagination](https://docs.predicthq.com/api/overview/pagination).

</details>

<details>

<summary>Events</summary>

The response lists events in the results section, each as a JSON block. The amount of information provided for each event can vary depending on the type of event and other factors. A comprehensive guide that covers each available field can be found in [Search events](https://docs.predicthq.com/api/events/search-events). Common response fields include:

**Dates**:

* `start_local`, `end_local`: Indicates the start and end dates of the event in the local time zone. If an end date is not available, it defaults to the start date. For some events where the end date is not available, a [Predicted End Time](https://docs.predicthq.com/getting-started/predicthq-data/predicted-end-times) fills this gap with `predicted_end_local`.
* `start`, `end`, `predicted_end`: Indicates the start, end, and predicted end dates in UTC.

**Location**:

* `geo`: Includes the latitude/longitude coordinates of the event as well as additional location information which is especially useful for events that cover an area rather than a point (see [working with polygons](https://docs.predicthq.com/getting-started/guides/geolocation-guides/working-with-polygons)), such as parades.
* `place_hierarchies`: Lists the [place IDs](https://docs.predicthq.com/getting-started/guides/geolocation-guides/understanding-place-hierarchies) associated with the event location.
* `country`: Identifies the country where the event takes place.

**Event descriptors**:

* `title`: The name of the event.
* `description`: A brief description of what the event entails, if available.
* `category`: The [type of event](https://docs.predicthq.com/getting-started/predicthq-data/event-categories), such as concerts or public holidays.
* `phq_labels`: [Tags](https://docs.predicthq.com/getting-started/predicthq-data/labels) that classify the event into common themes or topics. Note, `labels` is a legacy field that isn't maintained.

**Event impact**:

* `rank`: The [predicted impact](https://docs.predicthq.com/getting-started/predicthq-data/ranks/phq-rank) of the event based on a globally comparable rank index.
* `local_rank`: The [predicted impact](https://docs.predicthq.com/getting-started/predicthq-data/ranks/local-rank) of the event, taking into account the local area.
* `phq_attendance`: The number of people [predicted to attend](https://docs.predicthq.com/getting-started/predicthq-data/predicted-attendance) the event, for [attendance-based events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events).
* `impact_patterns`: The [predicted impact](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns) of how the event affects various industries on days surrounding the event.
* `predicted_event_spend`: The [predicted financial impact](https://docs.predicthq.com/getting-started/predicthq-data/predicted-event-spend) of the event on local businesses.

</details>

{% hint style="info" %}
For more details, visit:

* [Pagination](https://docs.predicthq.com/api/overview/pagination)
* [Search events](https://docs.predicthq.com/api/events/search-events)
* [Working with dates, times and timezones](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-dates-times-and-timezones)
* [PredictHQ data](https://docs.predicthq.com/getting-started/predicthq-data)
  {% endhint %}

## Next steps

With a clear view of upcoming events, Tom plans to leverage this information for various analytical and operational improvements at his Pizzeria:

* **Data Analysis and Reporting**: Tom will load event data into Power BI to generate detailed reports and dashboards, following [Using event data in Power BI](https://docs.predicthq.com/integrations/third-party-integrations/using-event-data-in-power-bi) for step-by-step instructions.
* **Relevant Events**: Tom aims to pinpoint event categories that impact his business the most by using [Beam](https://docs.predicthq.com/api/beam/overview) in the [WebApp](https://control.predicthq.com/beam). This helps him allocate his resources more effectively.
* **Forecast Future Orders**: Recognizing the benefits of predictive analytics, Tom is considering developing a demand forecasting model using [Power BI’s AutoML feature with PredictHQ’s event data](https://docs.predicthq.com/getting-started/guides/features-api-guides/integrate-with-a-demand-forecast-in-powerbi). This helps predict customer flows and optimize resource planning.

## Conclusion

This tutorial has demonstrated how to effectively use the Events API to filter out noise and identify events that are most relevant to your business. From configuring query parameters to interpreting the responses, you now have the tools to make informed decisions and strategically plan for future opportunities.


# Displaying events in a heatmap calendar

Learn how to create a heatmap-styled calendar to display event attendance for a location.

Event data provides critical insights into activities that can impact businesses. By tracking when and where events occur, businesses can optimize operations, marketing, and resource allocation. For instance, a surge in local events could indicate an increase in customer traffic, enabling businesses to adjust staffing and inventory levels accordingly.

This tutorial demonstrates how to use PredictHQ event data to build a heatmap calendar, starting with a simple build using [JavaScript D3](https://d3js.org/), followed by guidance on filtering and retrieving the underlying event data from PredictHQ's Features API. The goal is to provide a simple example so you can incorporate events into your own calendar view.

## Heatmap calendars

Heatmap calendars display data density over time, making it easier to identify patterns and trends, such as busy days. This visual tool allows users to quickly view upcoming peak periods at a glance. For example, a hotel booking platform might use a heatmap calendar to visualize peak booking periods associated with local events, aiding in pricing strategy, inventory management, and customer satisfaction by preempting high-demand times.

## Example calendar

This section goes through a simple example to demonstrate the basic functionality of a heatmap calendar and the integration of PredictHQ data. Explore the example through the following Observable notebook:

{% embed url="<https://observablehq.com/@predicthq/features_api_heatmap>" %}

{% hint style="info" %}
To experiment with this example, consider [forking the notebook](https://observablehq.com/documentation/notebooks/forking). This allows you to edit and modify the code as needed. For more information on Observable notebooks, see this [demo](https://observablehq.com/@observablehq/demo).
{% endhint %}

### Getting started

You need an Access Token to call PredictHQ's APIs and run the notebook. Follow the [API quickstart instructions](https://docs.predicthq.com/getting-started/api-quickstart) to obtain one if needed.

### Event data

The heatmap calendar uses aggregated event data from the [Features API](https://www.predicthq.com/apis/features-api) to display the total attendance per day. Selecting a specific day reveals additional event details via the [Events API](https://www.predicthq.com/apis/event-api), adding an interactive layer to the experience.

To view the code used to call the Features API, Events API, and other functions (if not already pinned):

* In the Observable notebook, click a cell's margin.
* Alternatively, in the cell menu, click **Edit**.

{% hint style="info" %}
For more information on the Features API, see [What is the Features API?](https://docs.predicthq.com/getting-started/core-concepts/what-is-the-features-api)
{% endhint %}

### Specifying parameters

Set the following parameters:

* **Date Range Start**: Set the start date for the period of interest.
* **Location**: Select one of the predefined locations.
* **Categories**: Choose the event categories to consider.

{% hint style="info" %}
For guidance on effectively querying the Features API, see [#customizing-event-data](#customizing-event-data "mention").
{% endhint %}

### Calendar

The calendar updates automatically based on the specified parameters. In this example, the intensity of the shading on the calendar reflects the total attendance for each day, reflecting how busy each day is. Interact with the calendar by:

* Hovering over the days to reveal more detailed information about the events.
* Clicking specific days to surface the specific events occurring, providing more granular details.

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXe91XOWCl6CkoPUeqz46MlUxCvuzyakT2cKIeKaRUhM8LNXaZf-dkjDmKZ66xSHw8OrJmvlLQcZrP4ZlwU4LC9A7O83H1bGpJ4vEdpJwHwXcceBx-adNwQV7GcBHdMU5NssX8zGHEkraTe28PGHZqLdFpGI?key=yHYQOK_XUxkGtvg9Am0g5g" alt="A heatmap calendar in which darker shading marks days with higher total event attendance" width="563"><figcaption><p>Interacting with the heatmap calendar</p></figcaption></figure>

### Exporting code

You can also [compile](https://observablehq.com/documentation/embeds/advanced#notebooks-as-es-modules) the notebook and download it as a JavaScript module. To do this:

1. Use the notebook menu to select **Export**.
2. To save a local copy, choose **Download code**.

### Extension

Another approach to using calendars is to showcase the most impactful events, including links to their respective pages in the WebApp. This method involves fetching event data from the [Events API](https://docs.predicthq.com/api/events/search-events), sorting by attendance, and then directly displaying the top events on the calendar.

{% hint style="info" %}
For more information on using the Events API, see [Filtering and finding relevant events](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events).
{% endhint %}

## Customizing event data

This section provides guidance on how to customize the underlying event data using the Features API. Tailor your event data by specifying the following [fields](https://docs.predicthq.com/api/features/get-features):

<details>

<summary>Date range</summary>

Set the date range as follows:

* Define a date range for the period of interest.
* Configuration: Use the `active` field.

</details>

<details>

<summary>Location of interest</summary>

Set the location as follows:

* Determine the geographical area for which event data is required.
* Configuration: To specify a latitude, longitude, and radius or place ID for a specific city or region, use the `location` field (as in the earlier example calendar).
* Guidance: For details on how to set locations, refer to [Industry recommendations](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters#location-type).

</details>

<details>

<summary>Event categories</summary>

Choose the categories as follows:

* Identify the types of events of interest, such as concerts, sports, or community events.
* Configuration: In the request body, add `<feature_name>`, specifying `stat` and `phq_rank` as needed (see the Aggregation Statistic and Minimum Event Rank sections).
* Guidance: Start with [features](https://docs.predicthq.com/api/features/get-features#available-features) prefixed by `phq_attendance` for [attendance-based categories](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events); other categories may require additional adjustments. For details on how to set event categories, refer to [Industry recommendations](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters#relevant-event-categories).

</details>

<details>

<summary>Aggregation statistic</summary>

Choose the aggregation as follows:

* Choose how to aggregate event data at the daily level.
* Configuration: Use the `stat` field under `<feature_name>`.
* Guidance: To visualize the total daily attendance, set it to `sum`, which offers insights into people movement. To monitor the daily count of events, set it to `count`, though it should be noted that this does not reflect event attendance or size.

</details>

<details>

<summary>Minimum event rank</summary>

Set the minimum rank as follows:

* To filter out small events that are unlikely to have a significant impact, set a threshold based on [PHQ Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/phq-rank).
* Configuration: Use the `phq_rank` field under `<feature_name>`.
* Guidance: For details on how to set the minimum event rank, refer to [Industry recommendations](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters#minimum-phq-rank).

</details>

{% hint style="info" %}
For an example of calling the API in JavaScript, see the [Observable notebook's data code](https://observablehq.com/@predicthq/features_api_heatmap#data). For more information on using the Features API, see these [guides](https://docs.predicthq.com/getting-started/guides/features-api-guides).
{% endhint %}

## Conclusion

This tutorial has demonstrated how to create a heatmap calendar with PredictHQ’s APIs, from fetching event data to visualizing it interactively. It is an effective tool that helps you plan for events and their impacts, supporting informed, data-driven decisions. Adapt the provided example and customize the heatmap to align with your specific operational needs.

<br>


# Displaying events on a map

Learn how to display events on a map for a specific location.

Events can significantly impact businesses. Understanding when and where events are scheduled helps businesses optimize operations, marketing strategies, and resource management. Maps provide a visual representation of these events, allowing for quick identification of regions of interest and potential impact zones. For example, [a ride-sharing platform](https://www.predicthq.com/blog/4-ways-event-data-enhances-rideshare-and-mobility-app-ui) can use this data to predict areas of high demand, directing drivers to where upcoming events are likely to increase the need for rides.

This tutorial demonstrates how to create a dynamic map using PredictHQ event data to visualize events geographically. It begins with a simple JavaScript example using [Leaflet](https://leafletjs.com/) and then looks at how to retrieve relevant events using PredictHQ's Events API. The goal is to provide a straightforward example to help you incorporate events into any map view.

## Example map

This section presents a simple example demonstrating the basic functionality of a map integrated with PredictHQ data. Explore this through the following Observable notebook:

{% embed url="<https://observablehq.com/@predicthq/events-map-example>" %}

{% hint style="info" %}
To experiment with this example, consider[ forking the notebook](https://observablehq.com/documentation/notebooks/forking). This allows you to edit and modify the code as needed. For more information on Observable notebooks, see this[ demo](https://observablehq.com/@observablehq/demo).
{% endhint %}

### Getting started

An Access Token is required to access PredictHQ's APIs and run the notebook. If you need one, follow these [instructions](https://docs.predicthq.com/getting-started/api-quickstart) to obtain it.

### Event data

The map uses event data from PredictHQ's Events API, which provides detailed, event-level information, including the title, dates, and location. This granularity makes the data ideal for mapping.

{% hint style="info" %}
For more information on the Events API, see the [Events API documentation](https://docs.predicthq.com/api/events/search-events).
{% endhint %}

### Parameters

For this example, the [fetchEvents code in the example notebook](https://observablehq.com/@predicthq/events-map-example#fetchEvents) retrieves events from the Events API based on the following criteria:

1. **Date Range**: The code considers events taking place within the next seven days from today to keep the data current and actionable.
2. **Location**: The geographical focus is on San Francisco, offering a targeted view of local events.
3. **Categories**: The focus is on sports events and their potential to draw large crowds.
4. **Event Rank**: The example prioritizes events with the largest Predicted Attendance, as indicated by their [PHQ Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/phq-rank). This ensures the map highlights the most significant events, providing a clear view of potential major draws in the area.

{% hint style="info" %}
For guidance on effectively querying the Events API, see [#customizing-event-data](#customizing-event-data "mention") later in this guide.
{% endhint %}

### Map

This example displays the most impactful sports event in San Francisco for the upcoming week. Interact with the map by:

* Zooming in and out to view all events.
* Clicking specific events for more details.

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXdFMd0QGP6NB67jU-826iGqRO-u5vNx4o4TEAKbgk9HI0uEJFLm-l84383lOPmK78hGVIEi_m5Jz8_Ed2H-qNVwBI0qFvBwjcaLGkDAvgX6jWsyGpiTU1CMUqV95V8AYfC21U8hlCqNr1QGcXLofXG8zjBf?key=Zcee3-lj9wWgy6r9JpJLQw" alt="A map of San Francisco showing the location of an upcoming sports event, with a pop-up of event details" width="563"><figcaption><p>Interacting with the map</p></figcaption></figure>

### Geographic features

The Events API returns event coordinates in the `geo` field. It uses GeoJSON format, which means the Events API returns longitude first, then latitude e.g. Downtown San Francisco is `[-122.39, 37.79]`, not `[37.79, -122.39]`.

The main focus of this example is on `point` type events, occurring at [basic location guidance in the geolocation overview](https://docs.predicthq.com/getting-started/guides/geolocation-guides/overview#basic-location). The Events API classifies events covering larger areas, such as parades, as `polygon` or `multipolygon`. The `geo` field also contains all the relevant geometry information you need to render these types of events on a map.

{% hint style="info" %}
For more information on how PredictHQ events are geographically represented, see this [overview](https://docs.predicthq.com/getting-started/guides/geolocation-guides/overview).
{% endhint %}

### Exporting code

You can also [compile and download](https://observablehq.com/documentation/embeds/advanced#notebooks-as-es-modules) the notebook as a JavaScript module. To do this:

1. Use the notebook menu to select **Export**.
2. For a local copy, choose **Download code**.

## Additional examples

For examples of maps created in Python, explore these [demo apps](https://docs.predicthq.com/getting-started/guides/streamlit-demo-apps). The source code for rendering events in these apps is available on GitHub. Check out [utils/map.py](https://github.com/predicthq/streamlit-parking-demo/blob/main/utils/map.py) and [map.py](https://github.com/predicthq/streamlit-parking-demo/blob/main/map.py) for the parking demo which provides a practical example of visualizing events with Python and [Streamlit](https://streamlit.io/).

## Customizing event data

You can customize the event data the Events API returns by adjusting parameters such as date range, location, and categories, among others.

For detailed guidance on configuring these parameters to meet your specific requirements, refer to the [Define Query Parameters](https://docs.predicthq.com/pages/RPpp9hzaFXKf8e0McsXG#step-1.-define-query-parameters-for-the-events-api) section in [Filtering and finding relevant events](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events). This tutorial provides step-by-step instructions on how to retrieve the most relevant event data for your needs.

## Conclusion

This tutorial has demonstrated how to create a dynamic map using PredictHQ's Events API, from retrieving event data to its geographic visualization. This approach provides key insights into the impact of events, enabling data-driven decision-making. Adapt the provided example to tailor the map to your specific operational requirements.


# Features API guides

Guides for the Features API - model-ready demand signals engineered from real-world events. Always call it with a `beam.analysis_id`; run [Beam](https://docs.predicthq.com/getting-started/guides/beam-guides) first if you haven't.

Recommended order:

1. [What is the Features API?](https://docs.predicthq.com/getting-started/core-concepts/what-is-the-features-api) - why engineered features beat manual event aggregation
2. [Get features with the Features API](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/get-features-with-features-api.ipynb) - the retrieval notebook
3. [Improving demand forecasting models with event features](https://docs.predicthq.com/getting-started/guides/features-api-guides/improving-demand-forecasting-models-with-event-features) - the worked walkthrough, from finding relevant events to a forecasting model with event features
4. [Demand forecasting with event features](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/demand-forecasting-with-event-features.ipynb) - the full modeling workflow notebook
5. [Forecasting demand in Power BI with event features](https://docs.predicthq.com/getting-started/guides/features-api-guides/integrate-with-a-demand-forecast-in-powerbi) - the same workflow demonstrated end to end in Power BI AutoML
6. [Using event features with time series foundation models](https://docs.predicthq.com/getting-started/guides/features-api-guides/using-event-features-with-time-series-foundation-models) - features as future covariates for pre-trained models

Remember the serving path: models trained on these features need future-dated features at every forecast run - see the [Features API reference](https://docs.predicthq.com/api/features/get-features) for training and inference windows.


# Improving demand forecasting models with event features

Learn how to integrate PredictHQ's event features into your demand forecasting model.

Adding PredictHQ event features to a demand forecasting model reduces forecast error in a way you can measure and attribute - and what a point of accuracy is worth is relative to your business: at enterprise scale, even a fraction of a percent less forecast error can mean millions of dollars in better staffing, inventory, and pricing decisions.

This tutorial guides you through the process of identifying, retrieving, and integrating relevant, demand-driving event features into a demand forecasting model. Follow along by running the accompanying Jupyter notebooks while referring to the provided links for more technical details. The tutorial concludes with a practical example of a demand forecasting model that incorporates PredictHQ event features.

## Harnessing event signals

### Events driving demand

Events, such as concerts, expos, and public holidays, are known to affect consumer behavior and [drive demand](https://www.predicthq.com/use-cases/demand-forecasting). PredictHQ offers event data across [more than a dozen categories](https://docs.predicthq.com/getting-started/predicthq-data/event-categories), featuring a [wide range of labels](https://docs.predicthq.com/getting-started/predicthq-data/labels). The [powerful data processing pipeline](https://www.predicthq.com/intelligence) ensures the delivery of high-quality, enriched event data that can be seamlessly incorporated as features into any demand forecasting model.

### Integrating event features

Built upon extensive event coverage, PredictHQ’s event features aggregate similar events into predefined groups for specific locations at set intervals, such as daily aggregations. These prebuilt, forecast-ready features can be added directly to machine learning models without further preprocessing. Access to an extensive library of features is available through the [Features API](https://www.predicthq.com/apis/features-api). We recommend starting with the Important Features that the [Beam API](https://www.predicthq.com/beam) identifies.

## How-to guide

The following sections guide you through integrating event features into your demand forecasting models. Follow these instructions and run the accompanying Jupyter notebooks to understand how you can adapt this approach to fit your workflow and improve the accuracy of your models.

### Overview

Adding event features to a demand forecasting model involves two main steps: pulling a list of Important Features from the [Beam API](https://docs.predicthq.com/api/beam/overview) and retrieving prebuilt, forecast-ready features from the [Features API](https://docs.predicthq.com/api/features/get-features) for a store or location.

<figure><img src="https://lh7-us.googleusercontent.com/BxTbjp8PELaPLMrh8664Jzh6W-PzBc73AyL8wvUCmL_7nm3TKIyA5tCMbyH-RmWihWLdi99JKy3RszSsIc0TJPCYeg3YtXUBPkHLclQ_uyRlk1XRa6Rmiz-2h3yLNn9w1K2IOwlrVNBkjHYNoAQjQEM" alt="Diagram of the integration flow: the Beam API supplies a list of Important Features, the Features API returns those features for a store or location, and they feed into a machine learning model."><figcaption><p>An overview of integrating event features into a machine learning model.</p></figcaption></figure>

PredictHQ APIs handle most steps; you provide the following for each store or location:

1. Historical demand data
2. Latitude and longitude
3. Industry

### Step 1. Select relevant event features

With countless events taking place globally throughout the year, identifying events that impact demand at your location is crucial. The [Beam API](https://docs.predicthq.com/api/beam/overview) automatically provides a list of Important Features based on your historical demand data and location. Alternatively, you can access [Beam](https://docs.predicthq.com/api/beam/overview) in our [WebApp](https://control.predicthq.com/beam) and directly [copy the Important Features](https://www.predicthq.com/blog/find-machine-learning-ml-features-to-use-in-forecasting-with-beam) from your browser.

There are two main strategies for determining a list of Important Features for a store or location: Important Features tailored specifically to the store or location, or Important Features based on a group of stores or locations. Review the Important Features by location and Important Features by group of locations sections, and choose the approach that best suits your operational needs.

<details>

<summary>Important Features by location</summary>

If you are able to implement individual models for each store or location, the Beam API’s [Feature Importance](https://docs.predicthq.com/api/beam/analyses/get-feature-importance) endpoint is recommended. It provides a list of Important Features tailored specifically to your store or location. Also referred to as Category Importance in our WebApp, Beam identifies these event features (or categories) as having the greatest impact on your demand.

</details>

<details>

<summary>Important Features by group of locations</summary>

If you manage multiple stores or locations and require a unified set of features, the Beam API’s [Aggregated Feature Importance](https://docs.predicthq.com/api/beam/analysis-groups/get-aggregated-feature-importance) endpoint is recommended. It provides a consolidated list of Important Features across all stores or locations within an [Analysis Group](https://docs.predicthq.com/api/beam/analysis-groups) based on aggregating Feature Importance results from contributing stores or locations.

</details>

<details>

<summary>User inputs</summary>

The following sections highlight what you need to provide for determining a list of Important Features. Explore the accompanying Jupyter notebooks to see how this fits together practically.

**Historical demand data**

Ensure you have enough time-series data that meets [Beam’s requirements](https://docs.predicthq.com/api/beam/analyses/upload-demand-data). Demand can be quantified in any unit relevant to your forecasting model. Common examples include sales in USD for retail stores, number of orders for restaurants, and revPAR for hotels.

**Industry**

Specify your industry as there are several industry-specific settings required in this step such as when using the [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area). If your [industry is not covered](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters), use the default `other`.

**Location**

To define the catchment area around your store or location, use [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area). Create a Saved Location with `origin_geojson` and your industry. PredictHQ then calculates and stores the Predicted Impact Area boundary automatically.

**Rank thresholds**

To automatically calibrate rank thresholds for your industry and location, use Beam. Beam identifies which event types and rank levels materially influence your demand - removing the need to set these manually.

</details>

{% hint style="info" %}
For technical details, visit:

* [Upload demand data](https://docs.predicthq.com/api/beam/analyses/upload-demand-data)
* [Get Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area)
* [Beam](https://docs.predicthq.com/api/beam/overview)
* [Analysis Groups](https://docs.predicthq.com/api/beam/analysis-groups)

For practical implementation:

* [ML features by location with Beam](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/identify-location-level-features-with-beam-api.ipynb)
* [ML features by group with Beam Analysis Groups](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/identify-group-level-features-with-beam-api.ipynb)
  {% endhint %}

### Step 2. Get features

The [Features API](https://docs.predicthq.com/api/features/get-features) provides access to a library of prebuilt, forecast-ready features ready for direct integration into your machine-learning models. Specify the date range, location, and list of features, all of which can be sourced from the [Beam API](https://docs.predicthq.com/api/beam/overview).

Responses from the Features API vary based on the type of feature. Most come with a suite of statistics that indicates how the Features API aggregates the underlying event data daily for a location, e.g. sum, max, count. For `phq_rank_*` features, the response is the daily number of events for each of the [five rank bands](https://www.predicthq.com/features/rankings/phq-rank). We recommend the following aggregations:

| Feature Type       |     stat    |       other       |
| ------------------ | :---------: | :---------------: |
| `phq_attendance_*` |     sum     |    <p><br></p>    |
| `phq_impact_*`     |     max     |    <p><br></p>    |
| `phq_rank_*`       | <p><br></p> | rank-weighted sum |
| `phq_spend_*`      |     sum     |    <p><br></p>    |
| `phq_viewership_*` |     max     |    <p><br></p>    |

**Predicted Impact Patterns**

Some features consider the additional impact from events before and after scheduled dates, offering a more accurate representation of event impacts on demand. This is known as [Predicted Impact Patterns](https://www.predicthq.com/blog/use-demand-impact-patterns-to-predict-how-events-shape-consumer-behavior), which vary by event category and industry. Features including Predicted Impact Patterns are denoted with an industry suffix, such as `phq_attendance_sports_accommodation` or `phq_impact_severe_weather_air_quality_retail`.

{% hint style="info" %}
For technical details, visit:

* [Features](https://docs.predicthq.com/api/features/get-features)
* [Beam](https://docs.predicthq.com/api/beam/overview)

For practical implementation:

* [Get features with the Features API](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/get-features-with-features-api.ipynb)
  {% endhint %}

### Step 3. ML model and future predictions

Event features provided by the [Features API](https://docs.predicthq.com/api/features/get-features) are prebuilt, forecast-ready and ready for immediate use. Merge them into your existing dataset by location ID and date. Incorporating these event features can enhance your model's performance by adding valuable demand-driving event data.

For future predictions, you can access forward-facing data, such as the next two weeks or the upcoming month, by querying the [Features API](https://docs.predicthq.com/api/features/get-features). To incorporate these new features into your production pipeline, work closely with your engineering team.

{% hint style="info" %}
For practical implementation:

* [Demand forecasting with event features](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/demand-forecasting-with-event-features.ipynb)
  {% endhint %}

## Conclusion

By following this tutorial, you should now understand how to enhance your demand forecasting models by integrating PredictHQ's event features. As known drivers of demand, incorporating event signals can noticeably improve the accuracy of your forecasts, empowering you to make more informed decisions and strategize more effectively.

To move from this tutorial into a production integration—covering data storage, refresh cadence, and how Saved Locations, Beam, the Features API, and Events API fit together as a pipeline—see the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern).


# Forecasting demand in Power BI with event features

Use PowerBI's AutoML models to forecast demand using PredictHQ technologies.

## Tools

### PredictHQ

PredictHQ tools and resources:

* [Features API](https://docs.predicthq.com/getting-started/guides/features-api-guides)
* [Beam](https://docs.predicthq.com/getting-started/guides/beam-guides)
* [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area)
* [WebApp](https://control.predicthq.com)
* Tutorial: [Improving demand forecasting models with event features](https://docs.predicthq.com/getting-started/guides/features-api-guides/improving-demand-forecasting-models-with-event-features)

### Microsoft

Microsoft tools and resources:

* [PowerBI AutoML](https://learn.microsoft.com/en-us/power-bi/transform-model/dataflows/dataflows-machine-learning-integration)

## Guide

{% embed url="<https://vimeo.com/905617307>" %}
Xuxu Wang (CDO) demoing this approach with PowerBI
{% endembed %}

### Base model in PowerBI

The starting point is developing a base model in PowerBI (without PredictHQ data). Using a combination of historical data and time trend features, we developed a base model in PowerBI. This initial version yielded a performance of 48%, a good starting point for further enhancement.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F3FVElNJRctKohn9LsLqw%2Fpowerbi-screenshot.png?alt=media&amp;token=33115a46-04ca-4790-9ae9-ced8cca5d57b" alt="PowerBI screen showing the base model&#x27;s performance of 48%, built without PredictHQ data"><figcaption><p>Base model performance in PowerBI (without PredictHQ data)</p></figcaption></figure>

### Improving base model results with PredictHQ

From here, follow the [Improving demand forecasting models with event features](https://docs.predicthq.com/getting-started/guides/features-api-guides/improving-demand-forecasting-models-with-event-features) tutorial book which helps you work out a set of PredictHQ features that are most impactful to your demand using [Beam](https://docs.predicthq.com/api/beam/overview) and [Features API](https://docs.predicthq.com/api/features/get-features). When we have the relevant PredictHQ features we can enhance the model's accuracy.

### Predicted Impact Area

Most teams start with a fixed radius when scoping events around a location. The problem is that the distance over which events influence demand varies—by industry, by location type, and by how people actually move in that area. A radius that works in one market will miss impact or introduce noise in another.

The Predicted Impact Area API returns a location and industry-specific polygon boundary that reflects where event-driven demand impact actually occurs. PredictHQ calibrates boundaries against real demand and event data across industries and geographies.

The recommended approach is to use Saved Locations. When you create a location using `origin_geojson` without specifying a `geojson` area, PredictHQ calculates Predicted Impact Area automatically and stores it against that location. You can then use the `location_id` across all PredictHQ APIs—Events, Features, and Beam—without needing to manage the boundary yourself.

The following example requests the Predicted Impact Area for a location:

```python
import httpx

response = httpx.get(
    "https://api.predicthq.com/v1/impact-area/",
    headers={
        "Authorization": "Bearer YOUR_PREDICTHQ_API_TOKEN",
        "Accept": "application/json",
    },
    params={
        "location.origin": "45.5051,-122.6750",
        "industry": "restaurants",
    },
)

print(response.json())
```

### Demand decomposition and anomaly detection using Beam

Next, the Beam API decomposes our demand data into baseline and remainders. This separation allows us to distinguish regular demand from anomalies and understand the factors driving these demand anomalies, providing a foundation for a more targeted forecasting approach.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FwXRBHqiLRmmj1kHr0a1U%2Fbeam-result-screenshot.png?alt=media&amp;token=7827498c-1dcf-4b14-b685-a95b8ab7ad9e" alt="WebApp screen showing the Beam correlation results for the demand data"><figcaption><p>Beam correlation results shown in the WebApp</p></figcaption></figure>

### Feature Importance using Beam

We then utilized Beam's [Feature Importance API](https://docs.predicthq.com/api/beam/analyses/get-feature-importance) to evaluate the impact of various events on demand fluctuations. This API helped us identify which events significantly influenced demand, informing our model about the types of events to prioritize in our forecasting.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FWa6zAmDgsttrsoANiRFB%2Ffeature-importance-result-screenshot.png?alt=media&amp;token=4d9ef57d-8de5-42d4-b914-51e2484fadfa" alt="WebApp screen showing the Feature Importance results that rank events by their influence on demand"><figcaption><p>Feature Importance results shown in the WebApp</p></figcaption></figure>

### Forecast-ready features using Features API

Finally, using the insights from the Feature Importance API, we employed the Features API to integrate detailed, relevant event data into our model. This precise merging of event data directly correlated with a notable improvement in our model's performance.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F1iahNHRAyjvSxgxzW9aa%2Ffeatures-table-screenshot.png?alt=media&amp;token=789abd4b-186d-43ac-93a9-575b85fae4ab" alt="Table combining Beam results and Features API event features for each date"><figcaption><p>Beam and Features API results</p></figcaption></figure>

### Improve model performance with PredictHQ data

Upon integrating this data into PowerBI, we developed an advanced model that combined both historical data and PredictHQ's event data. The outcome was a significant leap in performance, reaching 75%.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F3QvjCJaD0JL1Mco2jTGt%2Fpowerbi-improved-perf-screenshot.png?alt=media&amp;token=76bdd82a-327d-49e6-870a-8946cc2c52df" alt="PowerBI screen showing the improved model performance of 75% with PredictHQ data"><figcaption><p>75% performance in PowerBI using PredictHQ data</p></figcaption></figure>

### Conclusion

This demonstration not only underlines the effectiveness of combining PredictHQ's technology with PowerBI but also opens up new avenues for accurate demand forecasting across various industries.


# Using event features with time series foundation models

Supply PredictHQ event features as future covariates to pre-trained forecasting models such as Chronos-2, TimesFM, and TimeGPT.

Pre-trained forecasting models are applied zero-shot or with light fine-tuning - there is no per-location training step. They learn temporal patterns from large generic corpora, which means real-world drivers such as concerts, sports fixtures, and holidays are invisible to them unless supplied as covariates. Because events are known in advance, PredictHQ features provide real covariate values across the forecast horizon - no zero-filling or lagged proxies.

Most foundation model interfaces accept these as known future covariates - variously called future covariates, exogenous variables, or dynamic features depending on the model. Support varies by model and version: some accept covariates natively, some only through a wrapper framework, and some not at all - so check your model's documentation rather than assuming the covariates are being used.

One difference from a model you train yourself: a trained ML model learned the event-to-demand relationship at training, so inference needs only forward-looking features. A foundation model learns that relationship from its context window, so every forecast run supplies features for both windows - the demand history and the horizon:

```mermaid
sequenceDiagram
    participant Pipe as Your pipeline
    participant Model as Time series foundation model
    participant PHQ as PredictHQ Features API
    Note over Pipe,Model: No training phase - the model arrives pre-trained
    loop Every forecast run
        Pipe->>PHQ: Features for the demand-history window plus the forecast horizon
        PHQ-->>Pipe: Historical + forward-looking features
        Pipe->>Model: Demand history + features, both windows, in context
        Model-->>Pipe: Forecast
    end
```

## Prepare the covariates

To prepare the covariates:

1. To get an `analysis_id`, run [Beam](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam) for each location. Foundation model covariate mechanisms are lightweight, and published evaluations show accuracy degrading when they're fed noisy or irrelevant series - Beam limits the covariate set to the event signals that drive demand at that location.
2. Retrieve historical features covering the same period as the demand history you pass to the model:

```json
{
  "beam": { "analysis_id": "$ANALYSIS_ID" },
  "active": { "gte": "$HISTORY_START", "lte": "$NOW" }
}
```

3. Retrieve future features covering the forecast horizon:

```json
{
  "beam": { "analysis_id": "$ANALYSIS_ID" },
  "active": { "gte": "$NOW", "lte": "$FORECAST_END" }
}
```

4. Join both windows to your demand series on date.
5. Pass the joined features through the model's covariates interface alongside the demand history.

## Keep the covariates fresh

Retrieve future features ahead of each forecast run rather than caching them: new events are announced inside the forecast horizon continuously, Predicted Attendance values are revised as events approach, and events are canceled. Refresh the Beam Analysis monthly by appending new demand data - see the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) for the production architecture and refresh cadences.

## Related

For more information, see:

* [Features API reference](https://docs.predicthq.com/api/features/get-features) - available features and configuration
* [What is the Features API?](https://docs.predicthq.com/getting-started/core-concepts/what-is-the-features-api)
* [Data Leakage in Backtesting](https://docs.predicthq.com/getting-started/core-concepts/data-leakage-in-backtesting) - why forward-looking features don't leak future information into evaluation


# Forecasts API guides

Guides for the Forecasts API - event-driven demand forecasts without building or maintaining your own model. Beam runs automatically; you supply demand data and consume forecasts with explainability built in.

Recommended order:

1. [Getting started with Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/getting-started) - the full train, forecast, retrain lifecycle
2. [Understanding forecast accuracy metrics](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/understanding-forecast-accuracy-metrics) - reading MAPE and the baseline comparison, so the lift is measured on your own demand
3. [Troubleshooting guide for Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/troubleshooting) - when results don't look right

The Forecasts API also runs well inside multi-model setups - as one candidate in a champion-challenger selection or an ensemble alongside your existing forecasts.


# Getting started with Forecasts API

## Overview

The Forecasts API delivers fast, accurate, and scalable demand forecasts, and the real-world events that impact your business power them. Whether you’re starting from scratch or augmenting an existing model, our event-driven forecasting approach improves accuracy, unlocking significant ROI and cutting development time by months.

This API provides ready-to-use, event-optimized forecasts for your business, embedding the impact of sports, concerts, school holidays, and more directly into the forecast output. There’s no need to source or model event effects separately—we handle it for you.

Why use it:

* Event-aware by default: we build real-world events into every forecast
* Industry-specific performance—designed for demand planners, revenue managers, and ops teams
* Faster and more affordable than building your own system

PredictHQ’s Forecasts API is the only event-driven, fully automated forecasting solution available—built to get you to accurate forecasts without the complexity.

### SageMaker demo

Forecasts API can be used anywhere you can run code (SageMaker, Snowflake, Databricks etc). The demo here is running in AWS SageMaker.

{% embed url="<https://www.loom.com/share/f9c233261a8e4cb58ba8b2c752c4b542?sid=2366ebc2-4c16-4976-b9bc-ef6a0a1d8187>" %}
Forecasts API Notebook Run-Through in AWS SageMaker
{% endembed %}

### Requirements

Before you start, you need the following:

1. An [API Token](https://docs.predicthq.com/getting-started/api-quickstart#create-an-access-token).
2. To run an example yourself and adapt it to your needs, [use our Notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/forecasts-api/demand_forecasting_with_phq_forecasts_api.ipynb).

All code snippets in this guide assume the appropriate config has already been set:

```python
PHQ_API_TOKEN = os.getenv("PHQ_API_TOKEN") or "REPLACE_WITH_YOUR_API_TOKEN"
API_URL = "https://api.predicthq.com"

headers = {
    "Authorization": f"Bearer {PHQ_API_TOKEN}",
    "Content-Type": "application/json"
}

lat = 51.50396
lon = 0.00476
industry = "restaurants"
name = "Sample Restaurant Location"
```

## Forecasting workflow

The workflow has these stages:

```mermaid
---
title: Initial Setup for Forecasting
---
flowchart LR
    A[Create Saved Location] --> B[Define Model]
    B --> C[Upload Initial Demand]
    C --> D[Train Model]
    D --> E[📈 Forecast]
```

### Prepare your data

To generate a forecast, you need to provide a daily time series with two columns:

<table><thead><tr><th width="179.8515625">Column</th><th>Description</th></tr></thead><tbody><tr><td><code>date</code></td><td>The date of the observation, in <code>YYYY-MM-DD</code> format (ISO 8601).</td></tr><tr><td><code>demand</code></td><td>The actual demand value for that date (e.g. units sold, bookings).</td></tr></tbody></table>

Requirements:

* The data must be daily level
* Provide at least 18 months of history for best results
* The API rejects demand data that contains duplicated dates, missing values in the demand column, or non-numeric demand values

Example:

```csv
date,demand
2023-02-03,17696
2023-02-04,28718
2023-02-05,24442
2023-02-06,13468
2023-02-07,12600
2023-02-08,13671
2023-02-09,13324
2023-02-10,16589
```

### Create a model

The API ties each forecast model to a Saved Location, so you can define the location once and create multiple models for it. For this example we're going to look at a theoretical restaurant located by the O2 Arena in London.

#### Create a Saved Location using Predicted Impact Area

Predicted Impact Area calculates the optimal boundary around your business to capture the events that drive demand. To use it, create a Saved Location with `origin_geojson`—the API calculates the Predicted Impact Area automatically and stores it against the location, as this code shows:

```python
# Create Saved Location with Predicted Impact Area
response = requests.post(
    url=f"{API_URL}/v1/saved-locations",
    headers=headers,
    data=json.dumps(
        {
            "name": name,
            "origin_geojson": {
                "type": "Feature",
                "geometry": {
                    "type": "Point",
                    "coordinates": [lon, lat],  # GeoJSON order is lon,lat
                },
            },
            "industry": industry,
        }
    ),
)

location_id = response.json()["location_id"]
print(f"Saved location ID: {location_id}")

# Saved location ID: -ErnOilZkeP6P6CPdcXvTg
```

After creating the Saved Location, we can re-use it across as many forecast models as we need.

#### Create a model

To create the model, run this code:

```python
# Define model
response = requests.post(
    url=f"{API_URL}/v1/forecasts/models",
    headers=headers,
    json={
        "name": f"{name} Forecast",
        "location": {"saved_location_id": location_id},
        "algo": "phq-xgboost",
        "forecast_window": "7d",
        "demand_type": {
            "industry": industry,
        },
    },
)

model_id = response.json()["model_id"]
print(f"Model ID: {model_id}")

# Model ID: Oa1D2XvT-IXfFQ_osoTZjQ
```

#### Upload demand data

To upload your demand data, run this code:

```python
# Upload demand
sample_demand_df = pd.read_csv("data/sample_demand.csv")
sample_demand_json = sample_demand_df.to_json(orient="records")

response = requests.post(
    url=f"{API_URL}/v1/forecasts/models/{model_id}/demand",
    headers=headers,
    json={"demand": json.loads(sample_demand_json)},
)

print(f"Demand upload: {'Successful' if response.status_code == 201 else 'Failed'}")

# Demand upload: Successful
```

#### Train the model

During the training process, Beam analyzes the demand to determine what types of events impact your demand. This includes correlation and Feature Importance testing. The API uses the important features (from Features API) when training your model and when forecasting. To train the model, run this code:

```python
# Train model
response = requests.post(
    url=f"{API_URL}/v1/forecasts/models/{model_id}/train",
    headers=headers,
)

print(f"Model training: {'Successful' if response.status_code == 204 else 'Failed'}")

# Model training: Successful
```

Training usually takes a few minutes.

### Evaluate the forecast model

To compare the model performance to other models, benchmarks, etc., use evaluation metrics such as MAPE. In this example, the benchmark model had a MAPE of 8.96%, as this code shows:

```python
# Get evaluation results
response = requests.get(
    url=f"{API_URL}/v1/forecasts/models/{model_id}",
    headers=headers,
)

print(f"Evaluation metrics: {response.json()['model']['metrics']}")

"""
Evaluation metrics:
{
    'accuracy': {
        'mape': 8.96,
        'mae': 1708.8,
        'rmse': 2259.08
    },
    'demand_data': {
        'date_range': {
            'start': '2023-02-03',
            'end': '2023-08-02'
        }
    },
    'training_data': {
        'date_range': {
            'start': '2023-02-03',
            'end': '2023-08-02'
        },
        'missing_pct': 0.0,
        'missing_dates': []
    }
}
"""
```

Lower values indicate better accuracy. See the [Understanding forecast accuracy metrics](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/understanding-forecast-accuracy-metrics) guide for help interpreting MAPE, MAE, and RMSE.

### Retrieve the forecast

To get the forecast, run this code:

```python
# Get forecast
response = requests.get(
    url=f"{API_URL}/v1/forecasts/models/{model_id}/forecast",
    headers=headers,
    params={
        "date.gte": "2023-08-03",
        "include": "phq_explainability"
    },
)

results = response.json()["results"]
forecasts_df = pd.DataFrame(results)
```

Visualize the actual demand we uploaded as well as the forecasted demand we just retrieved:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F2Bn6bcSd538wj11n8yxj%2Fforecasts-api-time-series-chart.png?alt=media&amp;token=dc1e2298-53f3-487b-a3ee-16a291c01cbf" alt="Time series chart of the uploaded actual demand and the forecasted demand over time"><figcaption><p>Time series chart showing the actual and forecasted demand</p></figcaption></figure>

### Ongoing forecasting

After you have trained a model you can keep using that model in your ongoing workflow:

```mermaid
---
title: Ongoing Forecasting Loop
---
flowchart LR
    C[Upload New Demand] --> E[📈 Forecast]
    E -->|More demand arrives| C
    E -.->|Retrain if model becomes stale| D[Train Model]
    D --> E
```

## Explainability

Every date in the forecast response includes a `forecast` value—that’s the core output you’ll use. Optionally, you can request explainability to get additional context on why the model predicted that value for a given day. This includes a list of impactful real-world events (e.g. school holidays, concerts) that the model considered significant for that date. The API can provide two key pieces of explainability:

* `phq_explainability` - Top events the model has determined are impacting your demand on this date.
* `phq_features` - List of features (from Features API) that Beam's Feature Importance process identified as relevant to your demand, as well as their values. This field is only available if you also purchase our Features product.

{% hint style="info" %}
Explainability is optional. To enable it, use `phq_explainability` in your `include` query param.
{% endhint %}

Here's an example truncated response for a single date showing `phq_explainability`:

```json
{
  "date": "2023-08-03",
  "forecast": 18001.67,
  "phq_explainability": {
    "events": [
      {
        "id": "GqQA6oSLn8CGBao3vM",
        "category": "school-holidays",
        "title": "Newham - Summer Holidays",
        "start_local": "2023-07-22T00:00:00",
        "end_local": "2023-08-31T23:59:59",
        "phq_rank": 86,
        "local_rank": 69
      },
      {
        "id": "AZTohndL3PcdjwGjje",
        "category": "performing-arts",
        "title": "Mamma Mia! the Party",
        "start_local": "2023-08-03T18:30:00",
        "end_local": "2023-08-03T18:30:00",
        "phq_rank": 60,
        "local_rank": 69
      },
      ...
    ]
  }
}
```

## Tips for better forecasts

To get the most accurate results from the Forecasts API, your input data needs to reflect meaningful demand patterns over time. Here are key tips to improve forecast performance and reliability:

* Include enough history: At least 18 months of daily demand helps the model learn seasonal and event-driven patterns.
* Keep it consistent: Submit clean, continuous daily data—no smoothing, gaps, or placeholder values.
* Avoid over-segmentation: Low-volume or highly granular series often perform worse. Aggregate where possible.
* Watch out for tiny values: Very small but non-zero demand can distort percentage-based metrics like MAPE.
* Exclude outliers if needed: Remove early COVID-19 disruptions or other non-repeating anomalies if they don’t reflect current demand.

For more detailed recommendations, see the [Troubleshooting Guide](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/troubleshooting).

## Troubleshooting

If your forecasts aren’t meeting expectations, don’t worry—there are several common reasons why accuracy might be lower than expected. We’ve put together a dedicated [Troubleshooting Guide](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/troubleshooting) to help you identify and resolve these issues.

The guide covers topics like:

* What to do if your forecast accuracy is poor (e.g. noisy or low-volume data)
* Why not enough history can reduce model performance
* How overly fine-grained series can lead to weak signals
* When to remove early COVID-19 disruptions from your dataset

We also have a guide on [understanding forecast accuracy metrics](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/understanding-forecast-accuracy-metrics) (MAPE, MAE, RMSE) meaningfully.

{% hint style="warning" %}
Before tweaking your inputs or retrying, we strongly recommend reviewing the troubleshooting guide—it can save a lot of time and guesswork.
{% endhint %}

## Next steps

To continue:

* [Forecasts API Reference](https://docs.predicthq.com/api/forecasts/overview) - Full schema, endpoints, and parameters
* [Understanding forecast accuracy metrics](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/understanding-forecast-accuracy-metrics) - Guide to interpreting MAPE, MAE, and RMSE
* [Troubleshooting guide for Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/troubleshooting) - Common causes of low accuracy and how to fix them


# Understanding forecast accuracy metrics

The Forecasts API provides three common metrics to help you evaluate how well the model is performing. Each metric highlights a different aspect of error—use them together to get a complete picture.

## MAPE – mean absolute percentage error

MAPE quantifies the average magnitude of forecast error as a percentage of actual values. It’s easy to interpret and especially useful for comparing forecast performance across products, locations, or scales. However, it can become distorted when actual values are close to zero.

{% hint style="info" %}
In plain English – MAPE shows how far off your forecasts are, on average, as a percentage. It’s great for comparing performance across different types of demand—but it may overstate errors when actual demand values are very low.
{% endhint %}

Key points about MAPE:

* Best used when actual values are consistently non-zero.
* Good for comparing forecasts across series with different scales.
* Can produce very large values when actual demand is low, even if the forecast is reasonable.

In our expanding window evaluation framework, the Forecasts API calculates the MAPE not just from a single forecast, but across multiple rolling forecast iterations—this simulates how the model would perform in a real-world setting where forecasts are generated repeatedly over time, and ensures the reported accuracy reflects consistent performance, not just a one-off result.

## WAPE – weighted absolute percentage error

WAPE quantifies the total forecast error as a percentage of the total actual demand. Unlike MAPE, which gives equal weight to each data point, WAPE weights each error by the size of the actual value. This makes it less sensitive to very small actual values, so it's a more reliable measure of accuracy in some situations.

{% hint style="info" %}
In plain English – WAPE shows the share of your total demand that was mis-forecast, with bigger-demand periods counting more. It gives a more balanced view than MAPE when actual values vary a lot or include small numbers that could distort results. WAPE is a good way to measure forecasting accuracy for businesses with regular low-demand or off-peak periods.
{% endhint %}

Key points about WAPE:

* Defined even when some actual values are zero (unlike MAPE, which is undefined in those cases).
* Weights errors by demand size, reducing distortion from very small actual values.
* Best used with stationary series; results may be misleading when demand has strong trends, seasonality, or shifting volatility.

## MAE – mean absolute error

MAE measures the average absolute difference between predicted and actual values, expressed in the same units as your demand (e.g. units sold, bookings). It treats all errors equally, making it a simple and intuitive way to understand overall forecast accuracy.

{% hint style="info" %}
In plain English – MAE tells you how far off your forecast is on average, using the same units you care about—like “bookings” or “items sold”. Every mistake counts the same, so it gives a clear sense of typical error.
{% endhint %}

Key points about MAE:

* Easy to interpret and compare against your typical daily volumes.
* Treats all errors the same—no extra weight on large deviations.
* Best used when actual values are on a consistent scale across time or series.

## RMSE – root mean squared error

RMSE measures the square root of the average squared differences between predicted and actual values, placing greater weight on larger errors.

{% hint style="info" %}
In plain English – RMSE tells you how far off your forecasts are on average, but it especially highlights big mistakes—so if you care about avoiding large misses, RMSE is useful.
{% endhint %}

Key points about RMSE:

* Penalizes larger errors more than MAE does.
* Helpful for identifying volatility or occasional large misses.
* Useful when high-impact outliers matter more than average performance.


# Troubleshooting guide for Forecasts API

## Forecast accuracy issues

If you’re experiencing lower-than-expected forecast accuracy, there are a few common issues worth checking. Forecasting models rely on consistent, pattern-rich historical data to make reliable predictions. The more signal and structure in your input data, the better the output.

### Not enough history

Forecast models rely on repeated patterns in your data—seasonality, trends, and demand shifts over time. Without enough historical coverage, the model may struggle to detect these patterns or overfit to short-term fluctuations. We recommend providing at least 18 months of demand history.

What to try:

* To capture seasonality and other patterns, include at least 18 months of historical demand.
* Aggregate similar items, regions, or stores if individual series are sparse or noisy.
* Focus on stable patterns: if your business underwent recent changes, exclude outdated data that no longer reflects reality.
* Ensure consistent time intervals: avoid gaps or overlapping dates in your time series.

### Weak or unstable signal

Even if your demand data passes basic data quality checks, forecast quality still depends on the strength and consistency of the demand signal. Flat lines, irregular spikes, or inconsistent patterns can make it harder for the model to detect meaningful trends.

What to try:

* To boost volume and pattern strength, aggregate similar products.
* Exclude outliers that don’t represent normal demand behavior (e.g. one-off promotional spikes).
* Avoid artificial smoothing or flooring (e.g. replacing all zero values with 1), which can distort the signal.
* Focus on series that show some recurring variation—the model performs best when it can detect trends and seasonality.

### Early COVID-19 disruption

The early months of the COVID-19 pandemic (typically March–June 2020 or longer for many businesses) created extreme, non-recurring shifts in demand across nearly all industries. Lockdowns, panic buying, or closures drove these sudden drops or surges—none of which represent repeatable patterns the model can learn from.

Including this period in your training data may reduce accuracy, especially if your business has since stabilized or operates differently now.

What to try:

* Exclude the early COVID-19 period (e.g. March–June 2020 or longer) if it doesn’t reflect current conditions.
* Review data around major lockdowns or policy changes, even after 2020, and assess whether it’s relevant to keep.
* If your business fundamentally changed (e.g. moved online, altered operating hours), consider using only post-change data for training.

### Forecasting too fine-grained

Forecasting works best when the signal in your data is stronger than the noise. Extremely granular forecasts—like low-volume SKUs or store-level daily data—can result in high error rates because there’s not enough volume or structure to model accurately.

What to try:

* To build a stronger, more consistent demand signal, aggregate similar products or channels.
* Filter out extremely low-volume series where demand is often zero or close to zero.
* Avoid over-segmenting—forecasting too narrowly (e.g. SKU) may not be practical without enough volume.

### Misaligned seasonality

Some demand patterns repeat consistently each year—others don’t. If your data doesn’t include multiple seasonal cycles, or if the timing of spikes shifts from year to year, the model may struggle to generalize.

What to try:

* Provide multiple full seasonal cycles (e.g. two Christmas periods, two summer holidays).
* Avoid including only recent post-launch data unless the product is truly new.
* To help the model identify which demand shifts are predictable vs. one-offs, use longer history.

### Shifting business patterns

If your business has changed significantly—new pricing models, operational changes, store closures—the model may underperform if older demand no longer reflects current behavior.

What to try:

* Trim outdated data that no longer reflects how your business operates.
* Model each distinct version of the business separately, if feasible (e.g., pre/post relaunch).
* Note recent changes when reviewing forecasts; short-term fluctuations may smooth out over time.

### Misunderstanding accuracy metrics

Metrics like MAPE, MAE, and RMSE can tell different stories depending on your demand volume, volatility, and business goals. Don’t rely on a single metric in isolation.

What to try:

* For a straightforward measure of average error in units, use MAE.
* Use MAPE when your demand values aren’t near zero—it shows relative error in percentage terms.
* Use RMSE if large deviations are especially costly in your business.
* Compare forecasts visually as well—some patterns look worse in numbers than they are in practice.

### Very small but non-zero demand values

MAPE is sensitive not just to zeros, but also to very small non-zero demand values. When actuals are consistently low (e.g. 0.1, 0.5), even minor absolute errors can result in disproportionately large percentage errors. This can make the forecast seem worse than it actually is.

What to try:

* Review your data for unusually small values—are they valid, or could they be artifacts of rounding, smoothing, or unit conversion?
* Consider filtering, aggregating, or removing very low-volume series if they do not represent meaningful demand. This can reduce noise and improve the signal-to-noise ratio in your forecast evaluation.
* Use alternative metrics such as Mean Absolute Error (MAE) or Root Mean Squared Error (RMSE), which are less sensitive to small denominators and provide more stable evaluations.


# Live TV event guides

Live TV Events cover major broadcast sports in the United States, with Predicted Viewership by county - demand that arrives through screens rather than gates. These guides cover finding broadcasts [by county](https://docs.predicthq.com/getting-started/guides/live-tv-event-guides/find-broadcasts-by-county-place-id), [by coordinates](https://docs.predicthq.com/getting-started/guides/live-tv-event-guides/find-broadcasts-by-latitude-and-longitude), [by event](https://docs.predicthq.com/getting-started/guides/live-tv-event-guides/find-all-broadcasts-for-an-event), and [by sport](https://docs.predicthq.com/getting-started/guides/live-tv-event-guides/find-broadcasts-for-specific-sport-types), plus [aggregation](https://docs.predicthq.com/getting-started/guides/live-tv-event-guides/aggregating-live-tv-events). The Live TV notebook series lives in [Data science notebooks](https://docs.predicthq.com/getting-started/data-science-notebooks).

For modeling, use the `phq_viewership_*` features in the [Features API](https://docs.predicthq.com/api/features/get-features) rather than aggregating broadcasts yourself.


# Find Broadcasts by county place ID

For this example we want to find all broadcasts televised in two counties in California during November 2020.

The `location.place_id` parameter allows us to filter live sports events by their broadcast locations. For the counties in our example, we will use `location.place_id=5368381,5391832`, which are the respective Place IDs for Los Angeles County and San Diego County in California.

We found these Place IDs using the [Places API](https://docs.predicthq.com/api/places/search-places). We provide a CSV file of broadcast counties to download, to make it easier to discover the `place_id` for all counties and states in the US.

{% file src="/files/pQOQG0XiC8DoFESe45FK" %}

We can also use the `start.*` parameters to filter broadcasts by time. For the time range in our example, we will use `start.gte=2020-11-01` and `start.lte=2020-11-30`. Using `start.tz=America/Los_Angeles` treats the parameter’s start dates and times in the America/Los\_Angeles time zone, otherwise the API treats the parameter dates and times as UTC. The following request uses these parameters:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/broadcasts/",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer $API_TOKEN"
    },
    params={
        "location.place_id": "5368381,5391832",
        "start.gte": "2020-11-01",
        "start.lte": "2020-11-30",
        "start.tz": "America/Los_Angeles"
    }
)

print(response.json())
```

The following snippet shows part of the results:

```json
{
  "count": 501,
  "next": "https://api.predicthq.com/v1/broadcasts/?location.place_id=5368381%2C5391832&start.gte=2020-11-01&start.lte=2020-11-30&start.tz=America%2FLos_Angeles&offset=10",
  "previous": null,
  "overflow": false,
  "results": [
    {
      "broadcast_id": "56aJFMBmajvnTjM3DUB4JS",
      "dates": {
        "start": "2020-11-01T18:00:00Z",
        "start_local": "2020-11-01T10:00:00",
        "timezone": "America/Los_Angeles"
      },
      "location": {
        "geopoint": {
          "lon": -118.26102,
          "lat": 34.19801
        },
        "place_hierarchies": [
          [
            "6295630",
            "6255149",
            "6252001",
            "5332921",
            "5368381"
          ]
        ],
        "places": [
          {
            "place_id": "5368381",
            "type": "county",
            "name": "Los Angeles County",
            "county": "Los Angeles County",
            "region": "California",
            "country": "US"
          }
        ],
        "country": "US"
      },
      "phq_viewership": 566891,
      "event": {
        "event_id": "24HwKWjyPw3xLBhGza",
        "title": "Los Angeles Rams vs Miami Dolphins",
        "category": "sports",
        "labels": [
          "american-football",
          "nfl",
          "sport"
        ],
        ...
      }
    },
    ...
  ]
}
```

In this example, the Broadcasts API found 501 broadcasts. The snippet shows one of the broadcasts: an NFL game where 56,6891 people will watch the broadcast.


# Find Broadcasts by latitude and longitude

For this example we want to find all broadcasts televised in the county that corresponds to a geopoint (latitude and longitude coordinates).

The `location.origin` parameter allows us to filter broadcasts by a geopoint, such as the location of a store. The Broadcasts API returns broadcasts for the county the geopoint is located in. For our example, we have a store located in Union Square, San Francisco, which has a latitude of `37.7879` and longitude of `-122.4097`. So we will use `location.origin=37.7879,-122.4097`. Using these coordinates returns broadcasts for San Francisco County - the county which Union Square is in.

We can also use the `sort` parameter to order the broadcasts the API returns. For our example, we use `sort=-start` to return the most recently televised broadcasts first:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/broadcasts/",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer $API_TOKEN"
    },
    params={
        "location.origin": "37.7879,-122.4097",
        "sort": "-start"
    }
)

print(response.json())
```

The following snippet shows part of the results:

```json
{
  "count": 34069,
  "next": "https://api.predicthq.com/v1/broadcasts/?location.origin=37.7879%2C-122.4097&sort=-start&offset=10",
  "previous": null,
  "overflow": false,
  "results": [
    {
      "broadcast_id": "389i57kxDfXJLeyiggv3N3c",
      "updated": "2023-07-16T04:43:08Z",
      "first_seen": "2023-07-16T02:24:50Z",
      "dates": {
        "start": "2023-07-29T23:00:00Z",
        "start_local": "2023-07-29T16:00:00",
        "timezone": "America/Los_Angeles"
      },
      "location": {
        "geopoint": {
          "lon": -122.4425,
          "lat": 37.77823
        },
        "place_hierarchies": [
          [
            "6295630",
            "6255149",
            "6252001",
            "5332921",
            "5391997"
          ]
        ],
        "places": [
          {
            "place_id": "5391997",
            "type": "county",
            "name": "San Francisco County",
            "county": "City and County of San Francisco",
            "region": "California",
            "country": "US"
          }
        ],
        "country": "US"
      },
      "phq_viewership": 7773,
      "record_status": "active",
      "broadcast_status": "scheduled",
      "event": {
        "event_id": "F8ueP8SKbHn4xi7kW3",
        "title": "New York Yankees vs Baltimore Orioles",
        "category": "sports",
        "labels": [
          "baseball",
          "mlb",
          "sport"
        ],
        "dates": {
          "start": "2023-07-29T23:05:00Z",
          "start_local": "2023-07-29T19:05:00",
          "predicted_end_local": "2023-07-29T21:55:00",
          "timezone": "America/New_York"
        },
        "location": {
          "geopoint": {
            "lon": -76.61994529999998,
            "lat": 39.2840184
          },
          "place_hierarchies": [
            [
              "6295630",
              "6255149",
              "6252001",
              "4361885",
              "4347820",
              "4347778"
            ]
          ],
          "country": "US"
        },
        "entities": [
          {
            "entity_id": "VQXSiWZ85iHaP9QEZ25Ja6",
            "type": "organisation",
            "name": "New York Yankees",
            "formatted_address": "Bronx\nUnited States of America"
          },
          {
            "entity_id": "diNLbJSNy7Zh6EgSJCe6yw",
            "type": "organisation",
            "name": "Baltimore Orioles",
            "formatted_address": "Baltimore, MD 21201\nUnited States of America"
          },
          {
            "entity_id": "5QFtRcZrNF89kaPUwNS5pU",
            "type": "venue",
            "name": "Oriole Park at Camden Yards",
            "formatted_address": "333 West Camden Street\nBaltimore, MD 21201\nUnited States of America"
          }
        ],
        "phq_attendance": 48876,
        "phq_rank": 84,
        "local_rank": 97
      }
    },
    ...
  ]
}
```


# Find all Broadcasts for an event

In this example we want to find the broadcasts for the Super Bowl game, New England Patriots vs Los Angeles Rams, played on February 3rd 2019.

To find broadcasts for an event, we can use the `event.event_id` parameter. This parameter allows us to retrieve broadcast records for each county the game has viewership in. So, for a specific game televised nation-wide, the API returns over 3000 broadcast records with viewership per county.

The 2019 Super Bowl game's `event_id` is `ePQLUqbPnMn3mQhe35`, so we need to filter broadcasts using `event.event_id=ePQLUqbPnMn3mQhe35`. We found the `event_id` using our Events API. See our [Events API documentation](https://docs.predicthq.com/api/events/search-events) to discover how to query for other sports events. Run the following request:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/broadcasts/",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer $API_TOKEN"
    },
    params={
        "event.event_id": "ePQLUqbPnMn3mQhe35"
    }
)

print(response.json())
```

The following snippet shows the results:

```json
{
  "count": 3055,
  "next": "https://api.predicthq.com/v1/broadcasts/?event.event_id=ePQLUqbPnMn3mQhe35&offset=10",
  "previous": null,
  "overflow": false,
  "results": [
    {
      "broadcast_id": "RjiUnFcNRcZMdDaUX5vJkR",
      "updated": "2021-09-22T03:57:50Z",
      "first_seen": "2020-11-09T19:40:02Z",
      "dates": {
        "start": "2019-02-03T23:30:00Z",
        "start_local": "2019-02-03T17:30:00",
        "timezone": "America/Chicago"
      },
      "location": {
        "geopoint": {
          "lon": -96.15448,
          "lat": 41.29535
        },
        "place_hierarchies": [
          [
            "6295630",
            "6255149",
            "6252001",
            "5073708",
            "5067114"
          ]
        ],
        "places": [
          {
            "place_id": "5067114",
            "type": "county",
            "name": "Douglas County",
            "county": "Douglas County",
            "region": "Nebraska",
            "country": "US"
          }
        ],
        "country": "US"
      },
      "phq_viewership": 178573,
      "record_status": "active",
      "broadcast_status": "scheduled",
      "event": {
        "event_id": "ePQLUqbPnMn3mQhe35",
        "title": "Super Bowl - New England Patriots vs Los Angeles Rams",
        "category": "sports",
        "labels": [
          "american-football",
          "nfl",
          "sport"
        ],
        "dates": {
          "start": "2019-02-03T23:30:00Z",
          "start_local": "2019-02-03T18:30:00",
          "predicted_end_local": "2019-02-03T21:40:00",
          "timezone": "America/New_York"
        },
        "location": {
          "geopoint": {
            "lon": -84.40089219999999,
            "lat": 33.75540290000001
          },
          "place_hierarchies": [
            [
              "6295630",
              "6255149",
              "6252001",
              "4197000",
              "4196508",
              "4195207"
            ],
            [
              "6295630",
              "6255149",
              "6252001",
              "4197000",
              "4191014",
              "4180439"
            ]
          ],
          "country": "US"
        },
        "entities": [
          {
            "entity_id": "Bp2eZ273idefSEQcL8hYJ6",
            "type": "organisation",
            "name": "Los Angeles Rams",
            "formatted_address": "Inglewood, CA 90301\nUnited States of America"
          },
          {
            "entity_id": "cqqvB7RP56CkMANBy9pVMW",
            "type": "organisation",
            "name": "New England Patriots",
            "formatted_address": "Foxborough, MA 02035\nUnited States of America"
          },
          {
            "entity_id": "LJZrFdZT95u9qZ6p4q4ZuK",
            "type": "venue",
            "name": "Mercedes-Benz Stadium",
            "formatted_address": "1 AMB Dr NW\nAtlanta, GA 30313\nUnited States of America"
          }
        ],
        "phq_attendance": 70081,
        "phq_rank": 87,
        "local_rank": 100
      }
    },
    ...
  ]
}
```


# Find Broadcasts for specific sport types

Better understand predicted vs scheduled broadcasts as well as different sport types.

In this example we explain when the different `broadcast_status` values are used and how to search for broadcasts for different sports.

Our Broadcasts API provides broadcast and viewership data for sports with the top viewership in the US. These include broadcasts for games played in the seven top US leagues: NFL, NBA, NHL, MLB, MLS, D1 NCAA Basketball, D1 NCAA Football, and also broadcasts for other sports events with high viewership.

Broadcasts for the seven top US leagues have a `broadcast_status` of `scheduled`. We enrich our data with television listings to determine their televised time and location (county). The `scheduled` `broadcast_status` is for these broadcasts where we know the date, time, and location of a TV broadcast based on TV schedule information.

Broadcasts for sports other than the seven leagues have a `broadcast_status` of `predicted` since we predict their televised time and location (county). The `predicted` `broadcast_status` means we don’t have detailed TV schedule information for the sports event. These events have high viewership, and we assume they are televised nationally (in all counties). These are typically one-off events or are finals of their respective competitions, such as the 2019 NCAA Women's Basketball Final.

For broadcasts with a `predicted` `broadcast_status`, we calculate viewership per county based on many factors including the amount of sports fans in different counties. This information is not as precise as those with the `scheduled` `broadcast_status` but should give a pretty good prediction of who will be watching these large events. You may want to use the `broadcast_status` to indicate the confidence of a broadcast airing; you can build this as a feature or treat scheduled broadcasts differently from predicted.

The API returns broadcasts of all `broadcast_status` values by default. The `broadcast_status` parameter allows us to filter broadcasts with a particular status. The Broadcasts API also supports the `event.label` parameter which can be used to find broadcasts for specific sport types. In this example, we show an API query using the `broadcast_status` and `event.label` parameters which returns broadcasts for the 2019 NCAA Women’s Basketball Final amongst other matching results. You can discover available sport types and event labels by [Searching Live TV Events](https://control.predicthq.com/search/events/broadcasts) in our WebApp or using the [Events API](https://docs.predicthq.com/api/events/search-events). The following example shows the query:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/broadcasts/",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer $API_TOKEN"
    },
    params={
        "broadcast_status": "predicted",
        "event.label": "basketball",
        "start.gte": "2019-04-01",
        "start.lt": "2019-05-01"
    }
)

print(response.json())
```


# Aggregating live TV events

Aggregating Predicted Viewership data to create features for forecasting is an impactful way to unlock the value of Live TV Events data. You can use the Features API to aggregate Predicted Viewership data.

See the Predicted Viewership features in the [endpoint documentation](https://docs.predicthq.com/api/features/get-features). Using these features you can get the count, sum, min, max, avg, median, and std\_dev for any viewership feature in the Features API. The Features API combines all the viewership data for a location and returns these calculated values. For example, you can get the total NFL viewership and NBA viewership per day for a location:

```python
import requests

data = {
    "active": {
        "gte": "2020-02-01",
        "lte": "2020-02-29"
    },
    "location": {
        "place_id": [
            5224323,
            5811704,
            4887398
        ]
    },
    "phq_viewership_sports_american_football_nfl": {
        "stats": [
            "count",
            "sum",
            "avg"
        ]
    },
    "phq_viewership_sports_basketball_nba": {
        "stats": [
            "count",
            "sum",
            "avg"
        ]
    }
}


response = requests.post(
    url="https://api.predicthq.com/v1/features/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    json=data
)

print(response.json())
```


# Beam guides

Working guides and notebooks for Beam, PredictHQ's relevancy engine. Run Beam before configuring features or building forecasts - the `analysis_id` it produces calibrates everything downstream.

Recommended order:

1. [Understanding demand variability and event contribution in Beam](https://docs.predicthq.com/getting-started/guides/beam-guides/understanding-demand-variability-and-event-contribution-in-beam) - how to read what Beam tells you about your demand
2. [ML features by location notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/identify-location-level-features-with-beam-api.ipynb) - from analysis to model-ready features, per location
3. [ML features by group notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/identify-group-level-features-with-beam-api.ipynb) - one consistent feature set across many locations sharing a model
4. [Sample demand data](https://docs.predicthq.com/getting-started/guides/beam-guides/sample-demand-data) - the demand data format Beam expects

New to Beam? Read [What is Beam?](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam) first.


# Understanding demand variability and event contribution in Beam

Not all demand fluctuations are equal. Some are predictable, because day-of-week patterns, long-term growth trends, or seasonal cycles drive them. Others are anomalous: unexpected spikes or drops that sit outside those regular patterns. These anomalies are where events have the most impact, and where accurate forecasting is hardest.

Beam helps you understand and act on this anomalous demand. It identifies how much of your demand is anomalous, and then quantifies how much of that anomalous demand real-world context drives - things like concerts, sports games, conferences, or public holidays near your location.

## How Beam identifies anomalous demand

Beam analyzes your historical demand data and decomposes it into two components:

* **Baseline demand**: The stable, predictable portion of demand. This captures long-term trends, regular seasonal patterns, and recurring cycles - the demand you'd expect even without any unusual external influences.
* **Anomalous demand**: Everything left over after the baseline is removed. This is the variable, irregular portion of demand - the spikes and dips that can't be explained by your regular structured patterns alone. External factors like events, weather, or promotions tend to show up here.

The **demand variability ratio** measures the proportion of your total demand that is anomalous. A higher ratio means anomalous, external factors drive more of your demand - which in turn means there's more opportunity for real-world context to improve your forecasts.

> PredictHQ optimized Beam's decomposition to identify event-driven anomalies, so it may differ from decompositions that other tools such as STL or Prophet produce.

<table><thead><tr><th width="228.62890625">Demand Variability Ratio</th><th>What it means</th></tr></thead><tbody><tr><td>0–5%</td><td>Most demand follows predictable baseline patterns</td></tr><tr><td>5–10%</td><td>Some variability exists, likely influenced by external factors</td></tr><tr><td>>10%</td><td>Anomalies are a significant driver of demand fluctuations</td></tr></tbody></table>

Beam calculates this separately for **positive anomalies** (demand surges) and **negative anomalies** (demand drops), so you can understand both the upside and downside impact.

## How events explain that variability

Once Beam has identified your anomalous demand, the next step is to determine how much of it can be attributed to events.

Beam measures how much of your anomalous demand events explain. This gives you an **event contribution percentage**: the share of your anomalous demand that events happening near your location explain.

For example:

> *"Positive demand variability contributes 12.9% to total demand, and events explain 78% of that."*

This means that roughly 12.9% of your total demand sits above your predictable baseline, and of that elevated demand, events account for nearly 80%.

{% hint style="success" %}
Based on analysis of over 300,000 Beam Analyses across 59,000+ locations in 171 countries over the last 12 months, PredictHQ's event data explains an average of 61% of positive demand variability - though this varies depending on location, industry, and the types of events near your business.
{% endhint %}

Like the demand variability ratio, Beam calculates this separately for positive and negative anomalies, so you can see how events drive both demand surges and demand drops.

## Why this matters for forecasting

Understanding demand variability and event contribution gives you two practical advantages:

1. **Knowing whether events are relevant to your business.** If events explain a large share of your anomalous demand, incorporating event features into your forecasting model is likely to meaningfully improve accuracy. If the contribution is low, other factors (promotions, weather, etc.) may be more important to focus on.
2. **Knowing which events matter.** Beam's Feature Importance analysis goes a step further - it identifies which specific event categories (concerts, sports, conferences, public holidays, etc.) are the primary drivers of your demand variability. This lets you prioritize the right signals when building or refining your models.

## Next steps

To continue:

* To run an analysis on your demand data, use the [Beam API](https://docs.predicthq.com/api/beam/overview).
* See [Feature Importance in Beam](https://docs.predicthq.com/api/beam/analyses/get-feature-importance) to understand which event categories are driving your demand.


# Sample demand data

If you don't have your own demand data ready, you can use one of our sample datasets to explore Beam and the Forecasts API. Each dataset contains synthetic daily demand data modeled on realistic industry patterns. Use any dataset with your own location: the industry type matters more than the specific location when getting started.

## Available datasets

<table><thead><tr><th width="309.421875">Industry</th><th>File</th></tr></thead><tbody><tr><td>Retail</td><td><a href="https://raw.githubusercontent.com/predicthq/gitbook-tech-docs/main/assets/sample-demand-data/sample_demand_retail.csv"><code>sample_demand_retail.csv</code></a></td></tr><tr><td>Restaurants</td><td><a href="https://raw.githubusercontent.com/predicthq/gitbook-tech-docs/main/assets/sample-demand-data/sample_demand_restaurants.csv"><code>sample_demand_restaurants.csv</code></a></td></tr><tr><td>Accommodation</td><td><a href="https://raw.githubusercontent.com/predicthq/gitbook-tech-docs/main/assets/sample-demand-data/sample_demand_accommodation.csv"><code>sample_demand_accommodation.csv</code></a></td></tr><tr><td>Parking</td><td><a href="https://raw.githubusercontent.com/predicthq/gitbook-tech-docs/main/assets/sample-demand-data/sample_demand_parking.csv"><code>sample_demand_parking.csv</code></a></td></tr><tr><td>Other</td><td><a href="https://raw.githubusercontent.com/predicthq/gitbook-tech-docs/main/assets/sample-demand-data/sample_demand_other.csv"><code>sample_demand_other.csv</code></a></td></tr></tbody></table>

PredictHQ is optimized for the following named industries: `accommodation`, `cpg`, `tourism`, `marketing`, `parking`, `restaurants`, `retail`, and `transportation`. If your business doesn't fit one of these, use `other` - the platform applies to any industry, and Beam calibrates to your own demand data either way. See [Industry recommendations](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters) for guidance on choosing.

## Using the sample data

### **With Beam**

Upload the sample data to an existing Beam Analysis using the [Upload demand data](https://docs.predicthq.com/api/beam/analyses/upload-demand-data) endpoint:

```python
import requests

analysis_id = "YOUR_ANALYSIS_ID"
PHQ_API_TOKEN = "YOUR_API_TOKEN"

with open("sample_demand_retail.csv", "rb") as f:
    response = requests.post(
        url=f"https://api.predicthq.com/v1/beam/analyses/{analysis_id}/sink",
        headers={
            "Authorization": f"Bearer {PHQ_API_TOKEN}",
            "Content-Type": "text/csv",
        },
        data=f,
    )

print("Upload successful" if response.status_code == 202 else response.json())
```

See the [Beam guides](https://docs.predicthq.com/getting-started/guides/beam-guides) for a full walkthrough.

### **With Forecasts API**

Upload the sample data to an existing forecast model using the [Upload demand data](https://docs.predicthq.com/api/forecasts/demand-data/upload-demand-data) endpoint:

```python
import requests
import pandas as pd
import json

model_id = "YOUR_MODEL_ID"
PHQ_API_TOKEN = "YOUR_API_TOKEN"

df = pd.read_csv("sample_demand_retail.csv")

response = requests.post(
    url=f"https://api.predicthq.com/v1/forecasts/models/{model_id}/demand",
    headers={
        "Authorization": f"Bearer {PHQ_API_TOKEN}",
        "Content-Type": "application/json",
    },
    json={"demand": json.loads(df.to_json(orient="records"))},
)

print("Upload successful" if response.status_code == 201 else response.json())
```

See the [Getting started with Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/getting-started) guide for a full walkthrough including how to create a model and generate a forecast.

{% hint style="info" %}
We provide these datasets for testing and exploration only. For production use, replace them with your own demand data.
{% endhint %}


# Streamlit demo apps

To demonstrate what you can build with our APIs, we put together some Streamlit demos. All the code is available on GitHub and we encourage you to take the code, modify it, and use your own locations of interest to demo our APIs internally to your team or to better understand our technology. The demos are:

* [Parking Business Demo App](https://predicthq-parking-example.streamlit.app/) ***or*** [get the code from GitHub](https://github.com/predicthq/streamlit-parking-demo).
* [Accommodation Business Demo App](https://predicthq-accommodation-example.streamlit.app/) ***or*** [get the code from GitHub](https://github.com/predicthq/streamlit-accommodation-demo).
* [Restaurant Business Demo App](https://predicthq-restaurant-example.streamlit.app/) ***or*** [get the code from GitHub](https://github.com/predicthq/streamlit-restaurant-demo).
* [Location Insights Demo App](https://predicthq-location-insights-example.streamlit.app/) ***or*** [get the code from GitHub](https://github.com/predicthq/streamlit-location-insights-demo).

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FZGT0YGTv6CTDEF6aqQxh%2Fstreamlit-parking-demo-map-screenshot.png?alt=media&amp;token=02c623dd-8a36-431f-b77a-f2e7997b9111" alt="The map view in the Parking Business Demo App"><figcaption></figcaption></figure>


# Industry recommendations

How PredictHQ tailors results to your industry, the named industry values, and industry-level default categories and rank thresholds for when Beam can't be used.

PredictHQ applies to any business whose demand is shaped by the real world. For a set of named industries, we have gone further and optimized the product directly: industry-specific Predicted Impact Patterns, thresholds, and catchment radii, tuned to how events affect that sector. Specifying a named industry gives you those optimizations out of the box - and either way, Beam personalizes results using your own demand data, which is more specific than any industry preset.

## Named industries

Use the Industry Value when specifying an industry in an API request. If your business doesn’t map exactly, to find the closest fit, use the Examples / Adjacent column, or use `other` - an unlisted industry doesn't limit which events, features, or APIs you can use.

| Named Industry                         | Industry Value   | Examples / Adjacent Industries                                                       |
| -------------------------------------- | ---------------- | ------------------------------------------------------------------------------------ |
| Accommodation                          | `accommodation`  | Hotels, hostels, co-working spaces with short-term stays.                            |
| Consumer Packaged Goods (CPG)          | `cpg`            | Packaged food & beverages, household goods.                                          |
| Leisure, Travel & Tourism              | `tourism`        | Entertainment venues (cinemas, casinos, theme parks), attractions, DMOs, OTAs.       |
| Marketing and Advertising              | `marketing`      | Agencies, ad networks, campaign platforms.                                           |
| Parking                                | `parking`        | Car parks, garages.                                                                  |
| Food and Beverage (Restaurants & Bars) | `restaurants`    | Cafes, pubs, quick service restaurants, hospitality venues.                          |
| Retail                                 | `retail`         | Supermarkets, fashion, electronics, gyms/fitness centers (if sales-oriented).        |
| Transportation and Delivery            | `transportation` | Rail, buses, rideshare, delivery services.                                           |
| Other                                  | `other`          | If your business does not clearly fit into one of the named industries, use `other`. |

## Where industry matters

Our systems use industry to tune how they interpret and model events for your business. This includes areas like Predicted Impact Patterns, thresholds, and catchment radius recommendations:

* **Predicted Impact Area API**\
  Area recommendations vary by industry, since the catchment area for demand differs across sectors.
* **Predicted Impact Patterns**\
  For each event, we calculate its leading and lagging impact per industry. The Features API then uses these patterns to ensure event impacts reflect your sector.
* **Beam**\
  Beam builds on these industry-tuned patterns and thresholds, and further personalizes results with your own demand data.
* **Forecasts API**\
  Uses industry in the same way as Beam (the Forecasts API passes industry to Beam behind the scenes).

## Beam comes first

The most accurate way to identify which events impact your business is with [Beam](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam), PredictHQ’s relevancy engine. Beam analyzes your demand data to surface which event categories matter most at each of your locations, so you don’t need to guess.

Without Beam, you’re guessing which events matter. With Beam, your own demand data tells you - so you cut noise, focus on impact, and avoid costly mistakes.

**If you have demand data, always run Beam first.**

## When you can’t use Beam

If demand data isn’t available, we’ve done research to provide industry-level defaults. These include:

* Recommended Feature Groups (categories) per industry
* Minimum Local Rank thresholds to filter out events too small to matter
* Create a [Saved Location](https://docs.predicthq.com/api/saved-locations/overview) for each of your business locations: this automatically generates a Predicted Impact Area that defines the geographic scope for event retrieval, so you don't need to manage the boundary manually

These are starting points only. Switch to Beam as soon as you can provide demand data.

## Recommended feature groups / categories

<table><thead><tr><th width="236.2265625">Industry</th><th>Recommended Feature Groups / Categories</th></tr></thead><tbody><tr><td>Accommodation</td><td>academic, community, concerts, conferences, expos, festivals, observances, performing-arts, public-holidays, school-holidays, severe-weather, sports</td></tr><tr><td>Parking</td><td>concerts, expos, festivals, observances, performing-arts, public-holidays, school-holidays, sports</td></tr><tr><td>Restaurants</td><td>community, concerts, conferences, expos, festivals, performing-arts, public-holidays, school-holidays, sports</td></tr><tr><td>Retail, CPG</td><td>academic, community, concerts, conferences, expos, festivals, observances, performing-arts, public-holidays, school-holidays, severe-weather, sports</td></tr><tr><td>Transportation</td><td>academic, community, concerts, conferences, expos, festivals, observances, performing-arts, public-holidays, school-holidays, severe-weather, sports</td></tr><tr><td>Tourism, Marketing, and Others</td><td>concerts, expos, festivals, performing-arts, public-holidays, school-holidays, sports</td></tr></tbody></table>

{% hint style="info" %}
When requesting features from Features API with a Beam ID we automatically configure all the correct settings based on the Beam results. When not using Beam, we recommend using the `sum` stat for all relevant features (based on the industry to category mappings in the Recommended feature groups / categories table) except for severe weather where we recommend using the `max` stat to avoid over representing the impact of severe weather events when multiple are overlapping.
{% endhint %}

## Minimum Local Rank thresholds

Local Rank is a location-sensitive scale (0-100, logarithmic) that predicts how much impact an event will have in its immediate vicinity - factoring in population density and local characteristics such as how built-up or accessible an area is. For example, a 1,000-person conference may register a Local Rank of 43 in densely populated Hong Kong and 65 in less crowded Dublin - despite having the same PHQ Rank.

**Beam automatically applies Local Rank filtering** when identifying impactful event types for your demand modeling. However, if you’re setting up filters or queries manually, these thresholds offer a smart default to focus your analysis where it matters until you can rely solely on Beam.

<table><thead><tr><th width="242.7578125">Industry</th><th>Minimum Local Rank</th></tr></thead><tbody><tr><td>Accommodation</td><td>50</td></tr><tr><td>Parking</td><td>50</td></tr><tr><td>Restaurants</td><td>50</td></tr><tr><td>Retail</td><td>35</td></tr><tr><td>Others</td><td>35</td></tr></tbody></table>


# Use case guides

Industry guides that walk the proven path from first API call to measured value, using the integration patterns that have worked across our customers in that industry - so you don't have to rediscover them. Available guides:

* [Accommodation: the proven path to value](https://docs.predicthq.com/getting-started/use-case-guides/accommodation-the-proven-path-to-value)

Whatever your industry, the recommended paths in [How to use PredictHQ](https://docs.predicthq.com/getting-started/how-to-use-predicthq) and the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) apply - the industry guides add the specific event categories, thresholds, and decisions that matter in each vertical. See also [Industry recommendations](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters).


# Accommodation: the proven path to value

Most hotels and platforms know that local events drive demand - but turning that knowledge into actionable insight at scale is hard.

You may spend months trying to work out which event types actually impact demand, define the right radius for each hotel, and transform underlying events into data that can power forecasting and pricing models. These are hard, foundational problems - and PredictHQ has already solved them.

This guide shows the proven, fastest path to value - based on what’s worked across thousands of hotels and the platforms that serve them.

## The fast path to value

Two of the most effective ways accommodation businesses get value from PredictHQ are:

* **Calendar display**: Help hotel teams understand why demand is changing by showing the real-world events driving it. This brings explainability to pricing recommendations, booking patterns, and operational decisions - building trust and improving actionability.
* **Forecasting accuracy**: Strengthen your demand forecasts with high-quality, time-series features built from real-world event impact. Helps revenue and data teams get ahead of demand - not just react to it.

## Calendar display

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FUlONhPqnSzDV3CaZvo5Y%2Faccommodation-calendar-mockup.png?alt=media&amp;token=4895cde0-3281-4ef8-8858-b1e9d4670feb" alt="A hotel calendar showing local events on each day, with the highest Local Rank events listed first"><figcaption></figcaption></figure>

Many accommodation businesses want to show local events in their calendars - to help hoteliers plan ahead, staff smarter, and spot high-demand dates early. It’s a valuable use case. But nearly everyone hits the same challenge:

**There are too many events. How do we show only what matters?**

The challenge isn’t adding event data - it’s helping hotel teams understand which events explain their booking patterns and give them confidence to adjust pricing, staffing, or promotions. Relevance isn’t just about cutting noise - it’s about surfacing the right signals that support human decision-making.

To make a calendar useful - across one hotel or thousands - it needs to:

* Surface demand-driving events, not everything happening nearby
* Scale cleanly across locations and markets without one-off configs
* Build trust by being consistently insightful, not noisy

The challenge is: how do you know which events actually drive demand?

### Use Beam to identify impactful event types

Beam analyzes historical booking patterns to reveal which types of events consistently influence demand for each hotel or group of hotels. It gives you a data-backed filter that ensures each calendar surfaces the most relevant events - and hides the ones that don’t matter (via Beam’s Feature Importance).

### Filter event data accordingly

Once you know the high-impact event types, filter the events for each hotel or group/cluster accordingly - including only those categories, within a relevant radius or polygon. This dramatically reduces volume and increases signal.

### Sort events per day by Local Rank

To help hotel teams quickly understand what’s driving demand on a given day, sort events by [Local Rank](https://docs.predicthq.com/getting-started/predicthq-data/ranks/local-rank). This makes high-impact events easy to spot and supports confident, explainable decisions.

To enhance explainability and usability, consider displaying:

* Predicted Attendance
* Indication of Local Rank
* Show events on their leading/lagging days using Predicted Impact Patterns
* Event type icons
* Collapse/expand toggles for lower ranked events

By showing only the events that actually affect demand, you give hoteliers clear context for why certain days are different - empowering better decisions on pricing, staffing, and planning.

A well-filtered real-world context layer isn’t just raw events - it’s an explainability layer that builds trust, supports human decision-making, and drives faster value without needing complex modeling or deep data integration.

### PredictHQ tools for calendar display

These tools support event calendar displays:

* [Events API](https://docs.predicthq.com/api/events/search-events): Core event data, filtered by category, location, date, and more
* [Snowflake / AWS Data Exchange](https://docs.predicthq.com/integrations/third-party-integrations): Simplified alternative to Events API - access real-world context data directly in your cloud data environment
* [Beam API](https://docs.predicthq.com/api/beam/overview): Identify which event types impact demand using Feature Importance
* [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area): Get area recommendations for each hotel or location
* [Predicted Impact Patterns](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns): Identify leading and lagging demand days around events
* [Entities](https://docs.predicthq.com/getting-started/predicthq-data/entities): Group related events (e.g. concert residencies)

## Forecasting accuracy

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FTKtSK5YHRxRJT4UiQirG%2Faccommodation-forecast-mockup.png?alt=media&amp;token=60994473-7738-4d81-a03f-bbd685895647" alt="A demand forecast chart for a hotel with event-driven demand peaks marked on the timeline"><figcaption></figcaption></figure>

Most forecasting teams know that events drive demand - the challenge is turning the underlying event data into features that actually work in a time-series model.

While rich and detailed, PredictHQ’s underlying event data isn’t structured for modeling out of the box. It’s high-volume, event-specific, and filled with real-world edge cases that are non-trivial to handle, such as:

* Aggregating attendance for multi-day or overlapping events
* Accounting for leading and lagging demand effects (e.g. shoulder nights around a concert)

Even if you're an experienced data science team, you can spend weeks or months designing, testing, and iterating on how to best represent events in your forecasting pipelines.

PredictHQ’s Features API generates demand-relevant, time-series signals at request time designed for forecasting - so your teams can skip the foundational complexity of event aggregation and focus on building reliable, explainable, high-performing models faster.

For teams with mature pipelines, or those exploring model comparisons, PredictHQ’s Forecasts API offers another path. Forecasts API provides demand forecasts that already factor in the impact of events, seasonality, and local dynamics. It suits teams that already have forecasting pipelines and want to:

* Use it as a baseline, racehorse, or ensemble component
* Evaluate the isolated contribution of event-aware demand
* Speed up iteration while avoiding premature engineering work

It’s also a low-risk way to prove the value of event-aware forecasting before making larger architectural changes.

### PredictHQ tools for forecasting

These tools support event-aware forecasting:

* [Features API](https://docs.predicthq.com/api/features/get-features): Model-ready, time-series event features for forecasting
* [Forecasts API](https://docs.predicthq.com/api/forecasts/overview): Demand forecasts with event, seasonality, and local dynamics included
* [Beam API](https://docs.predicthq.com/api/beam/overview): Use Feature Importance to select the most predictive event features

## Iterate and expand

Once the fundamentals are in place, there are simple ways to drive even more value:

* Add alerts to notify your users about new and changed events
* Use [Umbrella Events](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-multi-day-and-umbrella-events) to simplify multi-day experiences - filter out individual sessions (like each race in an F1 weekend) and focus on the overarching event that actually drives bookings. This reduces clutter and makes calendars more explainable for hotel teams
* Use [Concert Residencies](https://docs.predicthq.com/getting-started/predicthq-data/entities#residencies-entities) to notify on a sequence of upcoming concerts rather than each individual event
* Apply an “onion radius” approach to surface major events beyond the immediate area - e.g. include all relevant events within the Predicted Impact Area, then expand to 3× with a Local Rank ≥ 95, and optionally 5× with Local Rank = 100 to capture rare, high-impact events.

## Real examples

These customers have followed this path:

* [Lighthouse](https://www.predicthq.com/customers/lighthouse): Replaced brittle manual event processes with trusted real-world context at scale, reducing support overhead.
* [HQ revenue](https://www.predicthq.com/customers/hqrevenue): Automated demand monitoring and increased RevPAR by 10%.
* [Wheelhouse](https://www.predicthq.com/customers/wheelhouse): Boosted nightly rates by up to 800% during major events with dynamic pricing that PredictHQ powers.

## Common pitfalls

Even well-resourced teams like yours can hit the same traps when working with event data:

* Trying to engineer model-ready features from event data - it’s harder than it looks. Features API handles timing, overlap, weighting, and more so you get clean, usable signals without the complexity.
* Hardcoding event categories or filters based on assumptions - what drives demand varies by location. Use Beam to validate which event types actually impact bookings in each market.
* Assuming one-size-fits-all radius logic - different locations respond to events differently. Use Predicted Impact Area and filter by Local Rank to ensure you’re capturing meaningful impact, not noise.

## Final advice: start simple, scale smart

Don’t overcomplicate your starting point. High-impact events and demand-aware forecasting unlock fast, measurable wins.

Start small - a focused market, a representative set of hotels, or even one city. Prove the value, then scale with confidence. We’ll help you get there.


# Build with AI

Ground AI systems in verified real-world event data and build integrations faster with the MCP server, agent skills, and AI-readable docs.

AI assistants can query PredictHQ's APIs in natural language, search the documentation while you code, and follow best practice integration patterns automatically - reducing the time from first API call to a production-ready integration.

These tools serve two distinct jobs: AI that helps you *build* your integration (coding assistants, agent skills), and AI that PredictHQ *grounds*—assistants and agents retrieving verified real-world context at inference time.

## PredictHQ MCP server

Connect any MCP-compatible AI assistant to PredictHQ's live APIs. Once connected, you can search events, retrieve demand intelligence, work with Saved Locations, Beam, Features, Forecasts, and Predicted Impact Area, and search PredictHQ's technical documentation - all through natural language, without leaving your AI client or writing API calls manually.

Supported clients include Claude, ChatGPT, Claude Code, Cursor, and any other client that supports the Model Context Protocol.

[Set up the MCP server →](https://docs.predicthq.com/ai/mcp)

## Agent skills

Agent skills give your AI coding assistant specialized knowledge about how to integrate with PredictHQ correctly - the recommended workflow, API selection guidance, Beam best practices, and common mistakes to avoid. Once installed, your assistant applies the skill automatically when you work on PredictHQ integrations. To install the skills, run:

```bash
npx skills add predicthq/agent-skills
```

[Set up agent skills →](https://docs.predicthq.com/ai/agent-skills)

## Plain text docs

Every page in PredictHQ's documentation is available as plain text Markdown - useful for pasting directly into an AI assistant or loading into a coding agent's context.

To get the plain text version, add `.md` to the end of any documentation URL. For example:

```
https://docs.predicthq.com/api/events/search-events.md
```

A full index of all documentation pages is available at [llms.txt documentation index](https://docs.predicthq.com/llms.txt).

## Grounding

New to grounding? [Grounding with PredictHQ](https://docs.predicthq.com/ai/grounding-with-predicthq) covers what grounding is, how it reduces AI hallucinations, and the two architectures - retrieval inside your environment or on demand via MCP.

For the assistant request flow and how the APIs map to scope, relevance, usability, and trust, see [Using PredictHQ with AI assistants](https://docs.predicthq.com/ai/grounding-with-predicthq#using-predicthq-with-ai-assistants).


# Grounding with PredictHQ

What grounding is, how RAG relates to it, how grounding reduces AI hallucinations, and how to ground LLMs and agents in verified real-world event data - in your environment or on demand via MCP.

Grounding is giving an AI model facts it does not hold, at the moment it answers, so it responds from what is true instead of what it guesses. Retrieval-augmented generation (RAG) is the most common technique for grounding. Grounding with PredictHQ supplies the verified real-world context your LLMs, AI assistants, and agents lack: the events, holidays, and demand signals that shape the physical world their decisions run in.

## Why LLMs hallucinate about the real world

An LLM's knowledge is frozen at training time and thin on location-specific detail, so questions like "why are prices elevated in Austin this weekend?" or "what will affect store traffic next month?" sit outside what any model can know from its weights. Asked anyway, a model produces a fluent, plausible answer - generic seasonality, a guessed event, an invented explanation. That is an AI hallucination, and in pricing, staffing, and inventory decisions it carries real cost.

Grounding closes the gap at answer time. The model retrieves verified, location-specific, time-bound facts and reasons from them. With PredictHQ context, the answer names the conference and the concert landing that weekend and quantifies their expected impact, instead of gesturing at "increased demand." PredictHQ does not compete with LLMs - it completes them.

## Grounding, RAG, and fine-tuning

These three are often conflated. They solve different problems:

|                 | What it is                                                                                                                             | When it happens   | What changes                       |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------------------------------- |
| **Grounding**   | Supplying external facts to a model at answer time                                                                                     | Every inference   | The context the model reasons from |
| **RAG**         | A technique for grounding: retrieve relevant content from a prepared corpus (typically a vector store) and add it to the model's input | Every inference   | The context the model reasons from |
| **Fine-tuning** | Additional training that adjusts a model's weights on domain data                                                                      | Before deployment | The model itself                   |

Grounding is the outcome; RAG is one way to achieve it. Tool calling, where an agent queries an API at answer time, achieves the same outcome and suits live data better than embedding static documents. Fine-tuning is not an alternative: real-world context changes daily, and facts baked into weights are stale on arrival. Ground for facts, fine-tune for behavior.

## Two grounding architectures

Grounding with PredictHQ delivers verified real-world context two ways. Most deployments choose one, and the choice is mostly a governance and maintenance question. The distinguishing question: at the instant the model answers, does the context come from your store or from ours?

### Provisioned grounding - retrieval inside your environment

PredictHQ delivers verified event context into your environment (Snowflake, AWS Data Exchange, SFTP, or API sync) and your AI systems retrieve from a store you govern. Choose this when data residency, access control, or retrieval scale matter.

The flow works like this:

```mermaid
sequenceDiagram
    participant User
    participant Agent as Your AI agent (LLM)
    participant Store as Your context store
    participant PHQ as PredictHQ
    loop Kept verified and current
        PHQ->>Store: Verified, demand-relevant context - delivered and refreshed
    end
    User->>Agent: How should we staff the downtown store next week?
    Agent->>Agent: Decides it needs real-world context
    Agent->>Store: Retrieve relevant context for the downtown store, next 7 days
    Store-->>Agent: Verified context, served from your own store
    Agent->>Agent: Synthesizes the answer using the context
    Agent-->>User: Grounded answer, events cited
    Note over Agent,Store: The answer path stays inside your environment
```

Learn more:

* [Provisioned grounding: retrieval inside your environment](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding) - the reference architecture

### On-demand grounding - query at answer time

Your agents query the [PredictHQ MCP server](https://docs.predicthq.com/ai/mcp) live at decision time and hold no copy of anything. Choose this when speed matters - there is no integration to scope and nothing to wait on from your platform team or roadmap, so an agent can be querying the same day - or when zero pipeline maintenance suits a stack that already speaks tool calling.

The flow works like this:

```mermaid
sequenceDiagram
    participant User
    participant Agent as Your AI agent (LLM)
    participant MCP as PredictHQ MCP server
    User->>Agent: How should we staff the downtown store next week?
    Agent->>Agent: Decides it needs real-world context
    Agent->>MCP: Query relevant context for the downtown store, next 7 days
    MCP-->>Agent: Verified, relevance-ranked context - events, features, forecasts
    Agent->>Agent: Synthesizes the answer using the context
    Agent-->>User: Grounded answer, events cited
    Note over Agent,MCP: Nothing stored - every answer uses context current at that moment
```

Learn more:

* [PredictHQ MCP in agentic workflows](https://docs.predicthq.com/ai/predicthq-mcp-in-agentic-workflows) - reference workflows

## Using PredictHQ with AI assistants

Whichever architecture you choose, the request flow an AI assistant follows is the same:

1. A user asks a question or requests a forecast.
2. The assistant determines that external context is required.
3. The assistant retrieves PredictHQ context for a specified location and time range - from your store (provisioned) or via MCP (on-demand).
4. Your store or the MCP server returns structured context.
5. The assistant incorporates that context into its reasoning or response.

PredictHQ APIs are stateless and deterministic - the same request always returns the same result - which suits inference-time use inside AI systems.

AI systems consuming real-world context face the same structural challenges described in [Event-driven demand](https://docs.predicthq.com/getting-started/core-concepts/event-driven-demand), and the APIs map directly to them:

* **Scope** - [Predicted Impact Area](https://docs.predicthq.com/api/impact-area/get-impact-area) defines where events matter for a location.
* **Relevance** - [Beam](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam) calibrates which events materially impact demand, using historical demand data.
* **Usability** - the [Features API](https://docs.predicthq.com/api/features/get-features) converts events into structured, model-ready signals.
* **Trust** - the [Events API](https://docs.predicthq.com/api/events/search-events) provides verifiable event records that can be surfaced in explanations.

This separation lets an assistant retrieve either raw event context or calibrated signals, depending on the workflow. For worked examples, see the [provisioned grounding workflows](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding) and [agentic workflows](https://docs.predicthq.com/ai/predicthq-mcp-in-agentic-workflows).

## How grounding reduces AI hallucinations

A hallucination is a confident, plausible answer invented where the model lacks facts. Grounding attacks the cause: the model no longer has to invent, because the facts are in front of it. Three properties of the retrieved context determine how much hallucination it removes:

* **Verified** - the context must be true. PredictHQ continuously verifies, deduplicates, and enriches its events. Grounding in unverified content replaces invented errors with retrieved ones.
* **Specific** - the context must match the question's location and time window. PredictHQ context is location and date scoped, and [Beam](https://docs.predicthq.com/getting-started/core-concepts/what-is-beam) calibrates it to the events that actually drive demand at each location, so retrieval returns relevant signal rather than a wall of nearby noise.
* **Current** - real-world context changes daily. Events are announced, canceled, and revised inside any decision window, which is why grounding retrieves at answer time rather than relying on what a model absorbed in training.

Grounded answers are also explainable: every claim traces back to a specific verified event, which is what makes the answer auditable and defensible - and trust is the bottleneck in AI adoption.

## Grounding is not training

Training improves a model before it runs. Grounding supplies verified context while it runs. The two never mix: you can ground a frozen foundation model without any training rights or retraining, and a model trained on [PredictHQ features](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use) still benefits from grounding when its outputs need explaining. Many production deployments run both side by side.

## Frequently asked questions

### What is grounding in AI?

Grounding is supplying an AI model with external facts at the moment it answers, so it reasons from what is true instead of what it guesses. It reduces hallucinations without changing the model itself - and it only works as well as the facts are trustworthy, which is why verified context matters.

### Is grounding the same as RAG?

No. Grounding is the outcome; retrieval-augmented generation (RAG) is the most common technique for achieving it. Tool calling, where an agent queries an API such as the PredictHQ MCP server at answer time, is grounding that isn't classically RAG.

### How do I reduce LLM hallucinations about real-world demand?

Ground the model in verified, location-specific, current event context. Retrieve from a PredictHQ-fed store in your own environment (provisioned grounding) or query the PredictHQ MCP server on demand (on-demand grounding), and scope retrieval with Beam so the model sees relevant signal.

### Do I need to retrain my model to ground it?

No. Grounding happens at inference time and never touches model weights. It works with any model, including ones you have no training rights to.

### Should I use provisioned or on-demand grounding?

It's mostly a governance and maintenance question. If context must live inside your own trust boundary, or retrieval volume is high, run provisioned grounding over a store you govern. If you'd rather maintain nothing, or want to be querying today without waiting on a platform roadmap, use the MCP server. Some deployments use both.

### Can I use PredictHQ for training and grounding at the same time?

Yes, and the two don't interact: training uses event features to improve your model before it runs, grounding supplies verified context while it runs. See [How to use PredictHQ](https://docs.predicthq.com/getting-started/how-to-use-predicthq).

## Next steps

Continue with these pages:

* [Provisioned grounding: retrieval inside your environment](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding) - the reference architecture
* [MCP server](https://docs.predicthq.com/ai/mcp) - set up the MCP server


# MCP server

Connect AI agents to verified real-world event context on demand. On-demand grounding for LLMs via the Model Context Protocol - no data pipeline to maintain.

The PredictHQ MCP server connects AI assistants and agent-based systems directly to PredictHQ's APIs using the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) - an open standard for giving AI systems access to external tools and data at inference time.

This is the **on-demand grounding** path of Grounding with PredictHQ: your agents retrieve verified real-world context at the moment they answer, and hold no copy of anything. Once connected, your AI assistant can search events, retrieve demand intelligence, and access PredictHQ's full API surface through natural language.

MCP is the grounding path, not the bulk path. For training-scale feature retrieval, use the [Features API](https://docs.predicthq.com/api/features/get-features). To retrieve from a verified event store inside your own environment instead, see [provisioned grounding](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding).

## How it works

Your agent decides per question whether it needs real-world context, writes its own query, and answers from what comes back:

```mermaid
sequenceDiagram
    participant User
    participant Agent as Your AI agent (LLM)
    participant MCP as PredictHQ MCP server
    User->>Agent: How should we staff the downtown store next week?
    Agent->>Agent: Decides it needs real-world context
    Agent->>MCP: Query relevant context for the downtown store, next 7 days
    MCP-->>Agent: Verified, relevance-ranked context - events, features, forecasts
    Agent->>Agent: Synthesizes the answer using the context
    Agent-->>User: Grounded answer, events cited
    Note over Agent,MCP: Nothing stored - every answer uses context current at that moment
```

## Server details

<table><thead><tr><th width="303.16796875"></th><th></th></tr></thead><tbody><tr><td><strong>MCP Server URL</strong></td><td><code>https://mcp.predicthq.com/v1/mcp</code></td></tr><tr><td><strong>Transport</strong></td><td>Streamable HTTP</td></tr><tr><td><strong>Authentication</strong></td><td>OAuth or Bearer token (API key)</td></tr></tbody></table>

## Authentication

The MCP server supports two authentication methods.

**OAuth** - when you connect using a supported client, the client redirects you to PredictHQ to authorize access. The client stores no credentials in its configuration. Best suited for interactive use and multi-user environments.

**Bearer token** - pass your PredictHQ API key in the `Authorization: Bearer $API_TOKEN` header. Well-suited for agent and automation workflows where interactive login is not practical, or for clients that do not support OAuth. You [can create an API key in the PredictHQ WebApp](https://docs.predicthq.com/getting-started/api-quickstart).

## Available tools

The MCP server exposes tools across the full PredictHQ API surface:

* **Events** - search and count events
* **Broadcasts** - search and count live TV broadcasts
* **Features** - retrieve aggregated ML-ready demand intelligence features
* **Saved Locations** - create and manage locations, retrieve insight events, opening hours, and closures
* **Beam** - create and manage Analyses and Analysis Groups, upload demand data, and retrieve Feature Importance and correlation results
* **Forecasts** - create and manage forecast models, upload demand data, train models, and retrieve forecasts with explainability
* **Predicted Impact Area** - get Predicted Impact Area by location and industry
* **Places & Geocoding** - search places, look up place hierarchies, and geocode addresses
* **Tech Docs** - search PredictHQ's technical documentation and retrieve individual pages, covering API references, integration guides, tutorials, and conceptual content

## Access & subscription

Access to the MCP server is subject to your PredictHQ subscription. The MCP also enforces the same data access controls as the REST API - if your plan covers a specific set of locations or event categories, those same limits apply when using MCP.

If you don't yet have access to the MCP server, contact your PredictHQ account manager.

## Connect your AI client

### Claude (claude.ai)

PredictHQ's MCP is listed in the [Claude Connectors Directory](https://claude.ai/directory/connectors/predicthq). To set it up:

1. Open the [PredictHQ connector listing link](https://claude.ai/directory/connectors/predicthq) and select **Connect**.
2. To authenticate with your PredictHQ account, follow the OAuth flow.

Once connected, PredictHQ tools are available in any Claude conversation.

For more information, see [Claude's connector directory documentation](https://claude.com/docs/connectors/directory).

### Claude Code

Claude Code supports MCP via the CLI.

To connect Claude Code to the PredictHQ MCP server:

1. Run the following command:

   ```bash
   claude mcp add --transport http predicthq https://mcp.predicthq.com/v1/mcp
   ```
2. Inside a Claude Code session, run `/mcp` and follow the OAuth flow.

To use a Bearer token instead:

```bash
claude mcp add --transport http predicthq https://mcp.predicthq.com/v1/mcp \
  --header "Authorization: Bearer $API_TOKEN"
```

For full instructions, see [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).

### ChatGPT

ChatGPT supports remote MCP servers via Connectors. There are two ways to set this up depending on your plan.

**Individual setup**

To set up the connector:

1. Under **Settings > Advanced Settings**, enable **Developer Mode**.
2. Under **Settings > Connectors**, click **Create**.

**Workspace-wide setup**

If you're a workspace admin:

1. In **Workspace Settings > Permissions & Roles > Connected Data**, enable **Developer Mode**.
2. In **Workspace Settings > Connectors**, create a connector.
3. Publish the connector for the whole organization. Once published, the connector is available to all users in the workspace without any individual setup.

**Adding the PredictHQ connector:**

1. In **Settings** or **Workspace Settings**, depending on your plan, go to **Connectors > Create**.
2. Enter a name (e.g. `PredictHQ`) and optionally a description.
3. Enter the **MCP Server URL**: `https://mcp.predicthq.com/v1/mcp`
4. Select your authentication method:
   * **OAuth** - to authenticate with your PredictHQ account, follow the login flow.
   * **Access token / API key** - select **Bearer** as the scheme and enter your PredictHQ API key.

**To use it in a conversation:**

In the chat field:

1. Click **+**.
2. Click **More**.
3. Select **PredictHQ**.

**Note:** The exact steps may vary depending on your plan and workspace configuration. If the earlier steps don't match what you see, refer to [OpenAI's connector documentation](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt) for the latest instructions.

### Other clients

The PredictHQ MCP server works with any MCP-compatible client that supports Streamable HTTP transport, including Cursor, Windsurf, VS Code (GitHub Copilot), Zed, Postman, and others.

Use the following details when configuring your client:

* **Server URL:** `https://mcp.predicthq.com/v1/mcp`
* **Transport:** Streamable HTTP
* **Authentication:** OAuth, or Bearer token via `Authorization: Bearer $API_TOKEN` header

Refer to your client's documentation for specific configuration steps.

## Next steps

Continue with these pages:

* [Grounding with PredictHQ](https://docs.predicthq.com/ai/grounding-with-predicthq) - what grounding is and how PredictHQ fits into AI and agent workflows
* [PredictHQ MCP in agentic workflows](https://docs.predicthq.com/ai/predicthq-mcp-in-agentic-workflows) - use the MCP in autonomous and multi-agent workflows, where agents call PredictHQ for real-world context and explainability at decision time
* [API quickstart](https://docs.predicthq.com/getting-started/api-quickstart) - create an API key for Bearer token authentication


# PredictHQ MCP in agentic workflows

Reference architectures for autonomous agents that query the PredictHQ MCP server for verified demand context at decision time.

The PredictHQ MCP server connects AI agents directly to real-world context at decision time. It's commonly used interactively, through Claude, ChatGPT, or another assistant. It's equally suited to autonomous agentic workflows, where an agent, or a system of agents, works toward a goal and calls PredictHQ for the real-world context it needs to make good decisions along the way.

## The agentic pattern

In an agentic workflow, a goal is defined, such as optimizing inventory, setting pricing, or scheduling staff. The agent works toward that goal, determining what information it needs, calling the tools required to get it, and acting on the result.

PredictHQ is one of those tools. The agent calls it via MCP whenever a decision depends on what's happening in the real world: understanding the drivers behind a forecast, gauging upcoming demand pressure across a network of locations, or checking whether real-world conditions support a pricing move. The agent gets verified, structured context at the moment the decision is made, not a retrospective report it has to interpret.

The same pattern holds in multi-agent systems. An orchestrator coordinating specialized agents, or a team of agents collaborating toward a shared goal, can treat PredictHQ as a shared source of real-world context. Whichever agent owns the decision that depends on real-world conditions is the one that reaches for it, and it returns the same verified, deterministic context regardless of which agent makes the call.

## Why PredictHQ fits agentic workflows

PredictHQ is the real-world context platform that powers enterprise AI decisions. Several properties make it well-suited to autonomous agent loops.

**Demand intelligence, not a data dump.** PredictHQ explains more than 60 percent of real-world demand variability. Agents receive calibrated demand signals they can act on directly, not a raw list of events they have to make sense of.

**Explainable decisions.** Every signal traces back to the specific real-world activity behind it. An agent can see why demand is moving, act with confidence, and justify the decision it made in terms of observable real-world drivers.

**Deterministic and stateless.** The same request always returns the same result. Agents can rely on consistent, predictable responses without managing state between calls.

**Full workflow coverage.** A single MCP connection gives an agent the complete PredictHQ workflow, from location setup and demand calibration through to model-ready features and demand forecasts, with no separate integration per API.

## Calibration comes first

PredictHQ's value in an agent loop comes from calibrated demand intelligence, which depends on two things being in place for each location.

**Saved Locations** define geographic scope. Create each location with an `origin_geojson` point and an `industry`, and PredictHQ automatically calculates a Predicted Impact Area calibrated to that location. Do not use a hardcoded radius.

**Beam** identifies which real-world activity actually drives demand at each location, using historical demand data. Beam is not optional. Without it, category selection is guesswork and the demand signals an agent acts on are weaker for it. Run one Beam Analysis per location, and refresh both Saved Locations and Beam at least monthly so calibration tracks PredictHQ's latest models.

An autonomous agent can own this end to end as part of its normal flow. Before querying a location, it checks whether a Saved Location and Beam Analysis already exist, creates them if not, and refreshes them if they are more than a month old, then proceeds to query calibrated demand intelligence. There is no separate setup step a human has to run first. It is ordinary conditional logic inside the agent.

When calling the Features API, always pass `beam.analysis_id`. This applies the correct location boundary, event relevance, and rank thresholds automatically, and returns model-ready features. Do not specify individual feature names alongside it, and never use raw event counts as model inputs.

## The decision loop

The calibration check is ordinary conditional logic, not a separate setup step. Put together, an agent's use of PredictHQ within its flow looks like this:

```mermaid
flowchart TD
    A[Agent working toward a goal] --> B{Decision depends on<br/>real-world context?}
    B -->|No| A
    B -->|Yes| C{Location calibrated<br/>and fresh?}
    C -->|No or stale| D[Create or refresh<br/>Saved Location and Beam Analysis]
    D --> E[Query PredictHQ via MCP:<br/>calibrated demand intelligence<br/>and explainability]
    C -->|Yes| E
    E --> F[Reason over the<br/>real-world drivers]
    F --> G[Make the decision with confidence:<br/>pricing, staffing, inventory,<br/>with a real-world rationale]
    G --> A
```

## Example workflows

These examples assume a demand forecast is already in place, ideally one already enriched with PredictHQ context. The agent's job is to act on that forecast, and it uses PredictHQ's real-world context and explainability to make more confident, defensible decisions. Where a location is not yet calibrated, the agent creates or refreshes its Saved Location and Beam Analysis first, as described earlier.

### Revenue management

A revenue management agent works across a portfolio of hotel properties. A property's forecast shows elevated demand next weekend. Rather than acting on the number alone, the agent pulls the real-world context behind it and finds a major conference and a high-attendance concert over the same dates. Because the drivers are large, scheduled, and high-confidence, it raises rate and records the reason. Where an elevated forecast has no clear real-world driver, it can treat the signal as less certain and hold.

Tools: `forecasts_api_get_forecast` (with `phq_explainability`), `events_api_list_events` (with `beam.analysis_id`), `features_api_get_features` (with `beam.analysis_id`)

### Workforce scheduling

A workforce scheduling agent sets rosters across hundreds of locations. Several stores show a midweek demand bump. The agent pulls the drivers and sees a mix of school holidays and a regional sports event, letting it distinguish a short, event-driven spike from a sustained shift. It staffs each location accordingly and gives managers a clear, real-world rationale for the change.

Tools: `forecasts_api_get_forecast` (with `phq_explainability`), `saved_locations_api_list_saved_location_insight_events`, `events_api_list_events` (with `beam.analysis_id`)

### Demand planning

A demand planning agent manages replenishment across a retail network. A forecast spike appears in part of the network. The agent pulls the real-world context and finds it concentrated around specific high-attendance events in a few catchments. It pre-positions inventory where a durable real-world driver justifies it and holds where the spike has no clear cause, avoiding both stockouts and over-ordering.

Tools: `features_api_get_features` (with `beam.analysis_id`), `events_api_list_events` (with `beam.analysis_id`), `forecasts_api_get_forecast` (with `phq_explainability`)

## Setting up for agentic use

### Connecting

For agents running autonomously, use Bearer token authentication: you configure tokens at agent setup time, so they need no interactive login flow, which suits headless and scheduled workflows. OAuth remains available and is a good fit for interactive, multi-user contexts where a person authenticates at connection time.

The server URL, transport, and per-client setup are documented in the [MCP server](https://docs.predicthq.com/ai/mcp) reference, and you can [create an API token](https://docs.predicthq.com/api/overview/authenticating) for Bearer authentication.

## Tool selection for agents

The MCP server exposes \~55 tools across the full PredictHQ API surface. Map them to the workflow rather than reaching for any single tool in isolation.

**Managing calibration** (the agent creates or refreshes these as needed):

* `saved_locations_api_create_saved_location` sets up a location with an automatically calculated Predicted Impact Area. Always set `industry`.
* `beam_api_create_analysis` and `beam_api_upload_analysis_demand` calibrate which real-world activity drives demand at that location.

**Querying demand intelligence and explainability:**

* `features_api_get_features` is the primary tool for demand intelligence. To get calibrated, model-ready time-series features ready to feed into a decision or model, call it with `beam.analysis_id`.
* `forecasts_api_get_forecast` returns ready-made, event-driven demand forecasts for agents that want accurate forecasts without building their own model. To get the top real-world drivers behind each forecasted date, pass `phq_explainability`. The system applies Beam automatically.
* `events_api_list_events` retrieves the specific real-world activity behind a demand signal, so an agent can explain or validate a decision. Use it with `beam.analysis_id`.
* `saved_locations_api_list_saved_location_insight_events` surfaces the highest-impact upcoming drivers for a known location.
* `saved_locations_api_get_saved_location` returns a location's summary insights, including Predicted Event Spend and Predicted Attendance for the next 90 days.

### Next steps

These pages cover related setup and concepts:

* [MCP server](https://docs.predicthq.com/ai/mcp) - connect your agent to PredictHQ via MCP
* [Agent skills](https://docs.predicthq.com/ai/agent-skills) - install PredictHQ's integration best practices directly into your coding agent
* [API quickstart](https://docs.predicthq.com/getting-started/api-quickstart) - create an API token for bearer token authentication
* [Grounding with PredictHQ](https://docs.predicthq.com/ai/grounding-with-predicthq) - grounding concepts and architectural patterns for AI systems


# Agent skills

Install PredictHQ agent skills to give AI coding assistants best-practice integration knowledge - recommended workflow, API selection, and Beam guidance, which your agent applies automatically while y

Agent skills are packaged integration knowledge for AI coding assistants. Once you install it, your agent applies the PredictHQ skill automatically whenever it works on a PredictHQ integration - no prompting, no pasting docs into context.

The skill encodes the same guidance these docs recommend, so code written with it follows the proven path instead of a plausible-looking wrong one:

* The recommended integration workflow - Saved Locations and Predicted Impact Area first, then Beam, then features
* API selection - Features API for model inputs, Events API for explainability, and when the Forecasts API is the better fit
* Beam best practices - one Analysis per location, `beam.analysis_id` on every downstream call, monthly refresh
* Common mistakes to avoid - manual event aggregation, fixed radii, skipping Beam

## Install

To install the skills, run:

```bash
npx skills add predicthq/agent-skills
```

Works with Claude Code, Cursor, Gemini CLI, GitHub Copilot, and other compatible agents. The skills are open source on [GitHub](https://github.com/predicthq/agent-skills).

## Skills and the PredictHQ MCP server

The two are complementary and often installed together. Agent skills teach your coding assistant how to *build* the integration correctly. The [MCP server](https://docs.predicthq.com/ai/mcp) gives assistants and agents live access to PredictHQ data - for exploring while you build, and for [grounding](https://docs.predicthq.com/ai/grounding-with-predicthq) AI systems in production.

## Next steps

To keep building, see these pages:

* [Build with AI](https://docs.predicthq.com/ai/build-with-ai) - all the tools for building with AI assistants
* [MCP server](https://docs.predicthq.com/ai/mcp) - live API access from any MCP-compatible client
* [Which API should I use?](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use) - the guidance the skill applies, in human-readable form


# Bolt

An AI-native notebook inside the PredictHQ WebApp. Bolt answers from live PredictHQ API data—a working example of a grounded agent.

Bolt combines a conversational AI interface with a persistent notebook of interactive cards. Ask questions in natural language, and Bolt retrieves real data from PredictHQ's APIs, guides you toward the right products for your situation, and surfaces results as cards you can explore, share, and take directly into your integration.

Bolt is also a working example of **grounding**: it answers from verified, live PredictHQ data retrieved at the moment you ask—not from what a model guesses. The same capability is available to your own AI stack through the [PredictHQ MCP server](https://docs.predicthq.com/ai/mcp).

{% hint style="success" %}
Bolt is in beta - use the 👍 / 👎 feedback buttons in the interface to help us improve it
{% endhint %}

## What you can do

**Explore PredictHQ data through conversation.** Ask about events, demand signals, locations, and forecast inputs in plain language. Bolt queries PredictHQ's APIs on your behalf and returns real results - not synthetic examples.

**Get guided to the right solution.** Bolt understands PredictHQ's products and how they fit together. Rather than returning a generic answer, it steers you toward the right approach for your use case - running a Beam Analysis before querying features, using Predicted Impact Area rather than a fixed radius, and following the integration patterns that produce the best outcomes.

**Build with the results.** Every card in the notebook includes a production-ready API code snippet alongside the visualization and raw data. When you find something useful, the code to reproduce it is already there.

**Work iteratively.** Cards persist across the session and accumulate in the notebook as the conversation progresses. Follow up, refine, and drill down - the notebook becomes an artifact you can revisit and share with your team.

## How it works

Bolt's interface has two panels that work together.

The **chat panel** is where you type questions and see responses. Bolt can execute multi-step workflows - creating a Saved Location, running a Beam Analysis, and returning demand-calibrated features - from a single conversational exchange.

The **notebook panel** is where results appear as cards. Each card has three tabs:

* **Preview** - an interactive chart or map of the results
* **Code** - a production-ready API snippet you can take directly into your integration
* **Data** - the raw API response

Bolt manages cards as the conversation evolves - it collapses cards that are no longer relevant, while cards you pin stay in view. The notebook is the persistent artifact; the chat is how you drive it.

## PredictHQ best practices built in

PredictHQ configures Bolt with its integration best practices. It follows the recommended workflow automatically:

* Creates Saved Locations before running Beam Analyses
* Uses Predicted Impact Area rather than fixed radii
* Runs Beam to identify which events drive demand at each location before retrieving features
* Uses the Features API for demand signals and the Events API for drill-down and explainability
* Applies industry context to calibrate results

This means Bolt produces better results out of the box than querying the APIs directly without guidance - and helps you understand why each step matters as you work through it.

## Getting started

Bolt is available inside the [PredictHQ WebApp](https://control.predicthq.com/bolt). In the navigation, select **Bolt** to open the interface.

Start by describing your use case or location - for example:

* *"What events are impacting demand at my hotel in Chicago next month?"*
* *"Set up a Beam Analysis for our restaurant in Sydney"*
* *"Show me demand signals for a retail location in London"*

Bolt guides you from there.

## Next steps

Continue with these pages:

* [MCP server](https://docs.predicthq.com/ai/mcp) - connect Bolt's capabilities to your own AI assistant or coding environment
* [Agent skills](https://docs.predicthq.com/ai/agent-skills) - install PredictHQ best practices into your AI coding agent
* [Integration guides](https://docs.predicthq.com/integrations/integration-guides) - move from exploration to a production integration


# Integration guides

How to put PredictHQ into production.

Start with the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) - the reference architecture for forecasting and decision systems, from location setup through features, events, and explainability. Grounding AI systems inside your environment extends the same architecture: see [Provisioned grounding](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding). [Keep data updated via API](https://docs.predicthq.com/integrations/integration-guides/keep-data-updated-via-api) and [Loading event data into a data warehouse](https://docs.predicthq.com/integrations/integration-guides/loading-event-data-into-a-data-warehouse) cover the do-it-yourself path when managed delivery isn't an option, and [Integrate with Loop Links](https://docs.predicthq.com/integrations/integration-guides/integrate-with-loop-links) lets frontline teams feed event corrections back into the data.

For which path to build at all, see [How to use PredictHQ](https://docs.predicthq.com/getting-started/how-to-use-predicthq).


# Standard integration pattern

This page describes the recommended architecture for integrating PredictHQ into a production system. It applies to most demand forecasting and operational use cases - staffing, inventory, pricing, scheduling, and similar applications where event-driven features feed into a model or decision system.

## Overview

A PredictHQ integration has four logical components on your side:

1. **Location & Beam Management** creates and maintains Saved Locations and Beam Analyses per location, refreshed monthly
2. **ML Features Management** - fetches pre-built ML features per location using the Beam Analysis, refreshed daily or weekly
3. **Events Management** - fetches relevant events per location for explainability and operational context, refreshed daily or weekly
4. **Forecasting & Decision System** - consumes features for model training and inference and surfaces events alongside results for explainability

We recommend working with your PredictHQ Solutions Engineer to scope the right architecture for your use case before implementation

The key principle across all of these: **store a local copy and query that, rather than making live API calls at inference time.** This removes API latency from the critical path and gives you full control over refresh cadence. It applies to forecasting pipelines and training-scale feature retrieval - AI agents that query for context on demand are the deliberate exception, covered in [Grounding paths for AI systems](#grounding-paths-for-ai-systems).

## Architecture diagram

The following diagram is PredictHQ's reference architecture for a standard production integration. It shows the recommended system design for ingesting event-driven ML features and events into a forecasting or decision-making pipeline, covering location setup, Beam Analysis, feature and event management, modeling, and end-user explainability.

Use this as the starting point when designing your integration - your Solutions Engineer can help tailor it to your specific locations, industry, and forecasting setup. The architecture applies across industries and use cases - staffing, inventory, pricing, scheduling, and similar demand forecasting applications. Variations such as bulk data delivery via Snowflake, AWS Data Exchange, or SFTP are noted where applicable in the following diagram:

```mermaid
---
config:
  layout: dagre
---
flowchart TB
 subgraph PredictHQ["**PredictHQ Platform**"]
        Saved_Locations_API["Saved Locations API"]
        Beam_API["Beam API"]
        Features_API["Features API<br>(or Snowflake, ADX, SFTP)"]
        Events_API["Events API<br>(or Snowflake, ADX, SFTP)"]
  end
 subgraph Customer["**Customer Environment**"]
        Manage_Locations["**Manage Saved Locations &amp; Beam**<br>refresh monthly"]
        Business_Location["Entry point: Business Location"]
        Location_Store[("Locations")]
        Manage_ML_Features["**Manage ML Features**<br>refresh daily / weekly"]
        Manage_Events["**Manage Events**<br>refresh daily / weekly"]
        ML_Features[("ML Features")]
        Forecasting_System["**Forecasting &amp; Modeling**<br>Train on historic<br>Run inference on future"]
        Forecasts[("Forecast Results")]
        Decision_System["**Decision System**<br>Display results or<br>automated decisions"]
        Events[("Events")]
        End_User(["End User"])
  end
    Business_Location --> Manage_Locations
    Manage_Locations -- origin_geojson --> Saved_Locations_API
    Saved_Locations_API -- location_id + Predicted Impact Area --> Manage_Locations
    Manage_Locations -- location_id --> Beam_API
    Beam_API -- analysis_id + Feature Importance --> Manage_Locations
    Manage_Locations --> Location_Store
    Location_Store --> Manage_ML_Features & Manage_Events
    Manage_ML_Features -- analysis_id --> Features_API
    Features_API -- ML features --> Manage_ML_Features
    Manage_ML_Features --> ML_Features
    Manage_Events -- analysis_id --> Events_API
    Events_API -- events --> Manage_Events
    Manage_Events --> Events
    ML_Features --> Forecasting_System
    Forecasting_System --> Forecasts
    Forecasts --> Decision_System
    Events -- explainability --> Decision_System
    Decision_System --> End_User

    Business_Location@{ shape: lean-r}
    style Business_Location fill:#00D09E20
    style End_User fill:#CCE8F620
    style PredictHQ fill:#FF236420
```

## Component detail

### Location & Beam management

**Refresh: monthly**

For each business location:

1. To create a Saved Location, call the Saved Locations API with `origin_geojson` (a lat/lon Point). This also automatically calculates a Predicted Impact Area - an industry and geography-calibrated boundary that determines which events are in scope.
2. Store the returned `location_id`.
3. Create a Beam Analysis for the location using the `location_id` and your historical demand data. Beam identifies which event categories materially drive demand at that specific location.
4. Store the returned `analysis_id` and Feature Importance results (event categories and p-values).
5. **Monthly refresh:**
   1. Append new demand data to the existing Beam Analysis - do not delete and recreate it.
   2. Update your stored Feature Importance results with the latest output.

Saved Locations are also the only way to use polygon-based boundaries with PredictHQ APIs. You store a polygon once against the location and reference it by `location_id` across all subsequent calls.

### ML features management

**Refresh: daily or weekly or other, depending on model cadence**

For each location:

1. To retrieve pre-built ML features, call the Features API with the `analysis_id` from your Location Store.
2. In your local store, save the results.

The `analysis_id` automatically applies the correct location boundary, event category filters, rank thresholds, and Predicted Impact Patterns for that location - no manual configuration needed. Pull from your local store at training and inference time, not directly from the API.

**Alternative delivery:** PredictHQ can deliver Features API output per Beam Analysis via Snowflake Private Share, AWS Data Exchange, or SFTP. Contact PredictHQ to discuss this option.

### Events management

**Refresh: daily or weekly**

For each location:

1. To retrieve the specific events driving demand, call the Events API with the `analysis_id`.
2. In your local store, save the results.

You use events for **explainability** - surfacing to end users or downstream systems which events are responsible for a forecast shift on a given day. This is distinct from the ML features used for modeling. Events give human-readable context to model outputs. The same store can also serve as the retrieval corpus for grounding AI systems in your environment - see [Grounding paths for AI systems](#grounding-paths-for-ai-systems).

**Alternative delivery:** PredictHQ can deliver events filtered by Beam Analysis or Saved Location via Snowflake Private Share, AWS Data Exchange, or SFTP. For most production use cases, this is the preferred approach over live Events API calls.

### Forecasting & decision system

The forecasting model pulls ML features from your local store - both historical (for training) and future (for inference). Event features represent demand signal - your model learns the relationship between event magnitude and demand impact at each location.

The decision or end-user system consumes:

* **Forecast results** from the modeling system
* **Events** from your local Events store, used to explain forecast anomalies or expected demand shifts to operators or end users

## Grounding paths for AI systems

This architecture also supports [grounding](https://docs.predicthq.com/getting-started/glossary#grounding) - supplying verified real-world context to LLMs and AI agents at the moment they answer, so they respond from facts instead of hallucinating. Grounding sits alongside the forecasting pipeline, not inside it: training improves your model before it runs, grounding supplies verified context while it runs, and the two never mix.

**Provisioned grounding** reuses this architecture as-is. The local Events store is the retrieval corpus: AI systems in your environment query it at answer time, your own access controls govern it, and your refresh cadence sets its freshness. Nothing new to build beyond a retrieval interface over a store you already maintain - see [Provisioned grounding: retrieval inside your environment](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding) for the reference architecture.

**On-demand grounding** is the deliberate exception to the store-locally principle. AI agents query the [PredictHQ MCP server](https://docs.predicthq.com/ai/mcp) live at decision time and hold no copy of anything. The latency trade-off that rules out live calls in a forecasting hot path is acceptable in an agent's tool-calling loop - and always-current context is the point. For more detail, see:

* [Grounding with PredictHQ](https://docs.predicthq.com/ai/grounding-with-predicthq)
* [PredictHQ MCP in agentic workflows](https://docs.predicthq.com/ai/predicthq-mcp-in-agentic-workflows)

## Refresh cadence summary

| Component       | Cadence              | Notes                                                                                                                                                                                                           |
| --------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Saved Locations | Monthly or as needed | Refresh monthly or if the location itself changes                                                                                                                                                               |
| Beam Analysis   | Monthly              | Append demand data to existing Analysis - do not recreate                                                                                                                                                       |
| ML Features     | Daily or weekly      | Align with model training / inference cycle. Future-dated values are revised continuously - new events are announced, attendance predictions update - so refresh ahead of each forecast run rather than caching |
| Events          | Daily or weekly      | Align with operational review cadence                                                                                                                                                                           |

***

### Key decisions

**Features API vs. Snowflake / ADX / SFTP** For smaller deployments or early integration, the Features API is the simplest path. For production at scale - particularly when feature freshness and API latency are concerns - talk to PredictHQ about bulk delivery options.

**One Beam Analysis per location** Event impact is location-specific. Do not reuse a single Beam Analysis across multiple locations. For fleet-scale deployments with many similar locations, see [Analysis Groups in Beam](https://docs.predicthq.com/api/beam/analysis-groups).


# Provisioned grounding: retrieval inside your environment

Reference architecture for provisioned grounding: retrieving verified PredictHQ event context inside your own environment at answer time, so your AI systems respond from facts they can cite.

Provisioned grounding gives your LLMs and agents verified real-world context from a store inside your own environment - your access controls govern it, it resides in your infrastructure, and your models retrieve from it at the moment they answer. It is the grounding architecture for teams where data residency, governance, or retrieval scale rule out live external calls.

This page is the reference architecture. If your agents can query externally and you want zero pipeline maintenance, use [on-demand grounding via the PredictHQ MCP server](https://docs.predicthq.com/ai/mcp) instead. For what grounding is and when to use it at all, see [Grounding with PredictHQ](https://docs.predicthq.com/ai/grounding-with-predicthq).

## Architecture

Provisioned grounding extends the [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern): the local event store that pattern maintains for explainability is the grounding corpus. If you already run that architecture, provisioned grounding adds a retrieval interface and a consumer - nothing else changes, as the following diagram shows:

```mermaid
flowchart TB
 subgraph PredictHQ["**PredictHQ Platform**"]
        Delivery["Managed delivery<br>Snowflake / ADX / SFTP / API sync"]
  end
 subgraph Customer["**Customer Environment**"]
        Store[("Event store<br>refreshed daily")]
        Retrieval["**Retrieval interface**<br>location + date + category filters<br>scoped by Beam Analysis"]
        AI["**LLM or agent**<br>assistant, copilot, or<br>autonomous workflow"]
        User(["User or downstream system"])
  end
    Delivery -- verified event context --> Store
    Store --> Retrieval
    AI -- question at answer time --> Retrieval
    Retrieval -- verified, scoped context --> AI
    AI -- grounded answer --> User

    style PredictHQ fill:#FF236420
    style User fill:#CCE8F620
```

The components:

1. **Delivery** - PredictHQ deploys verified event context into your environment via [Snowflake](https://docs.predicthq.com/integrations/third-party-integrations/snowflake), [AWS Data Exchange](https://docs.predicthq.com/integrations/third-party-integrations/aws-data-exchange), [SFTP](https://docs.predicthq.com/integrations/third-party-integrations/sftp), or [API sync](https://docs.predicthq.com/integrations/integration-guides/keep-data-updated-via-api). Managed delivery is preferred: no pipeline to build, and the store stays current without sync code.
2. **Event store** - the same store the Standard Integration Pattern maintains. Events are structured records (category, location, dates, Predicted Attendance, rank), so it lives naturally in the warehouse or lakehouse your AI stack already reads.
3. **Retrieval interface** - the query layer your AI systems call at answer time. Because events are structured, retrieval is structured too: filter by location, date window, and the event categories that matter, rather than embedding everything and hoping vector similarity finds the right concert.
4. **The model** - any LLM, assistant, or agent in your environment. It receives verified, scoped context in its input and answers from retrieved facts, not invented ones.

At answer time, the flow looks like this - the answer path stays inside your environment, and PredictHQ's only runtime role is keeping the store current:

```mermaid
sequenceDiagram
    participant User
    participant Agent as Your AI agent (LLM)
    participant Store as Your context store
    participant PHQ as PredictHQ
    loop Kept verified and current
        PHQ->>Store: Verified, demand-relevant context - delivered and refreshed
    end
    User->>Agent: How should we staff the downtown store next week?
    Agent->>Agent: Decides it needs real-world context
    Agent->>Store: Retrieve relevant context for the downtown store, next 7 days
    Store-->>Agent: Verified context, served from your own store
    Agent->>Agent: Synthesizes the answer using the context
    Agent-->>User: Grounded answer, events cited
```

## Retrieval design

Three decisions determine whether grounded answers are relevant or noisy:

* **Scope with Beam.** Retrieval should return the events that drive demand at the location in question, not every event nearby. Store each location's Beam `analysis_id` results (categories, rank thresholds) and apply them as retrieval filters - the same calibration your forecasting path uses. Without it, the model is grounded in noise.
* **Filter structurally first.** Location, date window, and category filters do the heavy lifting on structured event data. If you also embed event descriptions for semantic search, apply it after structural filtering, not instead of it.
* **Return records, not summaries.** Give the model the verified fields (title, category, dates, Predicted Attendance, venue) and let it reason. Pre-summarized context loses the specifics that make answers explainable, and every claim in a grounded answer should trace back to a specific event record.

## Freshness

Real-world context changes daily: events are announced, revised, canceled, and postponed inside any decision window. A grounding corpus that lags reality produces answers that are confidently out of date, which reads exactly like a hallucination to the person acting on it.

| Component                         | Cadence                                                                                                                                                               |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Event store                       | Daily refresh via managed delivery, or [API sync](https://docs.predicthq.com/integrations/integration-guides/keep-data-updated-via-api) using the `updated` parameter |
| Beam Analysis (retrieval scoping) | Monthly - append new demand data                                                                                                                                      |
| Retrieval                         | Live against the store at every answer - never cache retrieved context across questions                                                                               |

## Example workflows

**Forecast explanation.** An operator asks an assistant why demand is forecast to spike next Friday. The assistant retrieves that location's demand-driving events for the date window and answers with the specific festival and its Predicted Attendance - a claim anyone can verify against the record.

**Operational copilot.** A staffing copilot preparing next week's roster retrieves upcoming high-rank events for each store's location before recommending shift levels, and cites the events behind each recommendation.

**Customer-facing explanations.** A pricing platform explains rate changes to end users from the same store - provisioned grounding keeps the retrieval path inside the platform's own trust boundary, with no external call in the serving path.

## When to choose provisioned over on-demand grounding

| Choose provisioned grounding                                                   | Choose [on-demand grounding (MCP)](https://docs.predicthq.com/ai/mcp)       |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Data residency or compliance requires context inside your boundary             | Agents can call external tools                                              |
| Retrieval volume is high enough that per-query external calls don't make sense | Query volume is modest and bursty                                           |
| You already run the Standard Integration Pattern - the corpus exists           | You want nothing to build or maintain                                       |
| Your AI serving path can't take an external dependency                         | Always-current context matters more than residency                          |
| The integration has a place on your platform roadmap                           | You want to be querying today - no integration to scope, nothing to wait on |

Some deployments run both: provisioned grounding for the high-volume serving path, MCP for ad-hoc agent and analyst queries.

## Next steps

To continue:

* [Grounding with PredictHQ](https://docs.predicthq.com/ai/grounding-with-predicthq) - concepts and the two architectures
* [Standard integration pattern](https://docs.predicthq.com/integrations/integration-guides/standard-integration-pattern) - the architecture this extends
* [Receive data via Snowflake](https://docs.predicthq.com/integrations/third-party-integrations/snowflake) - the lowest-friction delivery path


# Keep data updated via API

Event information changes frequently. For example, a date changes, an event gets canceled, or ranking is updated. It’s important to keep your data set up to date.

{% hint style="success" %}
We highly recommend using Snowflake or ADX to keep your local event store up to date. Managed delivery removes all the complexity of implementing a sync system against the API and results in far higher accuracy with fewer issues. Keeping up to date via the API is much more complicated than via Snowflake or ADX.
{% endhint %}

Events change constantly: dates move, events are canceled or postponed, Predicted Attendance values are revised, and records are merged as duplicates or removed as spam. A stale local store degrades everything built on it - models score against outdated signals, and grounded AI systems answer from events that no longer exist. Keeping your store in sync is what keeps those outputs true.

Our records have an `updated` field which indicates the date/time the record was last updated.

{% hint style="info" %}
For example an event for a conference that starts on 1 April 2026 may originally be created in our system on 1 Jan 2026. Then the event’s details don’t change until the 5 Feb 2026 when the event is canceled. The event’s state field then changes to `deleted` and the `deleted_reason` changes to `cancelled`. The event’s updated field would show `2026-02-05T05:00:00Z` (for the cancellation change made to the event on 5 Feb 2026).
{% endhint %}

## High-level guide to keeping data updated

The best way to update your data store is to search for records that have changed since you last synced:

1. To find records that have been updated since your last fetch, use the `updated.*` parameters.
2. Make sure you’re fetching both `active` and `deleted` events e.g. `state=active,deleted`
   1. For the Broadcasts API, use `record_status=active,duplicate,deleted`
3. Ensure you won’t miss changes if records are updated while you’re fetching with `sort=-updated`
4. Sync every 24 hours, or more frequently for unscheduled events if needed.

The following example request in Python fetches updated events:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "updated.gte" : "2026-07-01",
        "updated.lte" : "2026-07-10",
        "state" : "active,deleted",
        "sort": "-updated",
        "limit": 500
    }
)

print(response.json())
```

{% hint style="success" %}
Note that you can use the [Features API](https://docs.predicthq.com/api/features/get-features) to directly get daily-level aggregations of the data instead of downloading large volumes of event data and keeping it up to date. The Features API provides pre-built features that save you from writing a lot of code to aggregate data and create features on your side.
{% endhint %}


# Loading event data into a data warehouse

Take PredictHQ API data and load it into a data warehouse, in this example, GCP BigQuery.

This guide outlines the process for integrating PredictHQ's Events data into your data lake. You may want to get data from our APIs and store it in your data lake. To support this, we have created this guide to help you with the integration process

We use Google Cloud Platform (GCP) as our primary example, but the methods for structuring the data table and making PredictHQ Events API calls can be applied to various data management systems. This guide assumes you have a basic understanding of GCP or similar data warehousing solutions and the necessary permissions to use them.

This guide covers Events API data only, loaded via the API - the do-it-yourself path. For production, [managed delivery](https://docs.predicthq.com/integrations/third-party-integrations) (Snowflake, ADX, or SFTP) keeps your store updated with nothing to build. And model features should come from the [Features API](https://docs.predicthq.com/api/features/get-features), not from aggregating warehouse events - see [Which API should I use?](https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use)

If you are using Snowflake or AWS Data Exchange (ADX) for your data lake PredictHQ integrates with those products. See [Receive data via Snowflake](https://docs.predicthq.com/integrations/third-party-integrations/snowflake) and [Receive data via AWS Data Exchange](https://docs.predicthq.com/integrations/third-party-integrations/aws-data-exchange) for details.

## Overview

This guide details the data structure of our Events API within a data warehouse environment and outlines two methodologies for creating an Events data table in GCP.

Throughout this guide, we will use the fictional example from our [Filtering Guide](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events), "Tom’s Pizzeria". This scenario will give us a practical illustration of the methods described and demonstrate how to tailor API queries to specific business needs. For an understanding of how we selected the parameters for this example, refer to the [Filtering Guide](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events).

**Requirements**:

* Access to PredictHQ Data
  * JSONL: Requires a PredictHQ account. [Sign up for a PredictHQ account](https://predicthq.com/signup) if you don’t already have one.
  * API: An [API Access Token](https://docs.predicthq.com/api/overview/authenticating) is necessary for accessing the data programmatically.
* GCP permissions:
  * Ensure you have "BigQuery Data Owner" and "BigQuery User" permissions over the BigQuery environment.
  * A GCP BigQuery Service Account and its corresponding JSON key are required.[ See the GCP documentation](https://cloud.google.com/iam/docs/service-account-overview) for details.

## Scenario: Tom’s Pizzeria

In this guide, we'll explore a hypothetical use case for “Tom’s Pizzeria”, a chain of restaurants with locations throughout the US headquartered in Seattle, Washington. Tom is interested in understanding how local events might influence his business operations and customer flow. Tom’s inventory system, website, and tools run off GCP. Tom wants to use event data in his staffing and inventory management systems to help anticipate the demand caused by events. He wants to show upcoming events near stores to his staff. To do this he needs to download events into his data lake.

For comprehensive details on selecting appropriate filters for this scenario, refer to our [Filtering Guide](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events). This guide will help us understand which events could impact Tom's business and how to configure our data queries accordingly. For our load into GCP, we want to bring through a larger number of events and then filter down to a specific pizzeria location using BigQuery once loaded. See [Querying the loaded data](#querying-the-loaded-data) section for more.

Tom's Data Parameters:

* **Attended Categories**: community, conferences, concerts, expos, festivals, performing-arts, sports.
* **Date Range**: Events active within the range June 1, 2024, to June 30, 2024.
* **PHQ Rank**: Events with a rank greater than 30 indicate a significant likelihood of impacting local traffic and attendance.
* **Event Status**: Both ‘active’ and ‘predicted’ events to ensure a comprehensive overview.
* **Location**: Bring through all of Seattle first, and Tom can filter for his locations once it’s in BigQuery using our [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area).

For the purposes of this guide, we have limited the example load to a single city for Tom to filter on. You can bring through as much data as you have access to or require when doing an actual load. We find with data warehouse customers they may pull down all data they have access to into their data warehouse and then query it for relevant locations and data from their applications.

## Data load methods

There are several methods available for integrating PredictHQ data with GCP BigQuery or other data warehouse solutions. This guide outlines two primary approaches, both compatible with each other’s data structure. Regardless of the method chosen for the initial data load, ongoing updates require API code.

**JSONL File Upload Method**: This method provides a straightforward, code-free approach to data upload, by exporting data from PredictHQ’s [WebApp](https://control.predicthq.com/search/events). We recommend using JSONL uploads for the initial population of your data lake, especially in cases where there is a substantial volume of data, such as multiple years of historical data. Manage subsequent updates through API calls to keep the data current.

**API connection method**: Connect to the PredictHQ Events API to download the latest data from the API into your data lake. This guide takes you through using the Python API connection method for GCP but similar steps would apply to other programming languages. Events data is dynamic with events changing all the time as events are canceled, postponed, shift location, or have other details change. Also, new events are being announced all the time. We recommend having a process that updates your data on a regular frequency, such as daily.

This guide will walk you through the initial data load, providing you with the tools and understanding necessary to create a robust connection to GCP. You'll learn how to structure your data effectively within your warehouse, setting the stage for potential automation and regular updates that you can implement as needed.

## Table data structure

Regardless of the method chosen for initial data creation and loading, the table structure remains consistent. This ensures that both methods are interchangeable, delivering data in a uniform format. The following table details the data structure:

| Field Name                          | Datatype  | Mode     |
| ----------------------------------- | --------- | -------- |
| id                                  | STRING    | REQUIRED |
| parent\_event                       | JSON      | NULLABLE |
| title                               | STRING    | NULLABLE |
| alternate\_titles                   | JSON      | NULLABLE |
| description                         | STRING    | NULLABLE |
| category                            | STRING    | NULLABLE |
| labels                              | JSON      | NULLABLE |
| phq\_labels                         | JSON      | NULLABLE |
| rank                                | INTEGER   | NULLABLE |
| local\_rank                         | INTEGER   | NULLABLE |
| phq\_attendance                     | INTEGER   | NULLABLE |
| entities                            | JSON      | NULLABLE |
| duration                            | INTEGER   | NULLABLE |
| start                               | TIMESTAMP | NULLABLE |
| start\_local                        | TIMESTAMP | NULLABLE |
| end                                 | TIMESTAMP | NULLABLE |
| end\_local                          | TIMESTAMP | NULLABLE |
| predicted\_end                      | TIMESTAMP | NULLABLE |
| predicted\_end\_local               | TIMESTAMP | NULLABLE |
| updated                             | TIMESTAMP | NULLABLE |
| first\_seen                         | TIMESTAMP | NULLABLE |
| timezone                            | STRING    | NULLABLE |
| location                            | JSON      | NULLABLE |
| geo                                 | JSON      | NULLABLE |
| scope                               | STRING    | NULLABLE |
| country                             | STRING    | NULLABLE |
| place\_hierarchies                  | JSON      | NULLABLE |
| state                               | STRING    | NULLABLE |
| private                             | BOOLEAN   | NULLABLE |
| impact\_patterns                    | JSON      | NULLABLE |
| predicted\_event\_spend             | INTEGER   | NULLABLE |
| predicted\_event\_spend\_industries | JSON      | NULLABLE |

## JSONL file upload method

We recommend this method for large data uploads, as it efficiently manages the transfer of large volumes of data better than direct API calls.

### Search Events in the WebApp and export JSONL

To locate and export the relevant event data into a JSONL file, we utilize the PredictHQ [WebApp Search](https://control.predicthq.com/search/events). This tool allows for precise querying of events based on specific criteria, ensuring that you retrieve only the most relevant information for your needs.

You can download everything you have access to, but most integrations are better served by scoping the export to the locations that matter - and production deployments by [managed delivery](https://docs.predicthq.com/integrations/third-party-integrations) rather than manual exports.

In the context of our example [Scenario](#scenario-toms-pizzeria) for Tom's Pizzeria, they would be downloading events for all of the US and then querying for specific locations. Many customers may bulk load all the data they have access to by exporting it all and then importing it into their data lake. In this example, we’ll download events only for Seattle.

To do that, we searched for Seattle in the WebApp for the relevant period, status, and attended categories.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FibNFfU3QLaqRFku6Udqa%2FCC%20Filters.png?alt=media&amp;token=a94cc896-6d37-4358-8304-fdb254a79652" alt="The WebApp Search page filtered to Seattle events, ready to export"><figcaption><p>WebApp Search for Seattle ready for Export</p></figcaption></figure>

To export the events:

1. In the WebApp Search, set your filters and run the search.
2. Click **Export**.
3. Choose the **JSONL** file format.

You can then upload the JSONL file directly to your BigQuery setup, as detailed in the [Create a table via JSONL upload](#create-a-table-via-jsonl-upload).

### Create a table via JSONL upload

To set up a BigQuery table with a JSONL file, you need the necessary permissions on GCP. Before beginning, ensure you are clear about which dataset will host the data. Here are the steps to create the table once you have found and highlighted the dataset in GCP BigQuery:

1. **Click Create table**: In the dataset you wish to create the table in, click the **hamburger menu**, and then select **Create table**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FqVnhZhTPHhoxYLqrWAWF%2FCreate%20Table.png?alt=media&amp;token=2bdfad20-f3f4-4329-bd99-d3b8e49e8296" alt="The BigQuery dataset menu open with the Create table option highlighted"><figcaption><p>Select destination dataset and use the hamburger menu to create table</p></figcaption></figure>

2. **Select the File Location**: Select the JSONL export that you have downloaded somewhere on your computer.
3. **Name the Table**: Give the table about to be created a name that suits

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Fn815pqxGKVv5bhpnCYSG%2Ftable%20upload%20details.png?alt=media&amp;token=005b5fb9-807f-47b9-9ad7-b2a3d1db5521" alt="The BigQuery Create table form with the file source, destination dataset, and table name filled in"><figcaption><p>table upload example details. Replace with your own dataset and table name</p></figcaption></figure>

4. **Manually Define Schema**: Specify the schema details manually. Define each column accurately, and make sure the datatype and column names precisely match those in the [Table data structure](#table-data-structure). Any discrepancies in spelling or datatype lead to errors during the upload process. While you have flexibility to modify the schema by adding or removing columns based on your specific data requirements, this guide focuses on the recommended fields we suggest including.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FNj5MUUU9OdXGFJiujwmC%2FJSONL%20BigQuery%20structure.png?alt=media&amp;token=3e4c4040-7462-4110-a2aa-8a91753653ab" alt="The BigQuery Create table form with the schema fields defined manually"><figcaption><p>Follow our <a href="#table-data-structure">Table data structure</a> and check for spelling</p></figcaption></figure>

5. **Advanced options**: Expand the **Advanced options** and tick the **Unknown values** checkbox. This setting allows the system to gracefully handle missing information in specific columns of some records, ensuring that rows with incomplete data are not rejected or throw errors during the upload process.
6. **Create the Table**: To finalize the creation, click **Create table**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Fz7GF3cWvzoLQxhSQH50D%2FJSON%20Unkown%20Values%20select.png?alt=media&amp;token=6e91e47c-40de-4ca2-8887-61f7850f62cf" alt="The BigQuery Advanced options section with the Unknown values checkbox ticked"><figcaption><p>tick <strong>Unknown values</strong> and you're ready to create</p></figcaption></figure>

This method allows initializing your BigQuery table with a JSONL dataset suitable for bulk data uploads. However, it does not support ongoing data refreshes. See the [Keep Event Data Updated](#keep-event-data-updated) section for advice on setting up a regularly updated table after initialization.

## API connection method

This method works well for smaller datasets as initial upload and must be used for continuous updates to the table as recommended in our [Keep Event Data Updated](#keep-event-data-updated) section.

### Table creation code

To establish the required data structure in BigQuery, you can utilize the following Python script. This script explicitly defines the columns and data types as laid out in our [Table data structure](#table-data-structure), configuring them precisely as needed for your BigQuery table. Before executing this script, ensure you have the following prerequisites:

* **SERVICE\_ACCOUNT\_JSON**: This is your service account JSON key, which is typically stored in a secure file. If your organization uses a different method to handle service account keys, modify the code accordingly.
* **dataset\_id**: Specify whether this is a new dataset or an existing one in which you want to place this table.
* **table\_id**: Determine a name for your new PredictHQ data table in BigQuery.

Manage this table creation code separately from other data processing scripts to maintain clarity and ease of updates. Use the following script:

{% code lineNumbers="true" fullWidth="true" %}

```python
from google.cloud import bigquery

#Set Service Account Key connection
SERVICE_ACCOUNT_JSON='~/file_location/service_account_key.json' 

# Set BigQuery variables
dataset_id = "[dataset_name]"
table_id = "[table_name]"

# Initialize the BigQuery client
client = bigquery.Client.from_service_account_json(SERVICE_ACCOUNT_JSON)

# Manually create schema
schema = [
    bigquery.SchemaField("id", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("parent_event", "JSON"),
    bigquery.SchemaField("title", "STRING"),
    bigquery.SchemaField("alternate_titles", "JSON"),
    bigquery.SchemaField("description", "STRING"),
    bigquery.SchemaField("category", "STRING"),
    bigquery.SchemaField("labels", "JSON"),
    bigquery.SchemaField("phq_labels", "JSON"),
    bigquery.SchemaField("rank", "INTEGER"),
    bigquery.SchemaField("local_rank", "INTEGER"),
    bigquery.SchemaField("phq_attendance", "INTEGER"),
    bigquery.SchemaField("entities", "JSON"),
    bigquery.SchemaField("duration", "INTEGER"),
    bigquery.SchemaField("start", "TIMESTAMP"),
    bigquery.SchemaField("start_local", "TIMESTAMP"),
    bigquery.SchemaField("end", "TIMESTAMP"),
    bigquery.SchemaField("end_local", "TIMESTAMP"),
    bigquery.SchemaField("predicted_end", "TIMESTAMP"),
    bigquery.SchemaField("predicted_end_local", "TIMESTAMP"),
    bigquery.SchemaField("updated", "TIMESTAMP"),
    bigquery.SchemaField("first_seen", "TIMESTAMP"),
    bigquery.SchemaField("timezone", "STRING"),
    bigquery.SchemaField("location", "JSON"),
    bigquery.SchemaField("geo", "JSON"),
    bigquery.SchemaField("scope", "STRING"),
    bigquery.SchemaField("country", "STRING"),
    bigquery.SchemaField("place_hierarchies", "JSON"),
    bigquery.SchemaField("state", "STRING"),
    bigquery.SchemaField("private", "BOOLEAN"),
    bigquery.SchemaField("impact_patterns", "JSON"),
    bigquery.SchemaField("predicted_event_spend", "INTEGER"),
    bigquery.SchemaField("predicted_event_spend_industries", "JSON")
]

#basic create code with no error handling
dataset_ref = client.dataset(dataset_id)
table_ref = dataset_ref.table(table_id)
table = bigquery.Table(table_ref, schema=schema)
table = client.create_table(table)  # Make an API request to create the table.
print("Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id))
```

{% endcode %}

This script sets up the initial table structure within BigQuery, providing a foundation for subsequent data loads.

### Extract from Events API

This section outlines the process of querying the PredictHQ Events API using Python, using the example for Tom's Pizzeria. This approach ensures the extracted data is directly relevant to Tom’s operational needs. The [Scenario](#scenario-toms-pizzeria) section of this guide explains the methodology and rationale behind the data extraction parameters used below.

Before initiating the script, ensure you have configured the following prerequisites:

* **phq\_access\_token**: Insert your PredictHQ access token here. For enhanced security, consider referencing the token indirectly if you prefer not to hard-code it into your script.
* **SERVICE\_ACCOUNT\_JSON**: This is your Google Cloud Platform service account JSON key, which should be securely stored. Adjust the access method in the script if your organization's practices differ.
* **dataset\_id**: Designate whether this is a new or existing dataset in which you plan to house the PredictHQ data.
* **table\_id**: Assign a name to your new PredictHQ data table in BigQuery.
* **params**: Modify these parameters as needed to align with the data you intend to extract from PredictHQ.

This Python script fetches the necessary data from the Events API. This method loops through the paginated response from the API and pulls all results and columns. The [next section](#transform-api-responses) covers transforming this data before we push for upload.\
For more details on any of the parameters we’ve used in the script that follows, see our [Events API](https://docs.predicthq.com/api/events/search-events) documentation, keeping in mind our [Scenario](#scenario-toms-pizzeria) to pull attended results in Seattle for Tom. Use the following script:

{% code lineNumbers="true" fullWidth="true" %}

```python
import time
import requests
import json
from google.cloud import bigquery

base_url = "https://api.predicthq.com/v1/events"
access_token = "[phq_phq_access_token]"  
dataset_id = "[dataset_name]"
table_id = "[table_name]" 
SERVICE_ACCOUNT_JSON='~/file_location/service_account_key.json'

headers = {
    "Authorization": f"Bearer {access_token}",  
    "Accept": "application/json"
}

params = {      # adjust these parameters to correspond to the data you want to pull down
    "categories": "community,conferences,concerts,expos,festivals,performing-arts,sports",
    "place.scope": "5809844",     #Seattle geonames ID
    "active.gte": "2024-06-01",
    "active.lte": "2024-06-30",
    "state": "active,predicted",
    "limit": 500       # Maximum number of events per page
}

# Initialize the BigQuery client
client = bigquery.Client.from_service_account_json(SERVICE_ACCOUNT_JSON)

def fetch_all_pages(base_url, headers, params):
    print("calling Events API")
    
    results = []
    next_url = base_url  # Start with the base URL

    while next_url:
        response = requests.get(next_url, headers=headers, params=params)
        params = None  # After the first request, prevent re-sending initial parameters
        if response.status_code == 200:
            data = response.json()
            results.extend(data.get('results', []))
            next_url = data.get('next')  # Update the next_url from the 'next' field in the response
        else:
            print(f"Failed to fetch data: {response.status_code}, Message: {response.text}")
            break

    print("total events fetched", len(results))

    return results

events_data = fetch_all_pages(base_url, headers, params)

```

{% endcode %}

### Transform API responses

To ensure seamless compatibility with the BigQuery table structure, we run a transformation function applied to the data retrieved from the Events API in the previous step. The function performs essential adjustments, including:

* Handling null or empty responses to maintain data integrity.
* Restricting output to only the columns defined in our table structure ensures consistency and relevance.
* Formatting complex fields to JSON, suitable for BigQuery ingestion.

To transform the data after extraction, append this transformation code to the extraction code from the previous step. This code readies the data for loading into BigQuery:

{% code lineNumbers="true" fullWidth="true" %}

```python
def prepare_data_for_bigquery(events_data):
    schema_fields = set([
        'id', 'parent_event', 'title', 'alternate_titles', 'description', 'category', 'labels',  
        'phq_labels', 'rank', 'local_rank', 'phq_attendance', 'entities', 'duration', 'start', 
        'start_local', 'end', 'end_local', 'updated', 'predicted_end', 'predicted_end_local', 'first_seen', 
        'timezone', 'location', 'geo', 'scope', 'country', 'place_hierarchies', 'state', 'private', 
        'impact_patterns', 'predicted_event_spend', 'predicted_event_spend_industries'
    ])

    # Fields that are to be in JSON format
    json_fields = {'phq_labels', 'entities', 'geo', 'location', 'impact_patterns', 
                   'predicted_event_spend_industries', 'labels', 'place_hierarchies', 
                   'parent_event', 'alternate_titles'} 

    cleaned_events = []

    for event in events_data:
        filtered_event = {}

        for key in schema_fields:
            if key in event and event[key] is not None:
                # If key is in json_fields, serialize it as JSON string
                if key in json_fields:
                    # Ensure the data is properly structured as a JSON string
                    filtered_event[key] = json.dumps(event[key])
                else:
                    filtered_event[key] = event[key]
            else:
                # Provide default None for missing fields, or an empty JSON structure as appropriate
                filtered_event[key] = 'null' if key in json_fields else None

        cleaned_events.append(filtered_event)

    return cleaned_events

transformed_events_data = prepare_data_for_bigquery(events_data)

```

{% endcode %}

### Load data into the table

Once your script has extracted the data from the API and transformed it to meet our [schema requirements](#table-data-structure), the next step involves loading this data into the previously established BigQuery table. This process utilizes Python code integrated with the BigQuery API to load the data.

Below is the code block that you need to append to the end of the extraction and transformation script. It includes a basic retry mechanism to handle occasional upload failures, which is common in network-related operations. However, depending on your requirements for reliability and data integrity, you might consider implementing a more advanced retry logic. Append the following code:

{% code lineNumbers="true" fullWidth="true" %}

```python
def insert_data_with_retry(table_ref, data, max_attempts=3):
    for attempt in range(max_attempts):
        errors = client.insert_rows_json(table_ref, data)
        if not errors:
            print("Data inserted successfully.")
            return
        else:
            print(f"Attempt {attempt + 1} failed with errors: {errors}")
            time.sleep(2)  # Wait for 2 seconds before the next retry

    print("Failed to insert data after several attempts.")

table_ref = client.dataset(dataset_id).table(table_id)

#Run insert data with retry
insert_data_with_retry(table_ref, transformed_events_data)
```

{% endcode %}

With this step completed, the script has loaded the data from the PredictHQ Events API into your BigQuery table, and the data is ready for analytical querying. This setup initially caters to a single load of data; however, to maintain the relevance and timeliness of your data, consider adapting this script to periodically update the dataset based on changes reflected in the "updated" timestamp column of the source data. See the [Keep event data updated](#keep-event-data-updated) section on updating your data.

The full code that follows combines all three code parts into one executable:

<details>

<summary>Full Code</summary>

{% code lineNumbers="true" fullWidth="true" %}

```python
import time
import requests
import json
from google.cloud import bigquery

bse_url = "https://api.predicthq.com/v1/events"
access_token = "[phq_phq_access_token]"  
dataset_id = "[dataset_name]"
table_id = "[table_name]" 
SERVICE_ACCOUNT_JSON='~/file_location/service_account_key.json'


headers = {
    "Authorization": f"Bearer {access_token}",  
    "Accept": "application/json"
}

params = {      # adjust these parameters to correspond to the data you want to pull down
    "categories": "community,conferences,concerts,expos,festivals,performing-arts,sports",
    "place.scope": "5809844",     #Seattle geonames ID
    "active.gte": "2024-06-01",
    "active.lte": "2024-06-30",
    "state": "active,predicted",
    "limit": 500       # Maximum number of events per page
}

# Initialize the BigQuery client
client = bigquery.Client.from_service_account_json(SERVICE_ACCOUNT_JSON)

def fetch_all_pages(base_url, headers, params):
    print("calling Events API")
    
    results = []
    next_url = base_url  # Start with the base URL

    while next_url:
        response = requests.get(next_url, headers=headers, params=params)
        params = None  # After the first request, prevent re-sending initial parameters
        if response.status_code == 200:
            data = response.json()
            results.extend(data.get('results', []))
            next_url = data.get('next')  # Update the next_url from the 'next' field in the response
        else:
            print(f"Failed to fetch data: {response.status_code}, Message: {response.text}")
            break

    print("total events fetched", len(results))

    return results

events_data = fetch_all_pages(base_url, headers, params)

def prepare_data_for_bigquery(events_data):
    schema_fields = set([
        'id', 'parent_event', 'title', 'alternate_titles', 'description', 'category', 'labels',  
        'phq_labels', 'rank', 'local_rank', 'phq_attendance', 'entities', 'duration', 'start', 
        'start_local', 'end', 'end_local', 'updated', 'predicted_end', 'predicted_end_local', 'first_seen', 
        'timezone', 'location', 'geo', 'scope', 'country', 'place_hierarchies', 'state', 'private', 
        'impact_patterns', 'predicted_event_spend', 'predicted_event_spend_industries'
    ])

    # Fields that are to be in JSON format
    json_fields = {'phq_labels', 'entities', 'geo', 'location', 'impact_patterns', 
                   'predicted_event_spend_industries', 'labels', 'place_hierarchies', 
                   'parent_event', 'alternate_titles'} 

    cleaned_events = []

    for event in events_data:
        filtered_event = {}

        for key in schema_fields:
            if key in event and event[key] is not None:
                # If key is in json_fields, serialize it as JSON string
                if key in json_fields:
                    # Ensure the data is properly structured as a JSON string
                    filtered_event[key] = json.dumps(event[key])
                else:
                    filtered_event[key] = event[key]
            else:
                # Provide default None for missing fields, or an empty JSON structure as appropriate
                filtered_event[key] = 'null' if key in json_fields else None

        cleaned_events.append(filtered_event)

    return cleaned_events

transformed_events_data = prepare_data_for_bigquery(events_data)

def insert_data_with_retry(table_ref, data, max_attempts=3):
    for attempt in range(max_attempts):
        errors = client.insert_rows_json(table_ref, data)
        if not errors:
            print("Data inserted successfully.")
            return
        else:
            print(f"Attempt {attempt + 1} failed with errors: {errors}")
            time.sleep(2)  # Wait for 2 seconds before the next retry

    print("Failed to insert data after several attempts.")

table_ref = client.dataset(dataset_id).table(table_id)

#Run insert data with retry
insert_data_with_retry(table_ref, transformed_events_data)
```

{% endcode %}

</details>

## Keep event data updated

Event data is dynamic and events can change frequently. This happens when events are canceled, posted, or have details updated. Also, PredictHQ’s pipeline is constantly fetching new events so new future events are always being added and can be downloaded via the API.

To keep your data updated see [Keep data updated via API](https://docs.predicthq.com/integrations/integration-guides/keep-data-updated-via-api). Use a similar code to the [API connection method code](#api-connection-method) using the ‘updated’ parameter to filter for recently changed events. This extracts all new events and updates to events. Check for events updated since your last table update using the ‘updated’ timestamp column. You will need to code for updating and replacing the data in BigQuery according to your preferred data update standards, but the structure will be the same as outlined earlier.

We recommend running a daily update process (such as a cron job) that calls the PredictHQ API and updates the data in your data lake.

## Querying the loaded data

Once the data is successfully loaded into BigQuery, you can begin querying it to derive insights relevant to your use case. This section provides an example of a BigQuery SQL query tailored to Tom’s scenario as outlined earlier. While the initial data load might have utilized specific filters via the WebApp or API parameters, it's often useful to perform additional queries directly within BigQuery. This capability is particularly valuable if you have loaded a broader dataset and need to perform dynamic or complex filtering post-load.

Some common fields to query are:

* **category:** filter down to the relevant categories most likely impacting your [industry](https://docs.predicthq.com/getting-started/guides/industry-specific-event-filters)
* **start and end:** filter on start and end dates being in a specified time period. You might be looking at events in the next week or month or longer.
* **rank:** is commonly used to filter out smaller events. Filter where rank is equal to or greater than a specific field to filter out smaller events.
* **geo:** This field contains geojson data (see the [GeoJSON overview](https://docs.predicthq.com/getting-started/guides/geolocation-guides/overview#geojson) for more details) on the location event. For attended events, this field typically holds the latitude and longitude of the point at which the event is occurring. It can also hold [polygon](https://docs.predicthq.com/getting-started/guides/geolocation-guides/working-with-polygons) information for events that cover a wide area like marathons or severe weather events. For marathons, the polygon shows the route of the marathon. Query on this field to find all events in an area like a radius.

See the [Filtering Guide](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events) for more examples. The SQL example later in this section shows how to query these fields in the database.

Below is a sample BigQuery SQL query that aligns with the parameters specified for our example. This query filters events based on the categories, date range, event rank, and geographical proximity to Tom’s location.

You use this type of query to find all events within a specified radius of a business location. For example a restaurant, hotel, store, parking garage, or any other business location. Once you have the data loaded into GCP you will want to find how events are impacting your locations. Use the type of query in the earlier example for each location to get all the events around that location:

{% code lineNumbers="true" fullWidth="true" %}

```sql
SELECT *
FROM `predicthq_dataset_test.phq_api_json_format`
WHERE category IN ('concerts','conferences','festivals','performing-arts')
  AND `start_local` >= '2024-06-01' --Change this to the date range you want to display events for - e.g. the next 30 days
  AND `end_local` <= '2024-06-30'
  AND rank >= 30
  AND ST_Distance(
      ST_GeogPoint(
          CAST(JSON_EXTRACT_SCALAR(geo, '$.geometry.coordinates[0]') AS FLOAT64),
          CAST(JSON_EXTRACT_SCALAR(geo, '$.geometry.coordinates[1]') AS FLOAT64)),
          ST_GeogPoint(-122.33, 47.60)  --Tom's store location in our example
      ) <= 2400 -- Approximately 1.48 miles in meters
	--When implementing this use the Predicted Impact Area API to find the area for your location
  AND state IN ('active', 'predicted');
```

{% endcode %}

This query retrieves records that meet all the specified criteria, allowing Tom to identify events that could potentially influence the operations and traffic at this pizzeria in Seattle. Modify the earlier query to fit the specific fields and data types of your table if they differ from this example, and fill your latitude and longitude for your locations using our [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area) to determine the optimal area for each location.

Visually, this type of query allows you to pull all the events in a radius, as shown in the Radius Map image that follows:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Feyx8z9RDcn3OCCttxBz1%2FRadius%20Map.png?alt=media&amp;token=06ef7bcc-699d-45c5-b6d7-2dab3aa787cf" alt="A map showing a circular radius around a business location with the surrounding events plotted inside it"><figcaption><p>Radius Map example from our website</p></figcaption></figure>

A common example is customers often look at events occurring in the next one to three months and may display this information in their application, in a BI tool, or in other types of products and tools. A common approach to doing this can be to have a table with a list of your business locations with latitude and longitude for each. For each, call the [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area) to determine the Predicted Impact Area and then look up your store locations in the table. For example you may have a table of locations like the following:

<table data-full-width="true"><thead><tr><th>location</th><th>lattitude</th><th>longitude</th><th>radius</th><th>radius_unit</th><th>date_start</th><th>date_end</th></tr></thead><tbody><tr><td>store1-chicago</td><td>41.8131</td><td>-87.6586</td><td>4.11</td><td>mi</td><td>2023-07-01</td><td>2023-12-31</td></tr><tr><td>Hyde Park</td><td>51.50736</td><td>-0.16411</td><td>2.06</td><td>mi</td><td>2024-01-01</td><td>2024-03-31</td></tr><tr><td>store10-new-yor</td><td>40.73061</td><td>-73.93524</td><td>...</td><td>...</td><td>...</td><td>...</td></tr></tbody></table>

You can look up location details from this table (to find the lat/long for a store for example) and then use it to find events with SQL like that shown in the earlier example. See our [Snowflake data science guide](https://docs.predicthq.com/integrations/third-party-integrations/snowflake/snowflake-data-science-guide) for an example of doing this in Snowflake.

Using BigQuery for these queries ensures that you leverage powerful, scalable SQL analytics over large datasets, enabling responsive decision-making based on the latest event data available in your system.\\

## Utilizing PredictHQ data in your data warehouse

Having integrated PredictHQ's rich events data into your data warehouse, the opportunities to leverage this data are extensive. By now, you've successfully set up your data structure within Google Cloud Platform's BigQuery and have a solid understanding of the JSONL file Upload or the API Connection methods. Here’s how you can maximize the value of PredictHQ data within your organization:

#### 1. Cross-referencing with internal datasets

Enhance the granularity and relevance of your internal analytics by cross-referencing PredictHQ events data with your own datasets. For instance, you can correlate sales data with event occurrences to analyze the impact of local events on sales performance. This cross-analysis can be crucial for demand forecasting and strategic planning.

Customers sometimes use fields like [Placekey ](https://docs.predicthq.com/getting-started/guides/geolocation-guides/join-events-using-placekey)to join events data and other location data.

#### 2. Demand analysis and forecasting

PredictHQ data can significantly enhance your demand forecasting models, especially for businesses that are impacted by local events, such as retail, hospitality, and transportation. By understanding when significant events are happening, you can better predict and prepare for attendance surges or declines.

You can use Event data from your data warehouse in your demand forecast to improve forecast accuracy. See our [Snowflake data science guide](https://docs.predicthq.com/integrations/third-party-integrations/snowflake/snowflake-data-science-guide) for an example of how you can implement ML features for demand forecasting in a data warehouse. Although that example shows how to do this in Snowflake, a similar approach applies to other data warehouses. See also [Improving demand forecasting models with event features](https://docs.predicthq.com/getting-started/guides/features-api-guides/improving-demand-forecasting-models-with-event-features).

#### 3. Building tailored reports

Use the data within BigQuery to create detailed reports and dashboards that monitor the effects of events on your business operations. These reports can provide actionable insights to business users across your organization, from marketing teams planning campaigns around major events to supply chain management preparing for increased activity.

See [Use Events Data in Power BI](https://docs.predicthq.com/integrations/third-party-integrations/using-event-data-in-power-bi) for an example of building reports in Power BI. You can connect Power BI or other BI tools to your database to build dashboards and reports. See also [How to Connect PowerBI to Google BigQuery](https://learn.microsoft.com/en-us/power-query/connectors/google-bigquery).

#### 4. Enhancing customer experience

Inform your customers about local events that might impact their experience with your service or product. For example, a transportation company could provide passengers with real-time updates about events that might affect travel times or service availability.

#### 5. Event-driven marketing

Plan and execute marketing campaigns that align with upcoming events to capitalize on increased foot traffic or digital engagement. This targeted approach can improve marketing ROI by reaching audiences when they are most receptive.

By tapping into the detailed and predictive insights provided by PredictHQ, your business can not only anticipate the impact of external events but also strategize proactively to harness potential opportunities or mitigate risks. Whether through enhancing predictive analytics, refining customer engagement strategies, or driving operational efficiencies, PredictHQ's events data serves as a powerful tool in your data-driven decision-making arsenal.


# Integrate with Loop Links

Loop Links let you submit missing events and provide feedback on existing events.

[PredictHQ's Loop tool](https://www.predicthq.com/tools/loop) allows customers to submit feedback on existing events and to submit missing events. PredictHQ has global events data from hundreds of providers, but sometimes our data may not include events such as hyperlocal events. Loop allows customers to report events that appear to be missing. It also allows customers to provide feedback on events if they have updates to details like attendance, times, or location.

Using [Loop](https://loop.predicthq.com/) requires a PredictHQ login to the WebApp. If you want your users to report missing events or give event feedback without a PredictHQ login, you can integrate Loop Links into your product.

**Loop Links** let you integrate with Loop without your users needing a WebApp login, and enable the following:

* You can integrate Loop into your products, such as a web app, mobile app, or other tool
* You can generate a unique URL to allow your users to submit event feedback and missing event information
* PredictHQ processes events in the normal way and adds valid events or feedback to its system
* The Events API returns events that PredictHQ approves via Loop

This means you can allow your users to submit feedback on events but your support team doesn't need to spend time managing this feedback. It goes straight to PredictHQ.

To use Loop Links you need to use the API that creates Loop Links. See [**Loop Links Technical Details**](#loop-links-technical-details). See also, our [Loop Links API documentation](https://docs.predicthq.com/api/loop/overview) for details on creating Loop Links.

## Overview

Loop Links provide a URL that allows a user to provide event feedback. You create Loop Links URLs via the Loop Links API. You must configure your own URLs before you can integrate Loop Links into your application.

The link does not require authentication. It has customer details embedded. For example:

* **Label**: My First Capture Link
* **Link**: `https://phq.link/loop/jG5KnDpad5SAUMkUtR` (note: this is not a valid link, just an example)

You can link to the URL from within your application, and feedback goes straight into the Loop system.

The advantage is you don't need to build a UI. The UI is responsive and works on desktop, tablet, and mobile.

## Loop Links integration

You integrate two functions in your application:

* One for submitting missing events
* Another for feedback on events - link event feedback to a part of your application that displays an event

These buttons link to the screens shown in the following section.

The following image shows a fictitious example app with examples of adding buttons for the two types of Loop Feedback

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FEWp9p9vhFb7LytaPpJlc%2Fexample-app-with-loop-links.png?alt=media&amp;token=1cc5264d-3233-40bf-9b67-aa97800ce1ce" alt="A fictitious example app with buttons for submitting a missing event and providing event feedback through Loop Links"><figcaption></figcaption></figure>

The following diagram shows how your app integrates with the Loop Links event pages:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FFrcngRA6QcTXUM3BpQlw%2Floop-links-integrated-example.png?alt=media&amp;token=05f7cdc5-4841-4579-a629-709c0f6f10f7" alt="Diagram showing how the buttons in an app link to the Loop Links pages for submitting a missing event and providing event feedback"><figcaption></figcaption></figure>

The heading at the top of the Loop pages defaults to your organization name in the WebApp. You can update it to change it via the API.

**Missing event link**

Opens a PredictHQ web page where users can enter details of a missing event in the browser.

We recommend you open this in a new window.

**Event feedback link**

Opens a PredictHQ web page where users can provide feedback on an existing event. Requires the public event ID of the event.

In your app, where you display a PredictHQ event, integrate this link. We recommend you open this in a new window.

### Submitting missing events

When a user submits a missing event:

1. Users enter event details
2. PredictHQ teams review events and approve or reject them
3. Approved events show as active events in your account
4. PredictHQ emails users when it approves or rejects an event

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FAZRCq6RIwEhkdXBfD6qb%2Floop-submit-missing-event.png?alt=media&amp;token=3a91c43b-c8ab-4713-b60c-7cd57a02c651" alt="The Loop Links page where users enter details of a missing event"><figcaption></figcaption></figure>

### Providing feedback on events

When a user gives feedback on an event:

1. On the page, review the event details
2. Provide feedback
3. Pass an event ID to the Loop Link URL
4. PredictHQ approves or rejects the feedback
5. Users receive an email if there are any questions about their feedback

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Ft47wtUaNffygvX2VzAta%2Floop-event-feedback.png?alt=media&amp;token=5622784d-f4fc-4d28-8aac-13664302aed6" alt="The Loop Links page where users review an event&#x27;s details and provide feedback on it"><figcaption></figcaption></figure>

## Loop Links automated emails

The Loop Links platform sends automated emails in the following cases:

* When PredictHQ approves a submitted event
* When PredictHQ rejects a submitted event
* When there is a reply or comment on event feedback

The email templates contain the organization at the top of the template. This is the same organization name that is shown at the top of the the Loop Link pages for submitting missing events and event feedback. You can update it by calling `PUT /v1/loop/settings`. See [**Loop Links Technical Details**](#loop-links-technical-details) for more information.

**Note that users cannot reply to these emails. In order to reply to them you need to use the event feedback page for the event in question and send a response in the feedback.**

The following tabs show some example emails:

{% tabs %}
{% tab title="Approved submission email" %}
The following image is an example of the email template for approved events:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F12F9a4gyauU3aRE8p7vt%2Fapproved-event-loop-links-email.png?alt=media&amp;token=4f54b781-bae4-43a8-b189-e54837b5da23" alt="Example Loop Links email telling a user that the event they submitted was approved"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Reply to submission/feedback email" %}
See an example of the email template for rejected events and replies to event feedback:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FbxSy2l2WMgjJyHPm3q8t%2Freply-event-loop-links-email.png?alt=media&amp;token=4d600793-b2e4-4ec0-a02c-e6cfdab27ad5" alt="Example Loop Links email telling a user that PredictHQ replied to their event submission or feedback"><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

## Tracking Loop feedback

If you have admin access, you can track Loop feedback at [the Loop website](https://loop.predicthq.com/) :

* Needs a PredictHQ login
* Shows whether PredictHQ approved or rejected Loop submissions
* Shows details of the discussion about the Loop events with responses from PredictHQ
* Lets you track the status of events your end users submit

Support teams typically use this if issues are raised about event feedback and they want to review the feedback.

## Loop Links technical details

### Integration overview

To integrate Loop Links with your application:

1. Using the API, create Loop Links:
   1. In your system, store the links, or
   2. Use the link immediately.
2. To set the name displayed at the top of the Loop pages, in the settings API, update the **`org_name`** field if required
3. In your application, implement the links. When an end-user clicks a link, the Public Loop UI opens in their browser. No login is needed. The end-user completes the form to submit an event (or feedback, depending on the type of link) and receives an email when PredictHQ approves or rejects the event they submitted.

### Types of links

#### Submit missing event

To **submit a missing event**, from your application, open the Loop Link:

E.g., open the link with /event/ in the URL:

`https://loop.phq.link/event/kt9fJZXpWFGSA5ky1Cunb2` (note: this is not a valid link just an example)

#### Submit event feedback

To **provide feedback on an existing event** - open the /event-feedback/ Loop Link and, on the URL, supply the `event_id` parameter:

`https://loop.phq.link/event-feedback/kt9fJZXpWFGSA5ky1Cunb2?event_id=BzjFubD5eqvrRA7NSw` (note: this is not a valid link just an example)

Note that the event ID to use is the `id` field from the [Events API](https://docs.predicthq.com/api/events/search-events). Users typically provide feedback while you display an event from the PredictHQ API in your application. To let users provide feedback, add a feedback link or icon next to each event.

#### To pre-fill the user's email address

The Loop forms require a user email address. You can pre-populate the email address by passing it in the query string. The name of the parameter is `email`, as in this example:

`https://loop.phq.link/event/kt9fJZXpWFGSA5ky1Cunb2?email=example@example.com` (note: this is not a valid link just an example)

### Loop Link expiration and reuse

Loop Links work as follows:

* You can reuse Loop Links unless you set an expiry date time
* If you set an expiry date time, the link stops working after it expires
* If you don't set an expiry date time, you can reuse them indefinitely


# Third-party integrations

Managed delivery of PredictHQ's verified real-world context into your own environment - the foundation for model training, explainability, and [provisioned grounding](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding), with no sync pipeline to build. Choose a delivery option:

* [Snowflake](https://docs.predicthq.com/integrations/third-party-integrations/snowflake) - shared tables, queried in place. The lowest-friction path if you're on Snowflake.
* [AWS Data Exchange](https://docs.predicthq.com/integrations/third-party-integrations/aws-data-exchange) - full and incremental exports to S3.
* [SFTP](https://docs.predicthq.com/integrations/third-party-integrations/sftp) - the same export model, delivered as files.
* Destination guides: [Databricks](https://docs.predicthq.com/integrations/third-party-integrations/integrate-with-databricks), [BigQuery](https://docs.predicthq.com/integrations/integration-guides/loading-event-data-into-a-data-warehouse) (worked warehouse-loading example), [Tableau](https://docs.predicthq.com/integrations/third-party-integrations/using-event-data-in-tableau), [Power BI](https://docs.predicthq.com/integrations/third-party-integrations/using-event-data-in-power-bi), and [Excel](https://docs.predicthq.com/integrations/third-party-integrations/connecting-to-predicthq-apis-with-microsoft-excel).

If none of these fit, the APIs plus [Keep data updated via API](https://docs.predicthq.com/integrations/integration-guides/keep-data-updated-via-api) cover the do-it-yourself path.


# Receive data via Snowflake

Snowflake Secure Data Share deploys PredictHQ's verified real-world context directly into your Snowflake environment, where your own access controls govern it. Your models, pipelines, and AI systems query an always-current local share over a familiar SQL interface - the foundation for training forecasting models on event features and for [grounding AI systems inside your environment](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding).

PredictHQ manages delivery, so there is no ELT/ETL pipeline to build or maintain. You can check out the [Introduction to Secure Data Sharing](https://docs.snowflake.com/en/user-guide/data-sharing-intro.html) page if you're interested to read more on Snowflake's Secure Data Sharing.

## Sample data shares

PredictHQ offers multiple up-to-date event Data Shares on Snowflake's Marketplace. This, bundled up with Snowflake's 30-day trial, offers you a commitment-free opportunity to try PredictHQ's data for free.

The sample Data Shares are not limited in terms of columns or fields making them valuable for business and data science evaluations. However, these data shares are limited to a specific location and restricted time window that might not suit your use case. These samples therefore represent a small fraction of the data we have. We also offer Customized Data Shares, which we filter to match your preferences.

{% embed url="<https://app.snowflake.com/marketplace/listings/PredictHQ?search=predicthq>" %}
PredictHQ Sample Data Shares on Snowflake Marketplace
{% endembed %}

## Customized data shares

PredictHQ can set up Customized Data Shares to match your preferences in terms of data type, location, time window, and business use case. They are secure, and PredictHQ manages delivery, so they usually don't require business resources for data integrations if you're already in the Snowflake platform.

[Get in touch](https://www.predicthq.com/contact) with us to discuss your needs and we will come back to you as soon as possible.

## Backwards compatible changes <a href="#backwards-compatible-changes" id="backwards-compatible-changes"></a>

Be aware that we may make backwards compatible changes to the Snowflake tables from time-to-time. Examples of some changes we might make that don't break backwards compatibility, and that we may introduce at any time without warning:

* New columns added to existing tables.
* New tables in addition to existing tables.
* New event categories and labels.

## Frequently asked questions

These questions come up most often:

* **How does costing work on the data shares?**\
  Snowflake's architecture separates data warehousing into different distinct layers: storage, virtual warehouses (compute), and cloud services. By using PredictHQ's data through Snowflake, you would only pay for the amount of computation that you would perform on the shared data. In other words, there is no cost for you to store the data and you would only be billed for running queries on the shared data. You can read more about [Snowflake's costing on their website](https://www.snowflake.com/pricing-page-registration-page/).
* **How frequently is the shared data updated?**\
  PredictHQ updates its data shares at midnight in the region's timezone by default. This frequency is generally sufficient for most use cases. If you require more up-to-date data, PredictHQ can provide it as frequently as every 3 hours on request - this would likely incur additional fees. If you require it more frequently than mentioned here, please discuss options with your PredictHQ team.
* **Can I make a change in the shared data or re-share it?**\
  All database objects shared between accounts are read-only. They cannot be directly modified or deleted, including adding or modifying table data. Shared databases and all the objects in the database cannot be re-shared with other accounts.


# Example SQL queries for Snowflake

Using SQL queries in Snowflake, you can manipulate the shared data to fit a variety of tasks. Feeding the data into analyses, dashboards, and machine learning models are only a few examples of what you can do with PredictHQ's data and SQL data manipulation in Snowflake.

The following SQL examples are based on the Sample Data Shares we provide. Here our database name is marketplace but in your account, it would be the custom name you chose when you added the sample data shares to your Snowflake account.

### Filter on labels

To find events with a `construction` label, filter on the `ARRAY` column `labels` using [ARRAY\_CONTAINS](https://docs.snowflake.com/en/sql-reference/functions/array_contains.html#array-contains):

```sql
SELECT event_id,
       title,
       category,
       phq_rank,
       labels
FROM   marketplace.predicthq.seattle_attended_events AS EVENTS
WHERE  ARRAY_CONTAINS('construction' :: variant, EVENTS.labels);
```

Example Results:

| **EVENT\_ID**      | **TITLE**                    | **CATEGORY** | **PHQ\_RANK** |                   **LABELS**                  |
| ------------------ | ---------------------------- | ------------ | :-----------: | :-------------------------------------------: |
| 8VmnC4u2qhHiYBnZQ7 | Zak World of Facades Seattle | conferences  |       0       |       \[ "conference", "construction" ]       |
| MPCit98VjwyuLikWZB | TecHome Builder Summit Fall  | conferences  |       42      |       \[ "conference", "construction" ]       |
| 7qmG3u42V3cVxNi9qD | Northwest Remodeling Expo    | expos        |       67      |  \[ "architecture", "construction", "expo" ]  |
| EuGFPmDdpLcHkfZwHa | Northwest Remodeling Expo    | expos        |       64      |     \[ "construction", "expo", "product" ]    |
| GxVVHErJWx83mizc9m | MCAA GreatFutures Forum      | conferences  |       28      | \[ "business", "conference", "construction" ] |

### Filter on latitude and longitude

Filtering the `GEOGRAPHY` column geo to find events around a 500-meter radius of [47.623257, -122.336498](https://goo.gl/maps/wxnLAufEpESLCcDj9) using [ST\_DISTANCE](https://docs.snowflake.com/en/sql-reference/functions/st_distance.html#st-distance) and [ST\_MAKEPOINT](https://docs.snowflake.com/en/sql-reference/functions/st_makepoint.html#st-makepoint-st-point):

```sql
SELECT event_id,
       title,
       category,
       phq_rank,
       labels,
       phq_rank,
       geo
FROM   marketplace.predicthq.seattle_attended_events AS EVENTS
WHERE  ST_DISTANCE(EVENTS.geo, ST_MAKEPOINT(-122.336498, 47.623257)) <= 500;
```

Example Results:

| **EVENT\_ID**      | **TITLE**                                                    | **CATEGORY**    | **PHQ\_RANK** |                 **LABELS**                 |                                  **GEO**                                 |
| ------------------ | ------------------------------------------------------------ | --------------- | :-----------: | :----------------------------------------: | :----------------------------------------------------------------------: |
| EYL7o5uE65TcQFpmQD | Sarah Christine and Taylor Tuke                              | concerts        |       0       |           \[ "concert", "music" ]          |       { "coordinates": \[ -122.34197, 47.62218 ], "type": "Point" }      |
| E4zrz8MTdb2UfNQfPi | South Lake Union Winter Market                               | festivals       |       54      |               \[ "festival" ]              |      { "coordinates": \[ -122.33621, 47.622634 ], "type": "Point" }      |
| X9rWASDN88DcRWhW8Z | AUG 26! An Evening w/ Sarah Christine The Collective Seattle | concerts        |       0       |           \[ "concert", "music" ]          | { "coordinates": \[ -122.34197340000003, 47.6221728 ], "type": "Point" } |
| FAmiEHQvanW3cfpRzB | Parlor Tricks Comedy Night                                   | performing-arts |       0       | \[ "concert", "music", "performing-arts" ] | { "coordinates": \[ -122.3421581, 47.62294079999999 ], "type": "Point" } |
| B7T6izj2gSJSr6Um5u | The Collective Patio Sets: Sarah Christine                   | community       |       0       |           \[ "concert", "music" ]          | { "coordinates": \[ -122.3421581, 47.62294079999999 ], "type": "Point" } |

### Filter with a polygon

Using the GEOGRAPHY column geo to find all events within a user defined area (eg: within a polygon) using [ST\_WITHIN](https://docs.snowflake.com/en/sql-reference/functions/st_within.html), [ST\_MAKEPOLYGON](https://docs.snowflake.com/en/sql-reference/functions/st_makepolygon.html), and [TO\_GEOGPRAPHY](https://docs.snowflake.com/en/sql-reference/functions/to_geography.html).

First, we define the shape we are interested in restricting the search to, as shown in the Seattle polygon map.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FYmKGW1ig89ysQxsP2pBU%2Fseattle-polygon-snowflake-ex.png?alt=media&amp;token=7ea8f485-b734-42ba-9516-1d2063e0ee35" alt="Map of Seattle with a polygon drawn around the area used to restrict the event search"><figcaption></figcaption></figure>

The following query finds events inside the polygon:

```sql
SELECT seattle_events.event_id,
       title,
       category,
       phq_rank,
       geo
FROM marketplace.predicthq.seattle_attended_events seattle_events
WHERE st_within(seattle_events.geo, st_makepolygon(to_geography(
 ('LINESTRING(-122.30263710021973 47.62467785241324,-122.33980178833006 47.60442694445526,
  -122.34134674072267 47.58451555263637,-122.27954864501955 47.616925574159424,
  -122.30263710021973 47.62467785241324)'))))
```

Example Results:

| **EVENT\_ID**      | **TITLE**                                     | **CATEGORY** | **PHQ\_RANK** |                                  **GEO**                                 |
| ------------------ | --------------------------------------------- | ------------ | :-----------: | :----------------------------------------------------------------------: |
| 84xmSc634UTHwAkT5b | NWSL - OL Reign vs Kansas City Current        | sports       |       78      | { "coordinates": \[ -122.33163939999997, 47.5951518 ], "type": "Point" } |
| 3y8VCcVthX6dRk88aK | The Antlers                                   | concerts     |       43      |      { "coordinates": \[ -122.31962, 47.613938 ], "type": "Point" }      |
| BH7ffgQGiJx9yux2qd | Boris Brejcha                                 | concerts     |       59      |     { "coordinates": \[ -122.3322862, 47.5933082 ], "type": "Point" }    |
| BaqF5i5yYxBzFUGFLj | Kill The Noise                                | concerts     |       52      |     { "coordinates": \[ -122.3205827, 47.6137242 ], "type": "Point" }    |
| HpuMrnfLhdEgcBJu4q | Convent Bonfires, Bonsai Trees, and Good Job. | concerts     |       36      |     { "coordinates": \[ -122.3343786, 47.6005944 ], "type": "Point" }    |

Using the geo field of the events, these can be plotted on a map as shown in the results map.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F4lBKHvkudzuy7JAJYzuo%2Fseattle-polygon-snowflake-results-ex.png?alt=media&amp;token=4d0116d3-8225-4b7b-ac6c-667830425e42" alt="Map of Seattle with the events returned by the polygon query plotted as points inside the polygon area"><figcaption></figcaption></figure>


# Snowflake data science guide

Transforming Event Data into ML-Ready Features in Snowflake

## This guide and the Features API

This guide shows you how to generate machine learning ready features from PredictHQ's intelligent event data in Snowflake similar to the output of the [Features API](https://docs.predicthq.com/getting-started/core-concepts/what-is-the-features-api), but is not intended to be in parity with the comprehensive results of the Features API. If possible, our primary recommendation is to use the Features API as it provides more comprehensive results. For more information on the Features API, go to the [Features API documentation](https://docs.predicthq.com/api/features/get-features) and for a more detailed guide on using the Features API for Machine Learning, see the [Get features with the Features API notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/get-features-with-features-api.ipynb) guide.

If you don't know which is the best for you, [contact sales](https://www.predicthq.com/contact/sales).

## Overview

This guide assumes you have access to PredictHQ’s events data in Snowflake via a [Snowflake data share](https://docs.predicthq.com/integrations/third-party-integrations/snowflake). The guide shows you how to generate aggregations similar to those provided by the Features API documented in the Features API [list of available features](https://docs.predicthq.com/api/features/get-features#available-features). These features provide daily aggregated data which shows the sum of data for all events happening in a location - for example, the amount of people attending events around a location. The goal is to generate aggregated features that can be used in demand forecasting.

Snowflake's ease of use and integration have made it a popular choice as a cloud data warehouse and is one of the ways PredictHQ's intelligent event data can be accessed for various use cases. In this guide, this guide generates machine learning ready daily level aggregated event data on a per-location basis, intended to be similar to the data that the PredictHQ Features API provides and ready to be added to a training set.<br>

**Requirements:**

1\. A list of locations with their respective latitude & longitude.

2\. Access to PredictHQ's intelligent event data via Snowflake

3\. Understanding of SQL & Snowflake's SQL Interface.<br>

**The process to follow:**

1. Get the Predicted Impact Area for Each Location
2. Create the input table filled with locations
3. Set the date range that you want to retrieve data for
4. Choose which method to follow:
   1. [Snowpark Method](https://docs.predicthq.com/integrations/third-party-integrations/snowflake/snowflake-data-science-guide/snowpark-method-guide)
   2. [SQL Method](https://docs.predicthq.com/integrations/third-party-integrations/snowflake/snowflake-data-science-guide/sql-method-guide)
5. Use the output in machine learning demand forecasting models or for other applications

## Get the Predicted Impact Area for each location

When querying events at the location level, a common way to retrieve those events is with a latitude, longitude, and radius to get the events within a given area. But, a common gap is knowing what radius to use when searching for events. The Predicted Impact Area API is the recommended approach.

The [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area) returns a polygon that defines the optimal area around a location and takes into account a number of different factors like population density, the surrounding street network, and the industry vertical of the location.

As a first step, get the Predicted Impact Area for each location before moving forward with the guide. The following example uses `area_type=radius` so the result can be stored directly in the `SAVED_LOCATIONS` table used by the Snowflake SQL later in this guide. For more information visit [Predicted Impact Area API documentation](https://docs.predicthq.com/api/impact-area/get-impact-area).

{% hint style="info" %}
In a separate environment outside of Snowflake, run this code:
{% endhint %}

```python
import httpx

# Copy your access token here or see our Quickstart docs:
# https://docs.predicthq.com/guides/quickstart/
API_TOKEN = 'ABC123'

list_of_locations = [
    {'name': 'store1-chicago', 'latitude': '41.81310', 'longitude': '-87.65860', 'industry': 'retail'},
    {'name': 'Hyde Park', 'latitude': '51.50736', 'longitude': '-0.16411', 'industry': 'accommodation'},
    {'name': 'store10-new-york', 'latitude': '40.730610', 'longitude': '-73.935242', 'industry': 'retail'},
]

for location in list_of_locations:
    response = httpx.get(
        "https://api.predicthq.com/v1/impact-area/",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Accept": "application/json",
        },
        params={
            "location.origin": f"{location['latitude']},{location['longitude']}",
            "industry": location["industry"],
            "area_type": "radius",
            "radius_unit": "mi",
        },
    )
    result = response.json()
    radius = result["geojson"]["properties"]["radius"]
    radius_unit = result["geojson"]["properties"]["radius_unit"]
    print(f"{location['name']} ({location['industry']}): {radius} {radius_unit}")
```

## Create input table used in both methods

To be able to reference the locations further in the guide, a table of locations is required as input (called **SAVED\_LOCATIONS**). Fill this table with\
The **SAVED\_LOCATIONS** input table requires this format:

<table data-full-width="true"><thead><tr><th width="190">location</th><th>latitude</th><th>longitude</th><th data-type="number">radius</th><th>radius_unit</th><th>date_start</th><th>date_end</th></tr></thead><tbody><tr><td>store1-chicago</td><td>41.81310</td><td>-87.65860</td><td>4.11</td><td>mi</td><td>2023-07-01</td><td>2023-12-31</td></tr><tr><td>Hyde Park</td><td>51.50736</td><td>-0.16411</td><td>2.06</td><td>mi</td><td>2024-01-01</td><td>2024-03-31</td></tr><tr><td>store10-new-york</td><td>40.73061</td><td>-73.93524</td><td>null</td><td>...</td><td>...</td><td>...</td></tr></tbody></table>

The columns are:

* **location**: a unique identifier for the location.
* **latitude**/**longitude**: we recommend including five decimal places.
* **radius**: the value the Predicted Impact Area API returns.
* **radius\_unit**: coded for either “km” (kilometers) or “mi” (miles).
* **date\_start**/**date\_end**: the date range for the data to be returned. Can be changed.

Here is the input table used when running this code, and note the datatypes of each column for the inputs:

{% code fullWidth="true" %}

```sql
CREATE OR REPLACE TEMP TABLE saved_locations (
    location STRING
    , lat STRING
    , lon STRING
    , radius FLOAT
    , radius_unit STRING
    , date_start DATE
    , date_end DATE);

INSERT INTO saved_locations (location, lat, lon, radius, radius_unit, date_start, date_end)
VALUES ('Hyde Park', '51.5073638', '-0.1641135', 2.06, 'mi'   
        , DATE_TRUNC('MONTH', DATEADD(MONTH, -3, CURRENT_DATE()))       --Start of 3 months ago
        , DATEADD(DAY, -1, DATE_TRUNC('MONTH', CURRENT_DATE()))         --End of last month
        )
;
```

{% endcode %}

By default, the query returns three months of historical data. If you train the model, we recommend, at minimum, two years of historical data, but this can be changed as needed. If you are forecasting for a future period then the date range should reflect the period you are forecasting for - e.g. the next two weeks.

Once the input table matches the earlier format, the following code shapes that table to be in a day-by-day format of the input called **SAVED\_LOCATIONS\_DAILY:**

{% code fullWidth="true" %}

```sql
----split the table out into having one day equals one row between the date range.
CREATE OR REPLACE TEMP TABLE saved_locations_daily AS
select
    date(date_start) + value::int as date,
    s.location,
    s.lat,
    s.lon,
    s.radius,
    lower(s.radius_unit) as radius_unit        --forcing the lower in case of data entry mistakes
   from saved_locations s,
     table(flatten(array_generate_range(0, datediff('day', date_start, date_end) + 1))) t
;
```

{% endcode %}

## Choose which method to use

### 1. [Snowpark method guide](https://docs.predicthq.com/integrations/third-party-integrations/snowflake/snowflake-data-science-guide/snowpark-method-guide)

Call the Features API with Python. Then, in Snowflake, save the output ML features.

### 2. [SQL method guide](https://docs.predicthq.com/integrations/third-party-integrations/snowflake/snowflake-data-science-guide/sql-method-guide)

In Snowflake, use SQL to run over the events table and create the ML Features.

## Integrating PredictHQ Features into your demand forecasting model

The **ML\_FEATURES\_FOR\_LOCATIONS** table offers ready-to-use features for forecasting models. Merge these features with current demand data using the location and date as keys. Train models using historical data from this table and use future data for forecasting.

\
For more information on creating machine learning-ready features from PredictHQ’s intelligent event data, check out the [Get features with the Features API notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/get-features-with-features-api.ipynb) guide or this blog on [Enhancing Demand Forecasting with PredictHQ and PowerBI: A Technical Exploration](https://www.predicthq.com/blog/enhancing-demand-forecasting-with-predicthq-and-powerbi-a-technical). While these resources discuss the Features API, remember to use the **ML\_FEATURES\_FOR\_LOCATIONS** table instead.


# Snowpark method guide

Transforming Event Data into ML-Ready Features using Snowpark and Python

## Calling the Features API from Snowflake to calculate features

There are two options for calculating features in Snowflake:

1. Call the Features API using [Snowpark](https://docs.snowflake.com/en/developer-guide/snowpark/python/index)
2. Use the [Python Connector ](https://docs.snowflake.com/en/developer-guide/python-connector/python-connector)or other libraries.

If you take either of the earlier approaches, you can call the Features API for each location and save the results into a table instead of using SQL. These options skip the maintenance of SQL and is the recommended approach if possible.

The following is an example of calling the Features API with Python in Snowpark. This uses the PredictHQ Python SDK. It loops over the **SAVED\_LOCATIONS** table, calls the Features API using the SDK, and outputs the results into a table. So, it achieves a similar result to the SQL method but using the API. Modify this code to include the features you want to fetch.

This code is an example, not production-ready. Test and optimize it before you use it.

### Python code

The following code calls the Features API for each location in the **SAVED\_LOCATIONS** table:

{% code fullWidth="true" %}

```python
from snowflake.snowpark import Session
from predicthq import Client
import pandas as pd

# Snowflake connection parameters
connection_parameters = {
  "account": "<your_account>",
  "user": "<your_username>",
  "password": "<your_password>",
  "role": "<your_role>",
  "warehouse": "<your_warehouse>",
  "database": "<your_database>",
  "schema": "<your_schema>"
}

# Create a session
session = Session.builder.configs(connection_parameters).create()

# PredictHQ Client setup
phq = Client(access_token="your_predicthq_access_token")

# Fetch location data from the Snowflake table
locations_df = session.table("SAVED_LOCATIONS").to_pandas()

# Prepare a DataFrame to collect all data
all_data = []

# Iterate over each row in the location DataFrame
for index, location in locations_df.iterrows():
    # Prepare the radius in the appropriate unit
    radius_with_unit = f"{location['RADIUS']}{location['RADIUS_UNIT']}"

    # Call the Features API for each location
    for feature in phq.features.obtain_features(
            active__gte=str(location['DATE_START']),
            active__lte=str(location['DATE_END']),
            location__geo={
                "lon": location['LON'],
                "lat": location['LAT'],
                "radius": radius_with_unit
            },
            phq_attendance_sports__stats=["sum"],
            phq_attendance_conferences__stats=["sum"]

 # add more ML features here like phq_attendance_community, phq_attendance_concerts,
 # phq_attendance_expos, phq_attendance_festivals, phq_attendance_performing_arts,
 # and so on.

    ):
                data_point = {
            'location': location['LOCATION'],
            'date': feature.date,
            'phq_attendance_conferences': getattr(feature.phq_attendance_conferences.stats, 'sum', 0),
            'phq_attendance_sports': getattr(feature.phq_attendance_sports.stats, 'sum', 0)
        }
        all_data.append(data_point)

# Convert all collected data to a DataFrame
results_df = pd.DataFrame(all_data)

# Convert the DataFrame to a Snowpark DataFrame
snow_df = session.create_dataframe(results_df)

# Append the results to the existing Snowflake table
snow_df.write.mode("append").save_as_table("ML_FEATURES_FOR_LOCATIONS")

# Print the contents of the table to verify
print(session.table("ML_FEATURES_FOR_LOCATIONS").show())

# Close the session
session.close()

```

{% endcode %}

### Table output

The output of the Python script should look similar to the following table:

<table data-full-width="true"><thead><tr><th width="226">location</th><th width="178">date</th><th width="321" data-type="number">phq_attendance_conferences</th><th data-type="number">phq_attendance_sports</th></tr></thead><tbody><tr><td>store1-chicago</td><td>2024-01-16</td><td>231</td><td>19329</td></tr><tr><td>store1-chicago</td><td>2024-01-17</td><td>666</td><td>12312</td></tr><tr><td>store1-chicago</td><td>2024-01-18</td><td>215</td><td>0</td></tr><tr><td>store1-chicago</td><td>2024-01-19</td><td>87</td><td>23246</td></tr><tr><td>store1-chicago</td><td>2024-01-20</td><td>395</td><td>19448</td></tr></tbody></table>

### Refer back to [main guide](https://docs.predicthq.com/integrations/third-party-integrations/snowflake/snowflake-data-science-guide)


# SQL method guide

Transforming Event Data into ML-Ready Features using SQL

## Using Snowflake SQL to recreate the Features API

This guide uses a publicly available PredictHQ event sample table called\
**PREDICTHQ\_EVENTS\_RETAIL\_LONDON**\
In all later instances, replace this table name with the name of the events data table that PredictHQ has provisioned as per the [Snowflake Secure Data Share](https://docs.predicthq.com/integrations/third-party-integrations/snowflake).

The rest of the guide also uses temporary tables but you can turn these tables into permanent tables as needed.

Once you have created **SAVED\_LOCATIONS** as described on the parent page of this guide, complete the following steps:

1. To use the input table with the code in this guide, modify its format
2. Generate daily aggregated statistics for each location by:
   * attendance based features
   * rank based features
   * impact based features
   * To match the desired granularity, update the date range in the following code examples:
     * For training a machine learning model, update the dates to get historical data for the locations
     * If running a model in production and forecasting future demand, update the dates for the visibility window of the forecast - e.g. the new week, month, or months
3. Join all features together in a single output table

## Step 1: Modify the input table format

Once the **SAVED\_LOCATIONS** input table is created, the following code shapes that table to be in a day by day format of the input called **SAVED\_LOCATIONS\_DAILY**:

{% code fullWidth="true" %}

```sql
----split the table out into having one day equals one row between the date range.
CREATE OR REPLACE TEMP TABLE saved_locations_daily AS
select
    date(date_start) + value::int as date,
    s.location,
    s.lat,
    s.lon,
    s.radius,
    lower(s.radius_unit) as radius_unit        --forcing the lower in case of data entry mistakes
   from saved_locations s,
     table(flatten(array_generate_range(0, datediff('day', date_start, date_end) + 1))) t
;
```

{% endcode %}

## Step 2: Calculating daily aggregated ML features with SQL in Snowflake

The code calculates each Feature set in blocks. See the column headers in each code block for which Features are available to generate.

### Predicted Attendance features

The code calculates each value as the sum of Predicted Attendance for the day at a given location within the defined radius:

<pre class="language-sql" data-title="Predicted Attendance features" data-full-width="true"><code class="lang-sql"><strong>----Predicted Attendance features
</strong><strong>CREATE OR REPLACE TEMP TABLE phq_attendance_features AS
</strong>WITH events_attended AS (           --Attendance Features for main 7 categories
  SELECT
    e.event_id,
    s.date,
    s.location,
    e.category,
    imp.value:value::int as phq_attendance
  FROM predicthq.predicthq_events_retail_london e
  RIGHT JOIN saved_locations_daily s
    ON ST_DISTANCE(e.geo, ST_MAKEPOINT(s.lon, s.lat)) &#x3C;=
      CASE
        WHEN s.radius_unit = 'mi' THEN s.radius * 1609.34
        WHEN s.radius_unit = 'km' THEN s.radius * 1000
      END
    AND TO_DATE(CONVERT_TIMEZONE(CASE WHEN e.timezone IS NOT NULL THEN e.timezone ELSE 'UTC' END, e.event_start)) &#x3C;= s.date
    AND TO_DATE(CONVERT_TIMEZONE(CASE WHEN e.timezone IS NOT NULL THEN e.timezone ELSE 'UTC' END, e.event_end)) >= s.date,
  latERAL FlatTEN(INPUT => e.IMPACT_PATTERNS) vert,
  latERAL FlatTEN(INPUT => vert.value:impacts) imp
  WHERE imp.value:date_local::DATE = s.date
    AND vert.value:vertical::STRING = 'accommodation'
    AND imp.value:position::STRING = 'event_day'
    AND e.phq_attendance IS NOT NULL
    AND e.category in ('community','concerts','conferences','expos','festivals','performing-arts','sports')
),
events_attended_other AS (          --Attendance Features for special categories
  SELECT
    e.event_id,
    s.date,
    s.location,
    e.category,
    e.phq_attendance,
    CASE WHEN category = 'academic' and ARRAY_CONTAINS('social'::variant, e.labels) THEN 'social'
        WHEN category = 'academic' and ARRAY_CONTAINS('social'::variant, e.labels) THEN 'graduation'
        ELSE '' END as academic_split
  FROM predicthq.predicthq_events_retail_london e
  RIGHT JOIN saved_locations_daily s
    ON ST_DISTANCE(e.geo, ST_MAKEPOINT(s.lon, s.lat)) &#x3C;=
      CASE
        WHEN s.radius_unit = 'mi' THEN s.radius * 1609.34
        WHEN s.radius_unit = 'km' THEN s.radius * 1000
      END
    AND TO_DATE(CONVERT_TIMEZONE(CASE WHEN e.timezone IS NOT NULL THEN e.timezone ELSE 'UTC' END, e.event_start)) &#x3C;= s.date
    AND TO_DATE(CONVERT_TIMEZONE(CASE WHEN e.timezone IS NOT NULL THEN e.timezone ELSE 'UTC' END, e.event_end)) >= s.date
  WHERE e.phq_attendance IS NOT NULL
    AND e.category in ('school-holidays','academic')
),
attendance_group AS (               --Group the 7 main categories daily and make sure a result is displayed each day even if it's just 0
    SELECT
      data_range.date,
      data_range.location,
      SUM(CASE WHEN a.category = 'community' THEN a.phq_attendance ELSE 0 END) AS phq_attendance_community,
      SUM(CASE WHEN a.category = 'concerts' THEN a.phq_attendance ELSE 0 END) AS phq_attendance_concerts,
      SUM(CASE WHEN a.category = 'conferences' THEN a.phq_attendance ELSE 0 END)  AS phq_attendance_conferences,
      SUM(CASE WHEN a.category = 'expos' THEN a.phq_attendance ELSE 0 END) AS phq_attendance_expos,
      SUM(CASE WHEN a.category = 'festivals' THEN a.phq_attendance ELSE 0 END) AS phq_attendance_festivals,
      SUM(CASE WHEN a.category = 'performing-arts' THEN a.phq_attendance ELSE 0 END) AS phq_attendance_performing_arts,
      SUM(CASE WHEN a.category = 'sports' THEN a.phq_attendance ELSE 0 END) AS phq_attendance_sports
    FROM (SELECT date, location FROM saved_locations_daily) data_range
    LEFT JOIN events_attended a
        ON data_range.date = a.date
            AND data_range.location = a.location
    GROUP BY data_range.date, data_range.location
    ORDER BY data_range.date, data_range.location
),
attendance_group_other AS (         --Group the other categories daily and make sure a result is displayed each day even if it's just 0
    SELECT
      data_range.date,
      data_range.location,
      SUM(CASE WHEN ao.category = 'school-holidays' THEN ao.phq_attendance ELSE 0 END) AS phq_attendance_school_holidays,
      SUM(CASE WHEN ao.academic_split = 'graduation' THEN ao.phq_attendance ELSE 0 END) AS phq_attendance_academic_graduation,
      SUM(CASE WHEN ao.academic_split = 'social' THEN ao.phq_attendance ELSE 0 END) AS phq_attendance_academic_social
    FROM (SELECT date, location FROM saved_locations_daily) data_range
    LEFT JOIN events_attended_other ao
        ON data_range.date = ao.date
            AND data_range.location = ao.location
    GROUP BY data_range.date, data_range.location
    ORDER BY data_range.date, data_range.location
)
SELECT                              --final select for phq_attendance_features
  ag.date,
  ag.location,
  ag.phq_attendance_community,
  ag.phq_attendance_concerts,
  ag.phq_attendance_conferences,
  ag.phq_attendance_expos,
  ag.phq_attendance_festivals,
  ag.phq_attendance_performing_arts,
  ag.phq_attendance_sports,
  ago.phq_attendance_school_holidays,
  ago.phq_attendance_academic_graduation,
  ago.phq_attendance_academic_social
FROM attendance_group ag
LEFT JOIN attendance_group_other ago
    ON ag.location = ago.location
        AND ag.date = ago.date
;

SELECT * FROM phq_attendance_features order by location, date;
</code></pre>

If you want metrics other than SUM, use the following code as a template for each column. The category name part of the code for each column (in these examples defaulted to ‘community’) changes depending on which Predicted Attendance feature you want to call. Refer to the column code in the earlier Predicted Attendance features code block for available Feature categories:

{% code title="Count" fullWidth="true" %}

```sql
COUNT(CASE WHEN a.category = 'community' THEN 1 ELSE NULL END)
```

{% endcode %}

{% code title="Average" fullWidth="true" %}

```sql
IFNULL(ROUND(AVG(CASE WHEN a.category = 'community' THEN a.phq_attendance ELSE NULL END),2),0)Some code
```

{% endcode %}

{% code title="Median" fullWidth="true" %}

```sql
IFNULL(ROUND(MEDIAN(CASE WHEN a.category = 'community' THEN a.phq_attendance ELSE NULL END),2),0)
```

{% endcode %}

{% code title="Standard Deviation" fullWidth="true" %}

```sql
IFNULL(ROUND(STDDEV(CASE WHEN a.category = 'community' THEN a.phq_attendance ELSE NULL END),2),0)
```

{% endcode %}

{% code title="Min and Max" fullWidth="true" %}

```sql
IFNULL(MIN(CASE WHEN a.category = 'community' THEN a.phq_attendance ELSE NULL END),0)
IFNULL(MAX(CASE WHEN a.category = 'community' THEN a.phq_attendance ELSE NULL END),0)
```

{% endcode %}

### PHQ Rank features

The code calculates values as a count of events occurring at each rank level, per day, per location. If an event occurs over multiple days, it has a result in each day until the event is over. The following code returns each rank level as its own column:

{% code title="PHQ Rank features" fullWidth="true" %}

```sql
----PHQ Rank features
CREATE OR REPLACE TEMP TABLE phq_rank_features as
WITH events_ranked AS (             --Pull ranked events within range
  SELECT
    e.event_id,
    s.date,
    s.location,
    e.category,
    e.phq_rank,
    CASE WHEN category = 'academic' and ARRAY_CONTAINS('academic-session'::variant, e.labels) THEN 'session'
        WHEN category = 'academic' and ARRAY_CONTAINS('exam'::variant, e.labels) THEN 'exam'
        WHEN category = 'academic' and ARRAY_CONTAINS('holiday'::variant, e.labels) THEN 'holiday'
        ELSE '' END AS academic_split,
    CASE
      WHEN e.phq_rank between 0 and 20 THEN 1
      WHEN e.phq_rank between 21 and 40 THEN 2
      WHEN e.phq_rank between 41 and 60 THEN 3
      WHEN e.phq_rank between 61 and 80 THEN 4
      ELSE 5
    END as rank_level
  FROM predicthq.predicthq_events_retail_london e
  RIGHT JOIN saved_locations_daily s
    ON ST_DISTANCE(e.geo, ST_MAKEPOINT(s.lon, s.lat)) <=
      CASE
        WHEN s.radius_unit = 'mi' THEN s.radius * 1609.34
        WHEN s.radius_unit = 'km' THEN s.radius * 1000
      END
    AND TO_DATE(CONVERT_TIMEZONE(CASE WHEN e.timezone IS NOT NULL THEN e.timezone ELSE 'UTC' END, e.event_start)) <= s.date
    AND TO_DATE(CONVERT_TIMEZONE(CASE WHEN e.timezone IS NOT NULL THEN e.timezone ELSE 'UTC' END, e.event_end)) >= s.date
  WHERE e.phq_rank IS NOT NULL
    AND e.category in ('academic','public-holidays','school-holidays','observances')
 ),
 events_ranked_distinct AS (        --Get count per rank level
   SELECT
     r.date,
     r.location,
     r.category,
     r.academic_split,
     r.rank_level,
     count(DISTINCT r.event_id) AS distinct_event_count
   FROM events_ranked r
   GROUP BY
     r.date,
     r.location,
     r.category,
     r.academic_split,
     r.rank_level
)
SELECT                             --Final formatting and select for phq_rank_features
  data_range.date,
  data_range.location,
  SUM(CASE WHEN r.category = 'observances' AND r.rank_level = 1 THEN r.distinct_event_count ELSE 0 END)  AS phq_rank_observances_rank_level1,
  SUM(CASE WHEN r.category = 'observances' AND r.rank_level = 2 THEN r.distinct_event_count ELSE 0 END)  AS phq_rank_observances_rank_level2,
  SUM(CASE WHEN r.category = 'observances' AND r.rank_level = 3 THEN r.distinct_event_count ELSE 0 END)  AS phq_rank_observances_rank_level3,
  SUM(CASE WHEN r.category = 'observances' AND r.rank_level = 4 THEN r.distinct_event_count ELSE 0 END)  AS phq_rank_observances_rank_level4,
  SUM(CASE WHEN r.category = 'observances' AND r.rank_level = 5 THEN r.distinct_event_count ELSE 0 END)  AS phq_rank_observances_rank_level5,
  SUM(CASE WHEN r.category = 'public-holidays' AND r.rank_level = 1 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_public_holidays_rank_level1,
  SUM(CASE WHEN r.category = 'public-holidays' AND r.rank_level = 2 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_public_holidays_rank_level2,
  SUM(CASE WHEN r.category = 'public-holidays' AND r.rank_level = 3 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_public_holidays_rank_level3,
  SUM(CASE WHEN r.category = 'public-holidays' AND r.rank_level = 4 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_public_holidays_rank_level4,
  SUM(CASE WHEN r.category = 'public-holidays' AND r.rank_level = 5 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_public_holidays_rank_level5,
  SUM(CASE WHEN r.category = 'school-holidays' AND r.rank_level = 1 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_school_holidays_rank_level1,
  SUM(CASE WHEN r.category = 'school-holidays' AND r.rank_level = 2 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_school_holidays_rank_level2,
  SUM(CASE WHEN r.category = 'school-holidays' AND r.rank_level = 3 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_school_holidays_rank_level3,
  SUM(CASE WHEN r.category = 'school-holidays' AND r.rank_level = 4 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_school_holidays_rank_level4,
  SUM(CASE WHEN r.category = 'school-holidays' AND r.rank_level = 5 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_school_holidays_rank_level5,
  SUM(CASE WHEN r.academic_split = 'session' AND r.rank_level = 1 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_session_rank_level1,
  SUM(CASE WHEN r.academic_split = 'session' AND r.rank_level = 2 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_session_rank_level2,
  SUM(CASE WHEN r.academic_split = 'session' AND r.rank_level = 3 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_session_rank_level3,
  SUM(CASE WHEN r.academic_split = 'session' AND r.rank_level = 4 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_session_rank_level4,
  SUM(CASE WHEN r.academic_split = 'session' AND r.rank_level = 5 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_session_rank_level5,
  SUM(CASE WHEN r.academic_split = 'exam' AND r.rank_level = 1 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_exam_rank_level1,
  SUM(CASE WHEN r.academic_split = 'exam' AND r.rank_level = 2 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_exam_rank_level2,
  SUM(CASE WHEN r.academic_split = 'exam' AND r.rank_level = 3 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_exam_rank_level3,
  SUM(CASE WHEN r.academic_split = 'exam' AND r.rank_level = 4 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_exam_rank_level4,
  SUM(CASE WHEN r.academic_split = 'exam' AND r.rank_level = 5 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_exam_rank_level5,
  SUM(CASE WHEN r.academic_split = 'holiday' AND r.rank_level = 1 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_holiday_rank_level1,
  SUM(CASE WHEN r.academic_split = 'holiday' AND r.rank_level = 2 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_holiday_rank_level2,
  SUM(CASE WHEN r.academic_split = 'holiday' AND r.rank_level = 3 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_holiday_rank_level3,
  SUM(CASE WHEN r.academic_split = 'holiday' AND r.rank_level = 4 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_holiday_rank_level4,
  SUM(CASE WHEN r.academic_split = 'holiday' AND r.rank_level = 5 THEN r.distinct_event_count ELSE 0 END) AS phq_rank_academic_holiday_rank_level5
FROM (SELECT date, location FROM saved_locations_daily) data_range
LEFT JOIN events_ranked_distinct r
    ON data_range.date = r.date
        AND data_range.location = r.location
GROUP BY data_range.date, data_range.location
ORDER BY data_range.date, data_range.location
;

SELECT * FROM phq_rank_features order by location, date;

```

{% endcode %}

### Predicted Impact features

The code calculates each value as the MAX of the Ranks of events occurring over each day, showing the highest rank Severe Weather event of each type occurring per day:

{% code title="Predicted Impact features" fullWidth="true" %}

```sql
----Predicted Impact features
CREATE OR REPLACE TEMP TABLE phq_impact_features as
WITH events_impact AS (             --Pull impact events within range
  SELECT DISTINCT
    e.event_id,
    imp.value:date_local::DATE AS date,
    s.location,
    e.category,
    imp.value:value::int AS phq_rank,
    CASE
        WHEN ARRAY_CONTAINS('blizzard'::variant, e.labels) THEN 'blizzard'
        WHEN ARRAY_CONTAINS('snow'::variant, e.labels) THEN 'cold-wave-snow'
        WHEN ARRAY_CONTAINS('cold-wave'::variant, e.labels) AND ARRAY_CONTAINS('storm'::variant, e.labels) THEN 'cold-wave-storm'
        WHEN ARRAY_CONTAINS('cold-wave'::variant, e.labels) THEN 'cold-wave'
        WHEN ARRAY_CONTAINS('air-quality'::variant, e.labels) OR ARRAY_CONTAINS('fog'::variant, e.labels) OR ARRAY_CONTAINS('sand'::variant, e.labels) THEN 'air-quality'
        WHEN ARRAY_CONTAINS('thunderstorm'::variant, e.labels) THEN 'thunderstorm'
        WHEN ARRAY_CONTAINS('tropical-storm'::variant, e.labels) THEN 'tropical-storm'
        WHEN ARRAY_CONTAINS('tornado'::variant, e.labels) THEN 'tornado'
        WHEN ARRAY_CONTAINS('hurricane'::variant, e.labels) OR ARRAY_CONTAINS('cyclone'::variant, e.labels) OR ARRAY_CONTAINS('typhoon'::variant, e.labels) THEN 'hurricane'
        WHEN ARRAY_CONTAINS('dust'::variant, e.labels) AND ARRAY_CONTAINS('storm'::variant, e.labels) THEN 'dust-storm'
        WHEN ARRAY_CONTAINS('dust'::variant, e.labels) THEN 'dust'
        WHEN ARRAY_CONTAINS('rain'::variant, e.labels) OR  ARRAY_CONTAINS('flood'::variant, e.labels) OR ARRAY_CONTAINS('rain'::variant, e.labels) THEN 'flood'
        WHEN ARRAY_CONTAINS('heat-wave'::variant, e.labels) THEN 'heat-wave'
        WHEN ARRAY_CONTAINS('wind'::variant, e.labels) OR  ARRAY_CONTAINS('hazardous-surf'::variant, e.labels) OR ARRAY_CONTAINS('storm'::variant, e.labels) THEN 'dust-storm'
    END AS weather_category
  FROM predicthq.events_0 e
  RIGHT JOIN saved_locations_daily s
    ON ST_DISTANCE(e.geo, ST_MAKEPOINT(s.lon, s.lat)) <=
      CASE
        WHEN s.radius_unit = 'mi' THEN s.radius * 1609.34
        WHEN s.radius_unit = 'km' THEN s.radius * 1000
      END
    AND TO_DATE(CONVERT_TIMEZONE(CASE WHEN e.timezone IS NOT NULL THEN e.timezone ELSE 'UTC' END, e.event_start)) <= s.date
    AND TO_DATE(CONVERT_TIMEZONE(CASE WHEN e.timezone IS NOT NULL THEN e.timezone ELSE 'UTC' END, e.event_end)) >= s.date,
  latERAL FlatTEN(INPUT => IMPACT_PATTERNS) vert,
  latERAL FlatTEN(INPUT => vert.value:impacts) imp
  WHERE vert.value:vertical::STRING = 'retail'
    AND e.category = 'severe-weather'
    AND weather_category IS NOT NULL
 )
SELECT                          --final formatting and select for phq_impact_features
  data_range.date,
  data_range.location,
  IFNULL(MAX(CASE WHEN i.weather_category = 'air-quality' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_air_quality_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'blizzard' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_blizzard_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'cold-wave' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_cold_wave_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'cold-wave-snow' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_cold_wave_snow_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'cold-wave-storm' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_cold_wave_storm_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'dust' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_dust_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'dust-storm' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_dust_storm_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'flood' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_flood_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'heat-wave' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_heat_wave_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'hurricane' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_hurricane_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'thunderstorm' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_thunderstorm_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'tornado' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_tornado_retail,
  IFNULL(MAX(CASE WHEN i.weather_category = 'tropical-storm' THEN i.phq_rank ELSE NULL END),0) AS phq_impact_severe_weather_tropical_storm_retail
FROM (SELECT date, location FROM saved_locations_daily) data_range
LEFT JOIN events_impact i
    ON data_range.date = i.date
        AND data_range.location = i.location
GROUP BY data_range.date, data_range.location
ORDER BY data_range.date, data_range.location
;


SELECT * FROM phq_impact_features order by location, date;
```

{% endcode %}

If you want metrics other than MAX, use the following code as a template for each column. The weather\_category name part of the code (in these examples defaulted to ‘air-quality’) changes depending on which feature you want to call. Refer to the earlier column code for the available weather\_category features:

{% code title="Count" fullWidth="true" %}

```sql
COUNT(CASE WHEN i.weather_category = 'air-quality' THEN i.phq_rank ELSE NULL END)
```

{% endcode %}

{% code title="Average" fullWidth="true" %}

```sql
IFNULL(ROUND(AVG(CASE WHEN i.weather_category = 'air-quality' THEN i.phq_rank ELSE NULL END),2),0)
```

{% endcode %}

{% code title="Median" fullWidth="true" %}

```sql
IFNULL(ROUND(MEDIAN(CASE WHEN i.weather_category = 'air-quality' THEN i.phq_rank ELSE NULL END),2),0)
```

{% endcode %}

{% code title="Standard Deviation" fullWidth="true" %}

```sql
IFNULL(ROUND(STDDEV(CASE WHEN i.weather_category = 'air-quality' THEN i.phq_rank ELSE NULL END),2),0)
```

{% endcode %}

{% code title="Min" fullWidth="true" %}

```sql
IFNULL(MIN(CASE WHEN i.weather_category = 'air-quality' THEN i.phq_rank ELSE NULL END),0)
```

{% endcode %}

{% code title="SUM" fullWidth="true" %}

```sql
SUM(CASE WHEN i.weather_category = 'air-quality' THEN i.phq_rank ELSE 0 END)
```

{% endcode %}

## Step 3: Final select for all features

The following code pulls all the features generated earlier into a single table called **ML\_FEATURES\_FOR\_LOCATIONS**.\
\
Machine Learning models can use this output directly. If unsure what features to use, create a Beam Analysis for the locations. To select features, use the Feature Importance results - see [ML features by location notebook](https://github.com/predicthq/phq-data-science-docs/blob/master/demand-forecasting-with-events/identify-location-level-features-with-beam-api.ipynb). To view all features in one table, use the following code:

{% code title="Combined Table" fullWidth="true" %}

```sql
----Combine Select for viewing all in one
CREATE OR REPLACE TEMP TABLE ml_features_for_locations AS
SELECT
  a.date,
  a.location,
  a.phq_attendance_community,       --Attendance columns
  a.phq_attendance_concerts,
  a.phq_attendance_conferences,
  a.phq_attendance_expos,
  a.phq_attendance_festivals,
  a.phq_attendance_performing_arts,
  a.phq_attendance_sports,
  a.phq_attendance_school_holidays,
  a.phq_attendance_academic_graduation,
  a.phq_attendance_academic_social,
  r.phq_rank_observances_rank_level1,   --Rank Level columns
  r.phq_rank_observances_rank_level2,
  r.phq_rank_observances_rank_level3,
  r.phq_rank_observances_rank_level4,
  r.phq_rank_observances_rank_level5,
  r.phq_rank_public_holidays_rank_level1,
  r.phq_rank_public_holidays_rank_level2,
  r.phq_rank_public_holidays_rank_level3,
  r.phq_rank_public_holidays_rank_level4,
  r.phq_rank_school_holidays_rank_level5,
  r.phq_rank_academic_session_rank_level1,
  r.phq_rank_academic_session_rank_level2,
  r.phq_rank_academic_session_rank_level3,
  r.phq_rank_academic_session_rank_level4,
  r.phq_rank_academic_session_rank_level5,
  r.phq_rank_academic_exam_rank_level1,
  r.phq_rank_academic_exam_rank_level2,
  r.phq_rank_academic_exam_rank_level3,
  r.phq_rank_academic_exam_rank_level4,
  r.phq_rank_academic_exam_rank_level5,
  r.phq_rank_academic_holiday_rank_level1,
  r.phq_rank_academic_holiday_rank_level2,
  r.phq_rank_academic_holiday_rank_level3,
  r.phq_rank_academic_holiday_rank_level4,
  r.phq_rank_academic_holiday_rank_level5,
  i.phq_impact_severe_weather_air_quality_retail,   --Impact columns
  i.phq_impact_severe_weather_blizzard_retail,
  i.phq_impact_severe_weather_cold_wave_retail,
  i.phq_impact_severe_weather_cold_wave_snow_retail,
  i.phq_impact_severe_weather_cold_wave_storm_retail,
  i.phq_impact_severe_weather_dust_retail,
  i.phq_impact_severe_weather_dust_storm_retail,
  i.phq_impact_severe_weather_flood_retail,
  i.phq_impact_severe_weather_heat_wave_retail,
  i.phq_impact_severe_weather_hurricane_retail,
  i.phq_impact_severe_weather_thunderstorm_retail,
  i.phq_impact_severe_weather_tornado_retail,
  i.phq_impact_severe_weather_tropical_storm_retail
FROM phq_attendance_features a
JOIN phq_rank_features r
    ON a.date = r.date
        AND a.location = r.location
JOIN phq_impact_features i
    ON a.date = i.date
        AND a.location = i.location
;

SELECT * FROM ml_features_for_locations ORDER BY location, date;
```

{% endcode %}

The output table should look like this (Note: the example here shows only the first three columns):

<table data-full-width="true"><thead><tr><th width="141">DATE</th><th width="119">LOCATION</th><th>PHQ_ATTENDANCE_COMMUNITY</th><th>PHQ_ATTENDANCE_CONCERTS</th><th>PHQ_ATTENDANCE_CONFERENCES</th></tr></thead><tbody><tr><td>2024-01-01</td><td>Hyde Park</td><td>68</td><td>1,839</td><td>1,578</td></tr><tr><td>2024-01-02</td><td>Hyde Park</td><td>0</td><td>469</td><td>126</td></tr><tr><td>2024-01-03</td><td>Hyde Park</td><td>200</td><td>346</td><td>139</td></tr><tr><td>2024-01-04</td><td>Hyde Park</td><td>0</td><td>2,029</td><td>324</td></tr><tr><td>2024-01-05</td><td>Hyde Park</td><td>120</td><td>691</td><td>238</td></tr></tbody></table>

### Refer back to [main guide](https://docs.predicthq.com/integrations/third-party-integrations/snowflake/snowflake-data-science-guide)


# Receive data via AWS Data Exchange

AWS Data Exchange (ADX) deploys PredictHQ's verified real-world context into your own AWS environment - delivered to S3, where your data warehouse, data science platform, and AI systems already operate. An always-current local dataset that you govern is the foundation for training forecasting models on event features and for [grounding AI systems inside your environment](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding).

PredictHQ provides the data as CSV, JSON, or Parquet in full and incremental exports, and it requires no ELT/ETL pipeline to build or maintain. You can check out the AWS Data Exchange Overview page if you're interested to read more on how AWS Data Exchange works.

## Overview

When integrating with AWS Data Exchange, PredictHQ delivers data as full and incremental file exports. Here’s what you can expect:

* **Initial Full Dump** - Upon setup, you receive a full dataset covering all events you have access to.
* **Incremental Updates** - After the initial dump, we provide incremental updates containing only the new or changed records since the last update. By default, we deliver these updates daily.
* **Occasional Full Dumps** - While incremental updates are the standard, at times (either by request or operational need), we may deliver a full dump without prior notice. You can distinguish these by the presence of `full` (not `incremental`) in the filename.

### Processing order & change action

It is essential to process all ADX revisions in the order they are delivered to maintain a complete and accurate dataset. However, within a revision, the individual files can be processed in any order or in parallel.

For incremental updates, make sure to check the `change_action` column to work out what action you should take the with record (`insert`, `update`, or `delete`).

### File naming

Files use this naming pattern:

```
<delivery_config_id>/<datetime>/<data_type>/<delivery_type>-part-<number>.<ext>
```

<table><thead><tr><th width="282.97265625">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>delivery_config_id</code></td><td>Internal PredictHQ identifier for your ADX configuration.</td></tr><tr><td><code>datetime</code></td><td>This is the date and time the data was exported (UTC).<br><br>Date format: <code>YYYYMMDD-HHMM</code><br>E.g., <code>20250324-0115</code> (24th March, 2025 at 01:15 UTC)</td></tr><tr><td><code>data_type</code></td><td><p>The data being delivered. Can be one of the following:</p><ul><li><code>event</code></li><li><code>broadcast</code></li></ul></td></tr><tr><td><code>delivery_type</code></td><td><p>The delivery is either a full export of all available data or incremental based on the previous export. Possible values:</p><ul><li><code>full</code></li><li><code>incremental</code></li></ul></td></tr><tr><td><code>number</code></td><td>When exporting, PredictHQ separates the data into multiple files to keep the file size small. File sizes vary and range up to 1 GB. Files are not sequential and do not need to be processed sequentially. You are able to process the files in parallel (it's important each ADX revision is processed sequentially, but within a revision, the files can be processed in parallel).</td></tr><tr><td><code>ext</code></td><td><p>The file extension indicates the data structure and compression used.</p><p>If compression is used (configurable) the data is compressed using Snappy and the file extension is prefixed with <code>snappy</code>.</p><p>Possible values:</p><ul><li><code>parquet</code></li><li><code>ndjson</code> - Newline-delimited JSON</li><li><code>csv</code> - Comma separated values</li><li><code>psv</code> - Pipe separated values</li></ul><p><br>E.g., <code>snappy.parquet</code></p></td></tr></tbody></table>

## Samples

The sample data sets are not limited in terms of columns or fields making them valuable for business and data science evaluations. However, these data sets are limited to a specific location and restricted time window that might not suit your use case. These samples therefore represent a small fraction of the data we have available. We also offer Private Listings that match your PredictHQ license.

{% embed url="<https://aws.amazon.com/marketplace/seller-profile?id=b82dc088-06e8-4b0c-9068-42e35f9a099b>" %}
PredictHQ Samples on AWS Data Exchange
{% endembed %}

## Private Listings

We can set up Private Listings to match your PredictHQ license in terms of data type, locations, and time window. We can provide the data in CSV, JSON, or Parquet and configure dumps of data at regular intervals. The files contained in the data set revisions can be automatically copied to S3 where your Data Warehouse (or other data platform) can pick them up.

PredictHQ creates the Private Listing and extends an “offer” to your AWS Account ID which you can then accept to start accessing the data.

Receiving data via an ADX Private Listing is a great alternative to writing code to integrate with our APIs allowing you to get the data you need much faster. Many Data Warehouses, Data Science Platforms, and other data platforms integrate natively with S3 to load data.

[Get in touch](https://www.predicthq.com/contact) with us to discuss your needs and we will come back to you as soon as possible.

## Automatic export to S3

The following video demonstrates how to set up automatic exports of data from AWS Data Exchange to S3.

{% embed url="<https://youtu.be/3sHbO5T45cE>" %}
Setup automatic export of data from AWS Data Exchange to S3
{% endembed %}

## Backwards compatible changes <a href="#backwards-compatible-changes" id="backwards-compatible-changes"></a>

Be aware that we may make backwards compatible changes to the exports from time-to-time. Examples of some changes we might make that don't break backwards compatibility and may be introduced at any time without warning:

* New columns/fields added to existing files.
* New files in addition to existing files.
* New event categories and labels.


# CSV/Parquet data structure for ADX

Data can be provided as NDJSON, CSV, or Parquet. This document describes the CSV/Parquet data structure.

<table data-full-width="true"><thead><tr><th width="387.744140625">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>EVENT_ID</code></td><td>The unique identifier of the event.</td></tr><tr><td><code>CREATE_DT</code></td><td>The date and time PredictHQ first saw the event, in UTC. Also called <code>first_seen</code> in the Events API.</td></tr><tr><td><code>UPDATE_DT</code></td><td>The date and time the event was last updated in UTC.</td></tr><tr><td><code>TITLE</code></td><td>The title of the event.</td></tr><tr><td><code>CATEGORY</code></td><td>The category of the event.</td></tr><tr><td><code>LABELS</code></td><td>The labels associated with the event. The <code>LABELS</code> field is representing PredictHQ's legacy labels, and we suggest using the <code>PHQ_LABELS</code> field instead where possible.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/labels">Labels</a> docs.</td></tr><tr><td><code>DESCRIPTION</code></td><td>The description of the event.</td></tr><tr><td><code>EVENT_START</code></td><td><p>The date and time the event starts, recorded in UTC. If the <code>TIMEZONE</code> field is null, the time represents the same relative time across all timezones.</p><p>Additionally, if an event has a start time of midnight in its local timezone, this may indicate that the actual time is unknown. You may wish to omit the time when displaying such events.</p></td></tr><tr><td><code>EVENT_END</code></td><td>The date and time the event ends, recorded in UTC. If the <code>TIMEZONE</code> field is null, the time represents the same relative time across all timezones.</td></tr><tr><td><code>PREDICTED_END</code></td><td>The date and time PredictHQ predicts the event will end, recorded in UTC. If the <code>TIMEZONE</code> field is null, the time represents the same relative time across all timezones. This value is present where an actual <code>EVENT_END</code> is unknown.</td></tr><tr><td><code>TIMEZONE</code></td><td>The time zone of the event in TZ Database format. This is helpful so you know which time zone to convert the dates to (if needed). If the time zone is <code>null</code>, the start and end date should be regarded as time zone agnostic and already being in local time.</td></tr><tr><td><code>ENTITIES</code></td><td>An array of entities linked to the event. This is a complex data type, see <a href="https://docs.predicthq.com/api/events/search-events">Events API</a> for details.</td></tr><tr><td><code>GEO</code></td><td>The geographic details (location) of the event in GeoJSON format.<br><br>See <a href="https://docs.predicthq.com/getting-started/guides/geolocation-guides">geolocation guides</a> for more information on handling <code>GEO</code> data.</td></tr><tr><td><code>IMPACT_PATTERNS</code></td><td>Also known as “Predicted Impact Patterns”. This field shows impact for leading days (days before the event), lagging days (days after an event), and the days the event occurs. It contains details such as the industry vertical the impact pattern applies to, the type of impact shown in the impact pattern, and an array of objects for each day showing the date in the local timezone of the event and the value of the impact_type for that given day.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns">Predicted Impact Patterns</a> docs.</td></tr><tr><td><code>SCOPE</code></td><td><p>The geographical scope the events apply to. Possible values are:</p><ul><li><code>locality</code></li><li><code>localadmin</code></li><li><code>county</code></li><li><code>region</code></li><li><code>country</code></li></ul></td></tr><tr><td><code>PLACEKEY</code></td><td>The Placekey identifier for the physical address where the event takes place. See <a href="https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-placekey">Placekey</a>. This field is <code>null</code> if the "What" part or the "Where" part of the Placekey for the event address couldn't be retrieved.</td></tr><tr><td><code>COUNTRY_CODE</code></td><td>The country code in ISO 3166-1 alpha 2 format. This value is typically present, but in some cases such as events occurring outside any country (e.g. an earthquake in the middle of the ocean), it may be empty.</td></tr><tr><td><code>PLACE_HIERARCHIES</code></td><td><p>An array of place hierarchies for the event. Each hierarchy is an array of place ids. The final place in a hierarchy is a specific place the event applies to. Each place is a sub-place of the place immediately preceding it in the hierarchy. An empty array is possible and valid.</p><p>See also the <a href="https://docs.predicthq.com/getting-started/guides/geolocation-guides/understanding-place-hierarchies">Place Hierarchies guide</a>.</p></td></tr><tr><td><code>PHQ_ATTENDANCE</code></td><td><p>A numerical value that reflects the Predicted Attendance for supported attendance-based categories. Supported categories include concerts, performing arts, sports, expos, conferences, community, and festivals. Some academic and school holiday events may also include a phq_attendance value to indicate student numbers.</p><p>For multi-day events, phq_attendance represents total attendance across the entire duration, except for certain categories like conferences, where it reflects daily attendance.</p><p>For details see our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-attendance">Predicted Attendance guide</a>.</p></td></tr><tr><td><code>PHQ_RANK</code></td><td><p>A log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. It is designed to represent the potential impact of an event independent of its geographical location.</p><p>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/ranks/phq-rank">PHQ Rank docs</a>.</p></td></tr><tr><td><code>LOCAL_RANK</code></td><td><p>Similar to PHQ Rank, this is a log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. It is designed to represent the potential impact of an event on its local geographical area.</p><p>PredictHQ calculates Local Rank for all events.</p><p>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/ranks/local-rank">Local Rank docs</a>.</p></td></tr><tr><td><code>AVIATION_RANK</code></td><td><p>A log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. Aviation Rank indicates how much an event will impact flight bookings by considering both domestic and international travel.</p><p>Aviation Rank has been deprecated.</p></td></tr><tr><td><code>STATUS</code></td><td><p>The publication state of the event.</p><p>Possible values:</p><ul><li><code>active</code> - The event is an active event.</li><li><code>postponed</code> - The event is a postponed event, and is expected to occur at a later date.</li><li><code>cancelled</code> - The event is a canceled event and is not expected to occur at a later date.</li><li><code>predicted</code> - The event is a predicted event. For details, see our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-events">Predicted Events page</a>.</li></ul></td></tr><tr><td><code>BRAND_SAFE</code></td><td>Whether or not this event is considered brand-safe. Examples of brand-unsafe events include content that promotes hate, violence, or discrimination, coarse language, content that is sexually suggestive or explicit, etc.</td></tr><tr><td><code>PARENT_EVENT_ID</code></td><td>Used to indicate if this event is part of a larger event. These types of events are called umbrella events in the system. For example, a large multi-day parent umbrella event may have individual child events for sessions on different days. This field only shows if a child event has a parent id. It does not indicate if a parent event has child events. For details see our <a href="https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-multi-day-and-umbrella-events">Umbrella Events docs</a>.</td></tr><tr><td><code>CANCELLED_DT</code></td><td>The date and time the event was marked as canceled, presented in the UTC timezone. This field is null if <code>STATUS</code> is not set to "cancelled" or if the cancellation date is unavailable.</td></tr><tr><td><code>POSTPONED_DT</code></td><td>The date and time the event was marked as postponed, presented in the UTC timezone. This field is null if <code>STATUS</code> is not set to "postponed" or if the postponement date is unavailable. Note that this field does not represent the new date and time of the postponed event.</td></tr><tr><td><code>PREDICTED_EVENT_SPEND_TOTAL</code></td><td>The total Predicted Event Spend (USD) across all supported industries: accommodation, hospitality, and transportation. This field is <code>null</code> if the Predicted Event Spend is not supported for this event.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-event-spend">Predicted Event Spend</a> docs.</td></tr><tr><td><code>PREDICTED_EVENT_SPEND_ACCOMMODATION</code></td><td>The total Predicted Event Spend (USD) for the accommodation industry. This field is <code>null</code> if the Predicted Event Spend is not supported for this event.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-event-spend">Predicted Event Spend</a> docs.</td></tr><tr><td><code>PREDICTED_EVENT_SPEND_HOSPITALITY</code></td><td>The total Predicted Event Spend (USD) for the hospitality industry. This field is <code>null</code> if the Predicted Event Spend is not supported for this event.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-event-spend">Predicted Event Spend</a> docs.</td></tr><tr><td><code>PREDICTED_EVENT_SPEND_TRANSPORTATION</code></td><td>The total Predicted Event Spend for the transportation industry. This field is <code>null</code> if the Predicted Event Spend is not supported for this event.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-event-spend">Predicted Event Spend</a> docs.</td></tr><tr><td><code>PHQ_LABELS</code></td><td>The PHQ Labels associated with the event. This field is <code>null</code> if there are no PHQ Labels for this event.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/labels">Labels</a> docs.</td></tr><tr><td><code>ALTERNATE_IDS</code></td><td>All alternate IDs for the event. Any event IDs that may have been used for this event in the past are included here. It does not include the current event ID.</td></tr><tr><td><code>EVENT_START_LOCAL</code></td><td>The date and time when the event begins, expressed in the event's local time zone.</td></tr><tr><td><code>EVENT_END_LOCAL</code></td><td>The date and time when the event ends, expressed in the event's local time zone.</td></tr><tr><td><code>PREDICTED_END_LOCAL</code></td><td>The date and time when the event is predicted to end, expressed in the event's local time zone.</td></tr><tr><td><code>REGION</code></td><td>The region in which the event will be occurring. This field is <code>null</code> if the event covers more than a single region.</td></tr><tr><td><code>LOCALITY</code></td><td>The locality in which the event will be occurring. A locality is most commonly referred to as a city or town. This field is <code>null</code> if the event covers more than a single locality.</td></tr><tr><td><code>POSTCODE</code></td><td>The postal code or ZIP code in which the event will be occurring. This field is <code>null</code> if the event covers more than a single post code.</td></tr><tr><td><code>FORMATTED_ADDRESS</code></td><td>A full formatted address which can include street addresses, locality, postcode, region, and country.</td></tr><tr><td><code>ROW_INSERTED_DT</code></td><td>The date and time this row was inserted in UTC. The row may have been deleted and inserted multiple times so it does not reflect when an event is first seen, use <code>CREATE_DT</code> for that.</td></tr><tr><td><code>ROW_UPDATED_DT</code></td><td>The date and time this row was last updated in UTC.</td></tr><tr><td><code>CHANGE_ACTION</code></td><td><p>Indicates if the record has been updated, deleted, or inserted. Use when processing the data file to keep your database updated.</p><p>Possible values:</p><ul><li><code>insert</code> - new record, not previously seen.</li><li><code>update</code> - existing record, updated values.</li><li><code>delete</code> - deleted record, remove from your dataset.</li></ul></td></tr></tbody></table>


# NDJSON data structure for ADX

Data can be provided as NDJSON, CSV or Parquet. This document describes the NDJSON data structure.

<table data-full-width="true"><thead><tr><th width="368.5">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>The unique identifier of the event.</td></tr><tr><td><code>parent_event</code></td><td>Used to indicate if this event is part of a larger event. These types of events are called umbrella events in the system. For example, a large multi-day parent umbrella event may have individual child events for sessions on different days. This field only shows if a child event has a parent id. It does not indicate if a parent event has child events. For details see our <a href="https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-multi-day-and-umbrella-events">Umbrella Events docs</a>.</td></tr><tr><td><code>title</code></td><td>The title of the event.</td></tr><tr><td><code>description</code></td><td>The description of the event.</td></tr><tr><td><code>category</code></td><td>The category of the event.</td></tr><tr><td><code>labels</code></td><td>The labels associated with the event. The <code>labels</code> field is representing PredictHQ's legacy labels, and we suggest using the <code>phq_labels</code> field instead where possible.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/labels">Labels</a> docs.</td></tr><tr><td><code>rank</code></td><td><p>A log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. It represents the potential impact of an event independent of its geographical location.</p><p>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/ranks/phq-rank">PHQ Rank docs</a>.</p></td></tr><tr><td><code>local_rank</code></td><td><p>Similar to PHQ Rank, this is a log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. It is designed to represent the potential impact of an event on its local geographical area.</p><p>PredictHQ calculates Local Rank for all events.</p><p>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/ranks/local-rank">Local Rank docs</a>.</p></td></tr><tr><td><code>aviation_rank</code></td><td><p>A log scale numerical value between 0 and 100 with a five-level hierarchical impact schema. Aviation Rank indicates how much an event will impact flight bookings by considering both domestic and international travel.</p><p>Aviation Rank has been deprecated.</p></td></tr><tr><td><code>phq_attendance</code></td><td><p>A numerical value that reflects the Predicted Attendance for supported attendance-based categories. Supported categories include concerts, performing arts, sports, expos, conferences, community, and festivals. Some academic and school holiday events may also include a phq_attendance value to indicate student numbers.</p><p>For multi-day events, phq_attendance represents total attendance across the entire duration, except for certain categories like conferences, where it reflects daily attendance.</p><p>For details see our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-attendance">Predicted Attendance guide</a>.</p></td></tr><tr><td><code>entities</code></td><td>An array of entities linked to the event. This is a complex data type, see <a href="https://docs.predicthq.com/api/events/search-events">Events API</a> for details.</td></tr><tr><td><code>duration</code></td><td>The difference in seconds between the event <code>start</code> and the event <code>end</code>.</td></tr><tr><td><code>start</code></td><td><p>The date and time the event starts, recorded in UTC. If the timezone is not considered relevant (e.g., Independence Day), PredictHQ stores the time in UTC to represent the same relative time across all timezones, and the <code>timezone</code> field is null.</p><p>Additionally, if an event has a start time of midnight in its local timezone, this may indicate that the actual time is unknown. You may wish to omit the time when displaying such events</p></td></tr><tr><td><code>end</code></td><td>The date and time the event ends, recorded in UTC. If the timezone is not considered relevant (e.g., Independence Day), PredictHQ stores the time in UTC to represent the same relative time across all timezones, and the <code>timezone</code> field is null.</td></tr><tr><td><code>updated</code></td><td>The date and time the event was last updated in UTC.</td></tr><tr><td><code>first_seen</code></td><td>The date and time PredictHQ first saw the event, in UTC. Also called <code>first_seen</code> in the Events API.</td></tr><tr><td><code>timezone</code></td><td>The time zone of the event in TZ Database format. This is helpful so you know which time zone to convert the dates to (if needed). If the time zone is <code>null</code>, the start and end date should be regarded as time zone agnostic and already being in local time.</td></tr><tr><td><code>geo</code></td><td>The geographic details (location) of the event in GeoJSON format.<br><br>See <a href="https://docs.predicthq.com/getting-started/guides/geolocation-guides">geolocation guides</a> for more information on handling <code>geo</code> data.</td></tr><tr><td><code>impact_patterns</code></td><td>Also known as “Predicted Impact Patterns”. This field shows impact for leading days (days before the event), lagging days (days after an event), and the days the event occurs. It contains details such as the industry vertical the impact pattern applies to, the type of impact shown in the impact pattern, and an array of objects for each day showing the date in the local timezone of the event and the value of the impact_type for that given day.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns">Predicted Impact Patterns</a> docs.</td></tr><tr><td><code>scope</code></td><td><p>The geographical scope the events apply to. Possible values are:</p><ul><li><code>locality</code></li><li><code>localadmin</code></li><li><code>county</code></li><li><code>region</code></li><li><code>country</code></li></ul></td></tr><tr><td><code>placekey</code></td><td>The Placekey identifier for the physical address where the event takes place. See <a href="https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-placekey">Placekey</a>. This field will be <code>null</code> if the "What" part or the "Where" part of the Placekey for the event address couldn't be retrieved.</td></tr><tr><td><code>country</code></td><td>The country code in ISO 3166-1 alpha 2 format. This value is typically present, but in some cases such as events occurring outside any country (e.g. an earthquake in the middle of the ocean), it may be empty.</td></tr><tr><td><code>place_hierarchies</code></td><td><p>An array of place hierarchies for the event. Each hierarchy is an array of place ids. The final place in a hierarchy is a specific place the event applies to. Each place is a sub-place of the place immediately preceding it in the hierarchy. An empty array is possible and valid.</p><p>See also the <a href="https://docs.predicthq.com/getting-started/guides/geolocation-guides/understanding-place-hierarchies">Place Hierarchies guide</a>.</p></td></tr><tr><td><code>state</code></td><td><p>The publication state of the event.</p><p>Possible values:</p><ul><li><code>active</code> - The event is an active event.</li><li><code>postponed</code> - The event is a postponed event, and is expected to occur at a later date.</li><li><code>cancelled</code> - The event is a canceled event and is not expected to occur at a later date.</li><li><code>predicted</code> - The event is a predicted event. For details, see our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-events">Predicted Events page</a>.</li></ul></td></tr><tr><td><code>brand_safe</code></td><td>Whether or not this event is considered brand-safe. Examples of brand-unsafe events include content that promotes hate, violence, or discrimination, coarse language, content that is sexually suggestive or explicit, etc.</td></tr><tr><td><code>cancelled</code></td><td>The date and time the event was marked as canceled, presented in the UTC timezone. This field will be null if <code>state</code> is not set to "cancelled" or if the cancellation date is unavailable.</td></tr><tr><td><code>postponed</code></td><td>The date and time the event was marked as postponed, presented in the UTC timezone. This field will be null if <code>state</code> is not set to "postponed" or if the postponement date is unavailable. Note that this field does not represent the new date and time of the postponed event.</td></tr><tr><td><code>predicted_event_spend</code></td><td>The total Predicted Event Spend (USD) across all supported industries: accommodation, hospitality, and transportation. This field is <code>null</code> if Predicted Event Spend is not supported for this event.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-event-spend">Predicted Event Spend</a> docs.</td></tr><tr><td><code>predicted_event_spend_industries</code></td><td>A breakdown of Predicted Event Spend (USD) into the three supported industries: accommodation, hospitality, and transportation. This field will be <code>null</code> if Predicted Event Spend is not supported for this event.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/predicted-event-spend">Predicted Event Spend</a> docs.</td></tr><tr><td><code>phq_labels</code></td><td>The PHQ Labels associated with the event. This field will be <code>null</code> if there are no PHQ Labels for this event.<br><br>See also our <a href="https://docs.predicthq.com/getting-started/predicthq-data/labels">Labels</a> docs.</td></tr><tr><td><code>predicted_end</code></td><td>The date and time PredictHQ predicts the event will end, recorded in UTC. If the <code>timezone</code> field is null, the time represents the same relative time across all timezones. This value is present where an actual <code>timezone</code> is unknown.</td></tr><tr><td><code>alternate_ids</code></td><td>All alternate IDs for the event. Any event IDs that this event has used in the past are included here. It does not include the current event ID.</td></tr><tr><td><code>start_local</code></td><td>The date and time when the event begins, expressed in the event's local time zone.</td></tr><tr><td><code>end_local</code></td><td>The date and time when the event ends, expressed in the event's local time zone.</td></tr><tr><td><code>predicted_end_local</code></td><td>The date and time when the event is predicted to end, expressed in the event's local time zone.</td></tr><tr><td><code>region</code></td><td>The region in which the event will be occurring. This field can be <code>null</code> if the event covers more than a single region.</td></tr><tr><td><code>locality</code></td><td>The locality in which the event will be occurring. A locality is most commonly referred to as a city or town. This field can be <code>null</code> if the event covers more than a single locality.</td></tr><tr><td><code>postcode</code></td><td>The postal code or ZIP code in which the event will be occurring. This field can be <code>null</code> if the event covers more than a single post code.</td></tr><tr><td><code>formatted_address</code></td><td>A full formatted address which can include street addresses, locality, postcode, region, and country.</td></tr><tr><td><code>change_action</code></td><td><p>Indicates if the record has been updated, deleted, or inserted. Use when processing the data file to keep your database updated.</p><p>Possible values:</p><ul><li><code>insert</code> - new record, not previously seen.</li><li><code>update</code> - existing record, updated values.</li><li><code>delete</code> - deleted record, remove from your dataset.</li></ul></td></tr></tbody></table>


# Receive data via SFTP

PredictHQ can deliver Event and Broadcast data via SFTP as regularly updated files - deploying verified real-world context into your environment when Snowflake or AWS Data Exchange aren't options. The result is the same: an always-current local store for model training, explainability, and [provisioned grounding](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding), which you govern.

SFTP delivery follows the same full + incremental data model used by our other bulk data integrations.

## Overview

When integrating via SFTP, PredictHQ delivers data as full and incremental file exports (same delivery model as our AWS Data Exchange exports). Here’s what you can expect:

* **Initial Full Dump**: upon setup, you receive a full dataset covering all records you have access to.
* **Incremental Updates**: after the initial dump, we provide incremental updates containing only the new or changed records since the last update. By default, PredictHQ delivers these updates daily.
* **Occasional Full Dumps**: at times (either by request or operational need), we may deliver a full dump without prior notice. You can distinguish these by the presence of full (not incremental) in the filename.

## Processing order and change action

To maintain a complete and accurate dataset, process deliveries in the order PredictHQ delivers them (typically by the datetime folder, oldest to newest). Within a single delivery, you can process the individual files in any order or in parallel.

For incremental updates, make sure to check the `change_action` column to work out what action you should take the with record (`insert`, `update`, or `delete`).

### File naming

PredictHQ names files using this pattern:

```
<delivery_config_id>/<datetime>/<data_type>/<delivery_type>-part-<number>.<ext>
```

<table><thead><tr><th width="282.97265625">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>delivery_config_id</code></td><td>PredictHQ identifier for your delivery configuration.</td></tr><tr><td><code>datetime</code></td><td>UTC export timestamp in <code>YYYYMMDD-HHMM</code> format.</td></tr><tr><td><code>data_type</code></td><td><p>The data being delivered. Can be one of the following:</p><ul><li><code>event</code></li><li><code>broadcast</code></li></ul></td></tr><tr><td><code>delivery_type</code></td><td><p>The delivery is either a full export of all available data or incremental based on the previous export. Possible values:</p><ul><li><code>full</code></li><li><code>incremental</code></li></ul></td></tr><tr><td><code>number</code></td><td><p>PredictHQ splits each delivery into multiple files to keep file sizes manageable. Individual files vary in size but don't exceed approximately 1 GB.</p><p>Files within a single delivery are not ordered and do not need to be processed sequentially. They can be processed in parallel. However, you must process deliveries themselves in chronological order to ensure data consistency.</p></td></tr><tr><td><code>ext</code></td><td><p>The file extension indicates the data structure and compression used.</p><p>If compression is used (configurable) PredictHQ compresses the data using Snappy and the file extension is prefixed with <code>snappy</code>.</p><p>Possible values:</p><ul><li><code>parquet</code></li><li><code>ndjson</code> - Newline-delimited JSON</li><li><code>csv</code> - Comma separated values</li><li><code>psv</code> - Pipe separated values</li></ul><p><br>E.g., <code>snappy.parquet</code></p></td></tr></tbody></table>

Within a single delivery, files can be processed in any order. Process deliveries themselves oldest to newest.

## Data retention

The SFTP server retains files for a limited period and automatically deletes them after that period.

Your ingestion process should fetch and persist data promptly. Do not rely on long-term availability of files on the SFTP server.

## Access and authentication

PredictHQ provides:

* An SFTP URL
* A private SSH key for authentication

You use these credentials to connect to the PredictHQ-managed SFTP server and fetch data on your own schedule.

## Typical ingestion flow

Implement an automated process with these steps:

1. Connect to the SFTP server.
2. List the available delivery folders.
3. Select the next unprocessed delivery.
4. Download all files for that delivery.
5. For incremental deliveries, apply records in order using `change_action`.
6. In your own system, record the delivery as processed.

## Backwards compatible changes <a href="#backwards-compatible-changes" id="backwards-compatible-changes"></a>

From time to time, PredictHQ may make backwards-compatible changes to SFTP exports, including:

* Adding new fields or columns
* Adding new files alongside existing ones
* Introducing new event categories or labels

Your ingestion process should tolerate these changes.


# Integrate with Databricks

Deploy PredictHQ's verified real-world context into Databricks via S3 or Snowflake for model training, inference-time features, and grounding AI systems.

Databricks is where many teams train demand forecasting models and build AI systems - and both jobs need verified real-world context in the lakehouse. PredictHQ data lands in Databricks through two natively supported paths, both continuously updated and neither requiring a custom pipeline:

* **AWS Data Exchange to S3** - full and incremental exports [delivered to S3](https://docs.predicthq.com/integrations/third-party-integrations/aws-data-exchange), which Databricks reads directly.
* **Snowflake shared tables** - a [Secure Data Share](https://docs.predicthq.com/integrations/third-party-integrations/snowflake) queried from Databricks over the native Snowflake connector.

[Get in touch](https://www.predicthq.com/contact) with us to set up delivery via ADX or Snowflake. PredictHQ can also deliver Features API output per Beam Analysis through the same channels, so model-ready features arrive alongside the event records.

Once landed, the data serves each integration path:

* **Model training** - join event features to your demand history and train in your existing Databricks ML workflow. Key features by `beam.analysis_id`, so feature selection reflects what actually drives demand at each location.
* **Inference** - retrieve future-dated features at every forecast run. [Pre-trained time series foundation models](https://docs.predicthq.com/getting-started/guides/features-api-guides/using-event-features-with-time-series-foundation-models) consume features as covariates across both the demand history and the forecast horizon.
* **Provisioned grounding** - the event tables double as the retrieval corpus for LLMs and agents built on Databricks, so AI systems answer from verified real-world context that your own platform governs - see [provisioned grounding](https://docs.predicthq.com/integrations/integration-guides/provisioned-grounding).

Databricks resources for reading data from S3 or Snowflake:

{% embed url="<https://docs.databricks.com/en/storage/amazon-s3.html>" %}

{% embed url="<https://docs.databricks.com/en/external-data/amazon-s3-select.html>" %}

{% embed url="<https://docs.databricks.com/en/external-data/snowflake.html>" %}


# Using event data in Tableau

Learn how to connect PredictHQ data to Tableau and build an example dashboard.

PredictHQ provides verified real-world events that impact key business operations, including demand forecasting and strategic planning. This tutorial shows how to connect PredictHQ to Tableau to visualize how events influence business trends - loading a static event export, and connecting directly to data warehouses where PredictHQ data is stored.

## Getting started

This tutorial requires access to both Tableau and PredictHQ:

1. Tableau: The instructions provided are based on [Tableau Public](https://public.tableau.com/app/discover), but other Tableau products, such as Tableau Desktop, should operate similarly.
2. PredictHQ: To download a static export of PredictHQ data, a [PredictHQ account](https://signup.predicthq.com/) is required.

## Connection with JSON file

Tableau supports [various methods](https://help.tableau.com/current/pro/desktop/en-us/exampleconnections_overview.htm) for connecting to data sources, including local files and data warehouses. This tutorial focuses on connecting to PredictHQ data via a [JSON file](https://help.tableau.com/current/pro/desktop/en-us/examples_json.htm).

Connecting via a JSON file in Tableau involves downloading a static snapshot of event data through bulk exporting from PredictHQ's WebApp. It is particularly useful for scenarios where real-time data updates are not essential. Ideal for testing or one-off analyses, this approach provides an efficient way to get started with event data in Tableau. This is a good way to try PredictHQ's data for the first time and explore how it can be useful in your business.

A JSON file export contains a structured list of events, much like a CSV export, but with better handling of nested data. While Tableau also [supports CSV file connections](https://help.tableau.com/current/pro/desktop/en-us/examples_text.htm), accessing nested data, such as [Predicted Impact Patterns](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns), is more challenging. In contrast, Tableau's native support for JSON files simplifies the integration and manipulation of nested information, making it the preferred method for connecting PredictHQ data.

### Export file

**Search Events**

To export events from the WebApp:

1. Access our WebApp: Log in and navigate to [Search events](https://control.predicthq.com/search/events).
2. Configure Filters: Set relevant filters, such as those for category, date, and location, and then click **Search**.

> **Example Search**
>
> To view all [attendance-based events](https://docs.predicthq.com/getting-started/predicthq-data/event-categories/attendance-based-events) in San Francisco scheduled or predicted to take place in May 2024, use the following URL with pre-configured filters:
>
> [San Francisco attendance-based events search for May 2024](https://control.predicthq.com/search/events?category=conferences,expos,concerts,festivals,performing-arts,community,sports\&place.scope=5391959\&active.gte=2024-05-01\&active.lte=2024-05-31\&state=active,predicted\&sort=phq_attendance,-start\&t=1716862100079)

{% hint style="info" %}
For guidance on finding the most relevant events for your business, see [Filtering and finding relevant events](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events). For searches around specific locations or stores, we recommend exporting a JSON file from our WebApp [Saved Locations](https://control.predicthq.com/location-insights).
{% endhint %}

**Export as JSON**

To export the events as a JSON file:

3. Export Events: Once the events of interest are displayed on our WebApp's Search, click **Export** and then **Export Events Data**.
4. Select Format: In the dialog box that appears, select the **JSONL** tab.
5. Start Export: In the dialog box, click **Export**.

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXcvQzusKN7PGRgRBq2QZ7AMtb-3r3k3B4Y4HRW3TDPYA1AZNt1fqiMprRB-prb9CiL3rTOe-7oH0z7aNEN_1rjPXY1GesmiVng0kjAUP3bC_S1Vg8OSBCsSv7qfvROnQnkHeJ_5RDWXCbm-TOSSK7DPieQ?key=Vi0_07VB32pOkrxgXfeY_A" alt="The Export Events dialog box in the WebApp with the JSONL tab and the Export button" width="375"><figcaption><p>Export Events dialog box</p></figcaption></figure>

6. Download Link: When the export is ready, in the dialog box, click the download link. PredictHQ also sends the link by email.
7. Save Export: To use the export later, download the file and save it to a directory.

### Connect in Tableau

**Connect to file**

To load the export file in Tableau:

1. Start Tableau: Open Tableau and under **Connect** select **JSON file**.
2. Locate File: In the file dialog, complete these actions:
   1. Navigate to the directory where you saved the export.
   2. If the JSON lines file isn't listed, change the file extension filter from **JSON Files (\*.json)** to **All Files (\*.\*)**.
   3. To load the file, click **Open**.

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXeYM6sCSxWnNn4WT6rinrcHl_oqGIeunmUmlT2IgZwwugm0XhASIhcRj1ucG_aoomHbEi3SH0TTjbLeM689xM_C8qRcE4He-BLQiq_VKdKfHXWMswwJnE3vJUaCs5kFV1FBXRPgGPpj1r5daiqa5oB03qxx?key=Vi0_07VB32pOkrxgXfeY_A" alt="Tableau file dialog with the file type options for selecting the JSONL export" width="375"><figcaption><p>File extension options</p></figcaption></figure>

{% hint style="info" %}
For more information on connecting a local JSON file to Tableau and setting up the data source, see the [Tableau guide to connecting a JSON file](https://help.tableau.com/current/pro/desktop/en-us/examples_json.htm).
{% endhint %}

**Flatten nested JSON**

To flatten the nested JSON:

3. Select Schema Levels: When the file is loaded, the **Select Schema Levels** dialog box should automatically appear. You can also modify the schema levels by following the [steps to change schema levels](https://help.tableau.com/current/pro/desktop/en-us/examples_json.htm#change-schema-levels). To ensure the data is structured correctly for this tutorial, select the following schema levels or follow the [steps to change schema levels](https://help.tableau.com/current/pro/desktop/en-us/examples_json.htm#change-schema-levels):

   1. **Root Level**: Typically named after the JSON file e.g. `Events-Export-…`
   2. **Predicted Impact Patterns**: Includes data related to Predicted Impact Patterns.
   3. **Impacts**: Details specific impact values for each day.

   <figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXdLRxDH6Zq-2jnUoQwltqqWhrpBN2UeamCuAJkjk02RHxx-V_It0GgKe-cl-PKax5O5zPnD6i1QSlyggRFzrsZhBjArKOCHbWJ43Qabi_UUbyy2JJ4YoP2JlMlJVRbEa57SQBiWXlW2dTubdGh2jY1BtE5P?key=Vi0_07VB32pOkrxgXfeY_A" alt="Tableau dialog for selecting the JSON schema levels to import" width="375"><figcaption><p>Schema levels to select</p></figcaption></figure>

{% hint style="info" %}
For more information on schema levels, see the [Tableau guide to schema levels](https://help.tableau.com/current/pro/desktop/en-us/examples_json.htm#select-schema-level).
{% endhint %}

**Update data types**

To update the data types:

* Check Data Types: Tableau automatically interprets a field's data type but this is not always correct. Review and adjust the data type where necessary by following the [steps to change a field's data type](https://help.tableau.com/current/pro/desktop/en-us/datafields_typesandroles_datatypes.htm#change-the-data-type-for-a-field-in-the-data-source-page), ensuring the following fields are set correctly for this tutorial:

| Field         | Correct Data Type              |
| ------------- | ------------------------------ |
| `End Local`   | Date & Time                    |
| `Date Local`  | Date                           |
| `Start Local` | Date & Time                    |
| `State`       | String (Geographic Role: None) |

{% hint style="info" %}
For more information on data types, see the [Tableau guide to data types](https://help.tableau.com/current/pro/desktop/en-us/datafields_typesandroles_datatypes.htm).
{% endhint %}

## Dashboard with event data

This section guides you through creating a simple dashboard in Tableau, featuring a time series chart of daily event impact derived from [Predicted Impact Patterns](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns) and a table listing relevant events. You connect PredictHQ data via a JSON file.

### Worksheets

**Chart**

To create the chart:

1. New Worksheet: [Open a new worksheet](https://help.tableau.com/current/pro/desktop/en-us/environ_workbooksandsheets.htm#create-new-worksheets-dashboards-or-stories) and name it 'Time Series'.
2. Set Filters: To refine the data for events of interest only, use filters. On the **Filters** shelf, [drag the following fields](https://help.tableau.com/current/pro/desktop/en-us/filtering.htm#drag-dimensions-measures-and-date-fields-to-the-filters-shelf):

<table data-full-width="false"><thead><tr><th width="174">Folder</th><th width="153">Field</th><th>Dialog Box</th></tr></thead><tbody><tr><td>Event-Export-...</td><td><code>State</code></td><td><p>Filter [State]:</p><ol><li>Under <strong>General</strong> and <strong>Select from list</strong>, check <code>active</code> and <code>predicted</code>.</li><li>Click <strong>OK</strong>.</li></ol><p>Notes:</p><ul><li>This filter is necessary unless you have already filtered these states in our WebApp Search.</li></ul></td></tr><tr><td>Event-Export-...</td><td><code>Category</code></td><td><p>Filter [Category]:</p><ol><li>Under <strong>General</strong> and <strong>Select from list</strong>, check <code>community</code>, <code>concerts</code>, <code>conferences</code>, <code>expos</code>, <code>festivals</code>, <code>performing-arts</code>, <code>sports</code>.</li><li>Click <strong>OK</strong>.</li></ol><p>Notes:</p><ul><li>This filter is necessary unless you have already filtered these categories in our WebApp Search.</li></ul></td></tr><tr><td>Predicted Impact Patterns</td><td><code>Vertical</code></td><td><p>Filter [Vertical]:</p><ol><li>Under <strong>General</strong> and <strong>Select from list</strong>, check an industry e.g. <code>accommodation</code>.</li><li>Click <strong>OK</strong>.</li></ol><p>Note:</p><ul><li><code>Vertical</code> is the industry vertical associated with the Predicted Impact Pattern.</li><li>This tutorial focuses on event day impact, which is the same for all industries.</li><li>Choose any available industry if yours is not available.</li></ul></td></tr><tr><td>Impacts</td><td><code>Date Local</code></td><td><p>Filter Field [Date Local]:</p><ul><li>Select <strong>Range of Dates</strong>, and then click <strong>Next</strong>.</li></ul><p>Filter [Date Local]:</p><ol><li>Set the minimum and maximum dates to '01/05/2024' and '31/05/2024', respectively.</li><li>Click <strong>OK</strong>.</li></ol><p>Notes:</p><ul><li><code>Date Local</code> is the date in the local time zone.</li></ul></td></tr><tr><td>Impacts</td><td><code>Position</code></td><td><p>Filter [Position]:</p><ol><li>Under <strong>General</strong> and <strong>Select from list</strong>, check <strong>event_day</strong>.</li><li>Click <strong>OK</strong>.</li></ol><p>Notes:</p><ul><li><code>Position</code> categorizes <code>Date</code> Local in relation to when the event takes place, such as before, during, or after the event.</li><li>While this tutorial focuses on the impact during event days, exploring impacts on other days is also encouraged.</li></ul></td></tr></tbody></table>

{% hint style="info" %}
For more information on PredictHQ event fields, see [Events](https://docs.predicthq.com/api/events/search-events).
{% endhint %}

3. Apply Filters Globally: To apply the filters you set earlier to **All worksheets using this data source**, right-click each field in the **Filters** shelf and follow the [steps to apply filters to all worksheets](https://help.tableau.com/current/pro/desktop/en-us/filtering_global.htm#apply-filters-to-all-worksheets-that-use-the-current-primary-data-source). This prevents the need to repeat configurations across multiple worksheets, ensuring consistency in data.
4. Create Chart:
   1. On the **Row** shelf, drag **Value** from **Source Measures**.
   2. On the **Column** shelf, drag **Date Local** from **Impacts**. Then right-click the `Date Local` pill and select the **Exact Date** format.
   3. To update the y-axis title, follow the [steps to change the appearance of an axis](https://help.tableau.com/current/pro/desktop/en-us/formatting_editaxes.htm#change-the-appearance-of-an-axis) and enter 'Daily Event Day Impact'.
5. Chart Preview:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FMSxEP5UK965Hpsxiql2s%2Fimage.png?alt=media&amp;token=2fa6050a-f429-449e-a5dc-f468c6bfe014" alt="The Time Series worksheet in Tableau with a chart of daily event day impact by date" width="563"><figcaption><p>Time Series worksheet</p></figcaption></figure>

**Table**

To create the table:

1. New Worksheet: [Open a new worksheet](https://help.tableau.com/current/pro/desktop/en-us/environ_workbooksandsheets.htm#create-new-worksheets-dashboards-or-stories) and call it 'Event Info'.
2. Create Table:
   * On the **Row** shelf, add all relevant fields as **Discrete** pills, which are blue. This tutorial uses the following fields:

<table data-full-width="false"><thead><tr><th width="177">Folder</th><th width="182">Field</th><th>Notes</th></tr></thead><tbody><tr><td>Impacts</td><td><code>Date Local</code></td><td><ul><li>Right-click the pill and select the <strong>Exact Date</strong> and <strong>Discrete</strong> formats.</li></ul></td></tr><tr><td>Event-Export-...</td><td><code>Id</code></td><td><ul><li>This is the ID of the event.</li></ul></td></tr><tr><td>Event-Export-...</td><td><code>Category</code></td><td><ul><li>This is the <a href="https://github.com/predicthq/gitbook-tech-docs/tree/main/docs/tech-docs/predicthq-data/event-categories/README.md">event category</a>.</li></ul></td></tr><tr><td>Event-Export-...</td><td><code>Start Local</code></td><td><ul><li>This is the start date of the event in the local time zone.</li><li>Right-click each pill and select the <strong>Exact Date</strong> and <strong>Discrete</strong> formats.</li></ul></td></tr><tr><td>Event-Export-...</td><td><code>End Local</code></td><td><ul><li>This is the end date of the event iin the local time zone.</li><li>Right-click each pill and select the <strong>Exact Date</strong> and <strong>Discrete</strong> formats.</li></ul></td></tr><tr><td>Event-Export-...</td><td><code>Timezone</code></td><td><ul><li>The local time zone.</li></ul></td></tr><tr><td>Source Measures</td><td><code>Phq Attendance</code></td><td><ul><li>This is the <a href="https://github.com/predicthq/gitbook-tech-docs/tree/main/docs/tech-docs/predicthq-data/predicted-attendance.md">Predicted Attendance</a> for an event.</li><li>Right-click the pill and select the <strong>Discrete</strong> format.</li></ul></td></tr><tr><td>Source Measures</td><td><code>Value</code></td><td><ul><li>This is the <a href="https://github.com/predicthq/gitbook-tech-docs/tree/main/docs/tech-docs/predicthq-data/impact-patterns.md">daily impact for an event</a>. For this tutorial, only impact on event days is considered.</li><li>Sort by descending `Value` by following these <a href="https://help.tableau.com/current/reader/desktop/en-us/reader_sort.htm">Tableau instructions for sorting data</a>.</li></ul></td></tr></tbody></table>

{% hint style="info" %}
For more information on PredictHQ event fields, see [Events](https://docs.predicthq.com/api/events/search-events).
{% endhint %}

3. Table Preview:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FhBmVBRtsUnvfh8bxpnA4%2Fimage.png?alt=media&amp;token=cd0cfb1a-1e38-4a40-9475-5d3637941ef0" alt="The Event Info worksheet in Tableau with a table of events and their daily impact values"><figcaption><p>Event Info worksheet</p></figcaption></figure>

### Dashboard

To build the dashboard:

1. New Dashboard: [Open a new dashboard](https://help.tableau.com/current/pro/desktop/en-us/environ_workbooksandsheets.htm#create-new-worksheets-dashboards-or-stories):
   * To make the dashboard fit any screen, follow the [steps to set the overall dashboard size](https://help.tableau.com/current/pro/desktop/en-us/dashboards_organize_floatingandtiled.htm#set-overall-dashboard-size) and set the size to **Automatic**.
2. Add Worksheets:
   1. From the **Sheets** list, drag the **Time Series** sheet into the dashboard.
   2. From the **Sheets** list, drag the **Event Info** sheet into the dashboard.
   3. Resize the [layout containers](https://help.tableau.com/current/pro/desktop/en-us/dashboards_organize_floatingandtiled.htm#layout-container-types) as needed.
3. Set Filters: Use the Time Series worksheet as an interactive filter by following these [steps to add dashboard interactivity](https://help.tableau.com/current/pro/desktop/en-us/dashboards_create.htm#add-interactivity). This allows you to click specific dates in the chart to dynamically filter the events displayed in the table.
4. Dashboard Preview:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FckllkZKCp62TU0zV7LNZ%2Fimage.png?alt=media&amp;token=78b3794c-07cf-4eae-9be7-f61f1234964c" alt="The Tableau dashboard combining the Time Series chart with the Event Info table"><figcaption><p>Dashboard</p></figcaption></figure>

{% hint style="info" %}
For more information on creating dashboards, see the [Tableau guide to creating dashboards](https://help.tableau.com/current/pro/desktop/en-us/dashboards_create.htm).
{% endhint %}

### Next steps

There are several ways to expand the functionality and relevance of this dashboard to your specific business needs:

1. Incorporate Business Metrics: Integrate key metrics such as sales figures or units sold to gain a comprehensive view of how events influence business performance. Linking event impacts with sales data can help uncover high-level trends and support data-driven decision-making.
2. Explore Predicted Impact Patterns: While this tutorial focuses on the immediate impacts of events, exploring additional Predicted Impact Patterns could yield deeper insights. For example, examining patterns leading up to and after events might reveal extended influences on consumer behavior or operational demands.
3. Customize Visualizations: Enhance the dashboard with more complex visualizations like heat maps or geographic visualizations. These can offer spatial insights into where events have the most impact, assisting in regional marketing strategies and resource allocation.
4. Up-to-date Event Data: Ensure the dashboard reflects the most current data by considering connections like Snowflake or Amazon Data Exchange. These methods (see [other connection methods](#other-connection-methods) later in this tutorial) offer real-time updates which are essential for accommodating the dynamic nature of event data.

## Other connection methods

While this tutorial primarily focuses on connecting via a JSON file, other connection methods are available for those needing real-time updates or integration with other data services

<details>

<summary>Snowflake</summary>

This connection method involves accessing PredictHQ data through Snowflake’s Secure Data Share and connecting it to Tableau.

**Snowflake Data Share**

To connect through a Snowflake Data Share:

1. Setup: With your Snowflake administrator, set up a Data Share with PredictHQ.
2. Database:
   1. Create a database from the Data Share.
   2. Grant the necessary permissions to users.

For more information on receiving PredictHQ data via Snowflake, see the [Snowflake data share guide](https://docs.predicthq.com/integrations/third-party-integrations/snowflake).

**Connect to Snowflake in Tableau**

3. Connection Details: Before connecting, gather all necessary information including:
   1. [Login credentials](https://help.tableau.com/current/pro/desktop/en-us/examples_snowflake.htm#before-you-begin) for Snowflake authentication
   2. [Server, Warehouse, Database, and Schema information](https://help.tableau.com/current/pro/desktop/en-us/examples_snowflake.htm#set-up-the-data-source) to set up the data source.
4. Start Tableau: Open Tableau and connect to Snowflake by following the [instructions for connecting to Snowflake](https://help.tableau.com/current/pro/desktop/en-us/examples_snowflake.htm#make-the-connection-and-set-up-the-data-source).

For more information on connecting to Snowflake in Tableau and setting up the data source, see the [Tableau guide to connecting to Snowflake](https://help.tableau.com/current/pro/desktop/en-us/examples_snowflake.htm).

**Filter for relevant events in Tableau**

5. Configure SQL Query: To manage how data is brought in for subsequent analyses, use Tableau’s custom SQL query. For PredictHQ data, this typically involves flattening nested JSON, converting data types, and applying filters, such as category, date, and location, to filter for relevant events. See this [Power BI tutorial](https://docs.predicthq.com/integrations/third-party-integrations/using-event-data-in-power-bi) for an example of how this query might be structured.

For more information on connecting to a custom SQL query, see the [Tableau guide to custom SQL queries](https://help.tableau.com/current/pro/desktop/en-us/customsql.htm).

</details>

<details>

<summary>Amazon S3</summary>

This connection method involves accessing PredictHQ data through AWS Data Exchange and connecting it to Tableau.

**AWS Data Exchange**

To connect through AWS Data Exchange:

1. Setup: On AWS Data Exchange, subscribe to PredictHQ data
2. Amazon S3:
   1. To access the data from Tableau, copy the data to your specified S3 bucket.
   2. In AWS, confirm that your IAM user or role has read permissions for this bucket.

For more information on receiving PredictHQ data via AWS Data Exchange, see the [AWS Data Exchange guide](https://docs.predicthq.com/integrations/third-party-integrations/aws-data-exchange).

**Connect to Amazon S3 in Tableau**

3. Connection Details: Before connecting, gather all [necessary information](https://help.tableau.com/current/pro/desktop/en-us/examples_amazons3.htm#before-you-begin) including:
   1. AWS IAM access key for the S3 bucket.
   2. The name and AWS region of the S3 bucket.
4. Start Tableau: Open Tableau and connect to the S3 bucket by following the [steps to connect to Amazon S3](https://help.tableau.com/current/pro/desktop/en-us/examples_amazons3.htm#make-the-connection-and-set-up-the-data-source).

For more information on connecting to Amazon S3 in Tableau and setting up the data source, see the [Tableau guide to connecting to Amazon S3](https://help.tableau.com/current/pro/desktop/en-us/examples_amazons3.htm).

**Filter for relevant events in Tableau**

5. Configure SQL Query: To manage how data is brought in for subsequent analyses, use Tableau’s custom SQL query. For PredictHQ data, this typically involves flattening nested JSON, converting data types, and applying filters, such as category, date, and location, to filter for relevant events. See this [Power BI tutorial](https://docs.predicthq.com/integrations/third-party-integrations/using-event-data-in-power-bi) for an example of how this query might be structured.

For more information on connecting to a custom SQL query, see the [Tableau guide to custom SQL queries](https://help.tableau.com/current/pro/desktop/en-us/customsql.htm).

</details>

<details>

<summary>More common connectors</summary>

Some other connectors commonly used with PredictHQ data include the following:

* [Google BigQuery](https://help.tableau.com/current/pro/desktop/en-us/examples_googlebigquery.htm)
* [Azure SQL Database](https://help.tableau.com/current/pro/desktop/en-us/examples_azure_sql_database.htm)
* [Amazon Redshift](https://help.tableau.com/current/pro/desktop/en-us/examples_amazonredshift.htm)

For more information on loading PredictHQ data into data warehouses, see the [guide to loading event data into a data warehouse](https://docs.predicthq.com/integrations/integration-guides/loading-event-data-into-a-data-warehouse) which provides an example using Google BigQuery.

See the [list of all connectors supported by Tableau](https://help.tableau.com/current/pro/desktop/en-us/exampleconnections_overview.htm). Once PredictHQ data is connected to a data warehouse, you can apply techniques similar to those described in this guide to query data from these sources.

</details>

## Conclusion

This tutorial has demonstrated how to connect PredictHQ data to Tableau and build a functional dashboard. This is just one way to harness the power of event data. Continue to refine and expand your dashboard to align with your business needs, maximizing the insights available and thereby enhancing strategic decision-making processes.

## **Resources for download**

{% file src="/files/vYX7h8F28DSgDqI6bYz4" %}
JSON file
{% endfile %}

{% file src="/files/9Qqdi2M6ISXcKSo4bNsC" %}
Tableau workbook
{% endfile %}

## Deprecated Tableau Web Data Connector

<details>

<summary>Deprecated Tableau Connector</summary>

To connect with the deprecated connector:

1. [Log in](https://control.predicthq.com/) to your PredictHQ account or [sign up](https://signup.predicthq.com/) for a trial if you haven't got an account yet.
2. In the [**API Clients**](https://control.predicthq.com/clients) part of the WebApp, create a new API Client.
3. Save the Client Secret somewhere safe, because the WebApp doesn't show it again.
4. Click **Create an access token**.
5. Select the scopes **Account**, **Events**, and **Places**.
6. Open Tableau and select **Web Data Connector**.
7. In the pop-up box, enter the URL:

```
https://tableau-connector.predicthq.com
```

8. Click **Begin**.
9. Enter the Access Token you generated.
10. Choose the filters and parameters that you wish to explore. Refer to the [Search Events documentation](https://docs.predicthq.com/api/events/search-events) for a full list of fields and parameters.
11. To import events into Tableau, click **Get data**.

</details>


# Using event data in Power BI

Learn how to connect PredictHQ data to Power BI using multiple methods, and build an example report.

In today's data-driven landscape, leveraging powerful analytical tools is essential for making informed decisions and uncovering hidden insights. This step-by-step guide focuses on Power BI as an industry standard robust, user-friendly platform. This guide uses Power BI as an example of a reporting suite that lets you integrate data from various sources, create interactive reports, and share insights across an organization, to leverage PredictHQ data for powerful insights.

## Overview

This tutorial covers how to connect PredictHQ data to Power BI via two sources, CSV upload and direct API connection using one of our APIs - the Events API.

The data used in this guide is based on a popular location, in our case San Francisco City as a whole. Change the location from San Francisco to the location you want to look at.

The main steps involved in this guide are:

1. Building report parameters around a location
   * Example parameters for this guide
2. Select an input method
   * CSV upload
   * Snowflake connection
   * API connection
3. Guide to building the report
   * Example report download

**Requirements:**

1. Access to PredictHQ data via three methods with three different requirements:
   * CSV: PredictHQ account - [Sign up for a PredictHQ account](https://signup.predicthq.com/) if you don’t already have an account.
   * Snowflake: PredictHQ [Snowflake Data Share](https://docs.predicthq.com/integrations/third-party-integrations/snowflake)
   * API: [API Access Token](https://docs.predicthq.com/api/overview/authenticating)
2. [Microsoft Power BI](https://www.microsoft.com/en-us/power-platform/products/power-bi) reporting software

## Building report parameters around a location

For the purposes of this tutorial, parameters will be fixed for a standard example. The next section, Example parameters for this guide, defines the parameters, focusing on San Francisco city for attended events in a three-month period.

{% hint style="info" %}
You can modify all of our parameters based on your needs, see our [filtering guide](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events) for details on what these parameters mean and how they can be modified to suit different use cases.
{% endhint %}

### Example parameters for this guide:

1. **Date**: user-defined, this tutorial uses a three-month period from January 1st to March 31st 2024
2. **Categories**: community, conferences, concerts, expos, festivals, performing-arts, sports - these are our [attended categories](https://docs.predicthq.com/getting-started/predicthq-data/event-categories)
3. **Event State**: Active and Predicted
4. **Predicted Attendance**: attended events only - filtered to events with an attendance of at least 1
5. **Location**: San Francisco city (place ID [5391959](https://www.geonames.org/5391959/san-francisco.html))

Location could be substituted for a specific latitude and longitude relating to an individual store, or could be scoped even wider depending on need. We suggest utilizing our [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area) to hone in on a specific shop location and pull only events within a more accurate area based on those results. For now, we will look at the citywide events in San Francisco as our example.

The report provided in this example shows a graph of the total number of people attending events around the location per day, as well as a list of the events happening at the location sorted by the highest attendance events first.

We find many customers want to know what is happening around a business location such as around a hotel, restaurant, store, or other location. The graph of total attendance per day shows you peaks and dips in physically attended events. This allows you to see upcoming busy days or potential demand surges as well as quieter days. The list of events allows you to see events happening on a given day in more detail.

Our customers use this in a variety of ways, for example, an accommodation customer may use a report like this to set their hotel room pricing per day and may increase the price on days with a lot of events happening. A restaurant customer looking at staffing might roster more people when they see a lot of events happening near their location and perhaps reduce staff levels when fewer events are happening. And so on. See our [use case guides](https://docs.predicthq.com/getting-started/use-case-guides) for more examples.

The end result of the exercise is a report like this:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FTZSAKvabik6DYlAB0KIR%2FFinal%20Result.png?alt=media&amp;token=6c6374bb-037d-4a9c-946c-8d4783118ed6" alt="Power BI report with a chart of total event attendance per day in San Francisco and a table of events sorted by highest attendance"><figcaption><p>Final Report Result</p></figcaption></figure>

## Select an input method

There are several ways to connect PredictHQ data to Power BI or other reporting software. The following are three of the main methods you can use to connect and start creating reports.

[**CSV Upload**](#csv-upload-method): This method connects data straight from the PredictHQ WebApp into reporting software. If a static view of data is all you need, this method gets it done fast. This method *does not* refresh or update the data when it changes. Events are dynamic and get canceled, postponed, move location, and so on. Using a CSV is a good way to do initial modeling but we’d suggest calling the API or connecting to a data warehouse moving forward.

[**Snowflake Connection**](#snowflake-connection-method): We highly recommend choosing Snowflake as the data source for Power BI due to its robust data warehousing capabilities and seamless integration. Snowflake provides dynamic scalability and real-time data access, enhancing the accuracy and efficiency of reports. Snowflake offers straightforward connectivity and powerful query performance.

[**API Connection**](#api-connection-method): Another preferred method for connecting our dynamic events data to Business Intelligence software is to use our robust APIs. This way the report is connected to an ever-updating data source and is always up to date.

### CSV upload method

We will use PredictHQ [WebApp Search](https://control.predicthq.com/search/events) to get our CSV. To search for the events:

1. Fill in the filters based on the parameters laid out in the [Example Parameters for this Guide](#example-parameters-for-this-guide).
2. Click **Search**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Fz4WKDTGg9jh5GqIaxhCc%2FControl%20Center%20Filter.png?alt=media&amp;token=18138200-fb5f-4697-b962-445e7b0316d7" alt="The PredictHQ WebApp event search page with the example filters filled in"><figcaption><p>WebApp Example Filters</p></figcaption></figure>

Once the search has completed to get a CSV, click **Export**. Once the export has been downloaded, it’s ready for use in Power BI. The filename by default should be “Events-Export-zzzz-on-xxxx” where x is the date of the export and z is the location - feel free to rename this to anything else.

To connect the CSV in Power BI:

1. Create a new report.
2. Click **Get Data** -> **Text/CSV**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FjK7cdELCozTokqvjbZcX%2FNew%20CSV%20Connection.png?alt=media&amp;token=2991bc1f-2516-4cb3-8916-04096c710c49" alt="Power BI Get Data menu with the Text/CSV option selected to create a new CSV connection"><figcaption><p>Get Data -> Text/CSV new connection</p></figcaption></figure>

To transform the CSV export:

1. Upload the CSV export.
2. Click **Transform Data**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FkbTsdHhz7nhTAm0QlN7n%2FCSV%20Transform%20Data.png?alt=media&amp;token=b61f0d03-d95a-48c1-bbbe-7fdadbe5b947" alt="The Power BI data preview window for the uploaded CSV with the Transform Data button highlighted"><figcaption><p>CSV 'Transform Data'</p></figcaption></figure>

To open the Advanced Editor:

1. Under **Queries**, right-click the Query, which is named the same as the uploaded CSV.
2. Click **Advanced Editor**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F2DXlOIir5SfysJOcgjQX%2FCSV%20go%20to%20Advanced%20Editor.png?alt=media&amp;token=0f68cbc3-66b9-4b46-81e0-f16000118adb" alt="The Power BI Queries pane with the context menu of the CSV query open and Advanced Editor highlighted"><figcaption><p>right click Query -> Advanced Editor</p></figcaption></figure>

This opens up a Power Query window which allows code to transform the data for us. The following Power Query code transforms the columns automatically for use in the report.

This code expands out the 'impact\_patterns' column (see [Predicted Impact Patterns ](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns)in our technical documentation for more information) and filters it to accommodation and actual attendance distribution. It renames some essential columns. It also transforms some column formats for easier use in reporting. It is an involved process with multiple steps - the following Power Query is the final output of this multi-stage transformation.

In the **Advanced Editor**, after the first existing four lines and the "Changed Type" step, paste the following Power Query, replacing the existing “in” line and everything after it:

{% code lineNumbers="true" fullWidth="true" %}

```powerquery
    ,#"Renamed Columns" = Table.RenameColumns(#"Changed Type",{{"impact_patterns", "impact_patterns_raw"}}),
    #"Added Custom" = Table.AddColumn(#"Renamed Columns", "impact_patterns", each Json.Document([impact_patterns_raw])),
    #"Expanded impact_patterns" = Table.ExpandListColumn(#"Added Custom", "impact_patterns"),
    #"Expanded impact_patterns1" = Table.ExpandRecordColumn(#"Expanded impact_patterns", "impact_patterns", {"vertical", "impact_type", "impacts"}, {"impact_patterns.vertical", "impact_patterns.impact_type", "impact_patterns.impacts"}),
    #"Expanded impact_patterns.impacts" = Table.ExpandListColumn(#"Expanded impact_patterns1", "impact_patterns.impacts"),
    #"Expanded impact_patterns.impacts1" = Table.ExpandRecordColumn(#"Expanded impact_patterns.impacts", "impact_patterns.impacts", {"date_local", "value", "position"}, {"impact_patterns.impacts.date_local", "impact_patterns.impacts.value", "impact_patterns.impacts.position"}),
    #"Filtered Rows" = Table.SelectRows(#"Expanded impact_patterns.impacts1", each ([impact_patterns.vertical] = "accommodation" and [impact_patterns.impacts.position] = "event_day")),
    #"Changed Number Type" = Table.TransformColumnTypes(#"Filtered Rows",{{"impact_patterns.impacts.value", Int64.Type}}),
    #"Changed Date Type" = Table.TransformColumnTypes(#"Changed Number Type", {
    {"impact_patterns.impacts.date_local", type date}
    }),
    #"Extracted Date" = Table.TransformColumns(#"Changed Date Type", {
        {"start", DateTime.Date, type date}, {"end", DateTime.Date, type date},
        {"start_local", DateTime.Date, type date}, {"end_local", DateTime.Date, type date}
    }),
    #"Changed Type1" = Table.TransformColumnTypes(#"Extracted Date",{{"phq_attendance", Int64.Type}}),
    #"Renamed Columns1" = Table.RenameColumns(#"Changed Type1", {
    {"impact_patterns.impacts.date_local", "date_local"},
    {"impact_patterns.impacts.value", "attendance_per_day"}
})
in
    #"Renamed Columns1"
```

{% endcode %}

As you can see we start with a comma to add on to the existing line, its positioning can be changed to the end of the existing line if you prefer, but its function is the same. The final pasted code should look something like this:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F04QaSta2YHauesEZBJc8%2FCSV%20Power%20Query%20complete.png?alt=media&amp;token=7634d1d3-5916-474b-9d47-c5f82c083c0f" alt="The Power BI Advanced Editor with the transformation Power Query pasted after the existing lines of the CSV query"><figcaption><p>CSV Power Query</p></figcaption></figure>

To apply the transformation:

1. Click **Done**.
2. Click **Close & Apply**, and wait for the data transformation to finish processing.

After completing these steps, we have successfully loaded a CSV extract of PredictHQ Events data into Power BI ready for use in visuals and reporting. See the [Guide to building the report](#guide-to-building-the-report) section later in this guide for the next steps.

### Snowflake connection method

To connect using Snowflake, gather the following information about your organization's Snowflake environment. Ask your Snowflake Administrators for these settings or refer to Snowflake's official documentation links for the following variables:

1. Server Name: Usually in format <[account\_name](https://docs.snowflake.com/en/user-guide/admin-account-identifier#label-account-name)>.snowflakecomputing.com
2. Warehouse: A [warehouse](https://docs.snowflake.com/en/user-guide/warehouses-overview) is what you use to run queries. See which are available to you using the [SHOW WAREHOUSES](https://docs.snowflake.com/en/sql-reference/sql/show-warehouses) function.
3. Table Location: the Database, Schema, and Table Name for your [PredictHQ Data Share Events](https://docs.predicthq.com/integrations/third-party-integrations/snowflake) table.

To start, navigate to the Snowflake data connection via:

**Get Data** -> **More** -> **Database** -> **Snowflake**\\

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2F7RlZONfAQEQ9vhgqTzZe%2FNew%20Snowflake%20Connection.png?alt=media&amp;token=489976ba-df6c-45b9-a6ac-dc60185e32b0" alt="The Power BI Get Data menu with the More option highlighted to start a new Snowflake connection"><figcaption><p>Get Data -> More</p></figcaption></figure>

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Ftl4OKwPlaK5DYaLoAQVQ%2FSelect%20Snowflake%20Database.png?alt=media&amp;token=0dce3050-5b90-4916-a559-bd8e50a73b2b" alt="The Power BI Get Data window with Database selected and Snowflake highlighted in the list of connectors"><figcaption><p>Database -> Snowflake</p></figcaption></figure>

Enter the **Server** and **Warehouse** info you gathered earlier.\
It should look something like the following screenshot, replacing square bracket placeholder variables for your Server and Warehouse info.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FqiHELKrM2ryXoX55zsGb%2FServer%20and%20Warehouse.png?alt=media&amp;token=08514673-2a66-42d2-8087-6a4b6f368e51" alt="The Power BI Snowflake connection dialog with the Server and Warehouse fields filled in"><figcaption><p>enter Server and Warehouse info</p></figcaption></figure>

To enter the query:

1. Expand **Advanced options** and scroll down.
2. In **Database**, enter the database where the PredictHQ Events table lies in your Snowflake structure (case sensitive).
3. In the following SQL, replace the Schema and Table Name placeholders with your own.
4. In the **SQL** box, paste the SQL. This code assumes no columns have been renamed:

{% code lineNumbers="true" fullWidth="true" %}

```sql
select e.event_id as id, e.parent_event_id, e.update_dt, e.title, e.category, ARRAY_TO_STRING(e.labels,',') as labels, e.phq_labels
    , e.phq_rank, e.phq_attendance, e.local_rank, e.status 
    , e.event_start AS "start", e.event_start_local as "start_local", e.event_end AS "end", e.event_end_local as "end_local"
    , e.predicted_end, e.timezone
    , val.value:value::INT as attendance_per_day, val.value:date_local::DATE as date_local  
    , e.country_code, e.entities, e.geo, e.placekey, e.impact_patterns
    , e.predicted_event_spend_accommodation, e.predicted_event_spend_hospitality, e.predicted_event_spend_transportation
    , e.place_hierarchies 
from [Schema].[TableName] e
, LATERAL FLATTEN(INPUT => impact_patterns) imp
, LATERAL FLATTEN(INPUT => imp.value:impacts) val
where val.value:date_local::DATE between '2024-01-01' and '2024-03-31'
    and status in ('active','predicted')
    and phq_attendance >= 1
    and category in ('community','concerts','conferences','expos','festivals','performing-arts','sports')
    and imp.value:vertical::STRING = 'accommodation' and val.value:position::STRING = 'event_day'
    and ARRAY_TO_STRING(PLACE_HIERARCHIES, ',') ilike '%5391959%'
```

{% endcode %}

This code is performing the data transformation and filtering in code. It filters to the parameters laid out in the [Example Parameters for this Guide](#example-parameters-for-this-guide) section, and transforms some columns we will be using for ease of use in the report.\
The most important transformed column is the 'impact\_patterns' column which we use to find the attendance spread per day across a multi-day event. See [Predicted Impact Patterns ](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns)in our technical documentation for more information.

This is what it should look like when filled in - with all square bracket placeholder text in the FROM condition replaced.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FxzrZZI2Xox6cVfMSLrf9%2FSQL%20Statement.png?alt=media&amp;token=00c3f4b4-b11b-4426-8399-55342fbc1d0c" alt="The Snowflake connection advanced options with the SQL statement pasted in"><figcaption></figcaption></figure>

To finish the connection:

1. Click **OK**.
2. On the next screen, click **Load Data**.

Connection settings: We recommend **DirectQuery** for a constant database connection and **Import** for a one-off import of data from the database.

After completing these steps, we have successfully connected Events data from Snowflake into Power BI ready for use in visuals and reporting and automatic data refreshes. See the [Guide to building the report](#guide-to-building-the-report) section later in this guide for the next steps.

#### Connecting to other data warehouses

See [Loading event data into a data warehouse](https://docs.predicthq.com/integrations/integration-guides/loading-event-data-into-a-data-warehouse) for an example of how to load event data into Google BigQuery or other data warehouses. See this guide on [how to connect PowerBI to Google BigQuery](https://learn.microsoft.com/en-us/power-query/connectors/google-bigquery).

### API connection method

PredictHQ has a few APIs that can be used to build reports, for this example, we will stick to the Events API. Starting this process assumes you have created a PredictHQ API access token by following the [API Quickstart guide](https://docs.predicthq.com/getting-started/api-quickstart).

Power BI connects using the URL from the [Events API](https://docs.predicthq.com/api/events/search-events): `https://api.predicthq.com/v1/events/` but you must add query parameters to this URL for the Power BI connection, in line with the parameters outlined in the [Example Parameters for this Guide](#example-parameters-for-this-guide).

Following these parameters and the [Events API](https://docs.predicthq.com/api/events/search-events) documentation we end up with a URL string like this:

{% code overflow="wrap" fullWidth="true" %}

```url
https://api.predicthq.com/v1/events/?active.gte=2024-01-01&active.lt=2024-04-01&active.tz=America/Los_Angeles&category=community,conferences,concerts,expos,festivals,performing-arts,sports&state=active,predicted&phq_attendance.gte=1&place.scope=5391959&limit=500
```

{% endcode %}

Note: Scope uses the Place ID (geonames ID) for San Francisco (see our [tech docs for info on Place ID](https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-place-id)). If you were looking for events happening around a business location you would use the [within parameter](https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-latitude-longitude-and-radius) with the latitude and longitude of your business location and the area from the [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area).\
Time zone parameter (active.tz) filters results based on that given time zone.\
Limit parameter allows for more results returned per “page” which allows for faster loading, rather than the default 10 per page.

See also our [filtering guide](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events) for details on how to query the Events API for events impacting your locations.

With this API query string, event data can start to be loaded into Power BI.

To start the connection:

1. Start a new report.
2. Select **Get Data** -> **Web**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FJnVYkFnehb995W71LNWj%2FNew%20Web%20Connection.png?alt=media&amp;token=aa949a7a-caf1-4836-894d-74973610c3f3" alt="The Power BI Get Data menu with the Web option selected"><figcaption><p>Get Data -> Web connection</p></figcaption></figure>

Choose the **Advanced** tab, not the **Basic** default. To include the API Access Token request header, select the **Advanced** tab. The PredictHQ API uses Bearer token authorization.

Add the HTTP request header with the following information:

1. **URL parts**: our created Events API URL from earlier: `https://api.predicthq.com/v1/events/?active.gte=2024-01-01&active.lt=2024-04-01&active.tz=America/Los_Angeles&category=community,conferences,concerts,expos,festivals,performing-arts,sports&state=active,predicted&phq_attendance.gte=1&place.scope=5391959&limit=500`
2. **HTTP request header parameters**:
   1. In the first field, enter `Authorization`
   2. In the second field, enter `Bearer [api_token]`, with your PredictHQ API Access Token in place of `[api_token]`. The value keeps the word `Bearer` followed by a space before the token.

The filled-out information should look like this:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FKMTEG4hZViKQq4JWgVuO%2FAPI%20Connection.png?alt=media&amp;token=e7cf9c2a-38c5-477d-b5b9-ca39e6355fa4" alt="The Power BI web connection dialog with the Events API URL and Authorization header filled in"><figcaption><p>Web Connection URL and Header</p></figcaption></figure>

After clicking **OK**, the Data Transformation page opens where you can shape the data before building the report.

Rename the Query to something relevant, as it defaults to the connection URL string parameters and we need a string to reference in the Power Query code later in this section. Rename the Query to “PredictHQ Connection”.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FV8TO1nOO4y2OpJwmoY5F%2FAPI%20Rename%20connection%20Query.png?alt=media&amp;token=8142fe09-4f59-4126-ae9c-fe38b0e95aa6" alt="The Power Query Editor with the Query renamed to PredictHQ Connection"><figcaption><p>Rename the Query</p></figcaption></figure>

To format and expand some columns for easy use, open the **Advanced Editor** for this Query:

1. Open Power Query.
2. Under **Queries**, right-click the Query name.
3. Click **Advanced Editor**.

The screenshot shows the menu:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FyvkSwMoIbfuhZVP78cDc%2FAPI%20go%20to%20Advanced%20Editor.png?alt=media&amp;token=143d7fbb-a606-4164-a9ee-e81d2fea661f" alt="The right-click menu for the renamed Query with Advanced Editor selected"><figcaption><p>Right click renamed Query -> Advanced Editor</p></figcaption></figure>

To update the code:

1. Replace the entire existing Power Query code with the code that follows.
2. In Lines 4 and 8, replace the text that refers to ‘\[api\_token]’ with the PredictHQ API Access Token used previously.

This code expands out the 'impact\_patterns' column (see [Predicted Impact Patterns ](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns)in our technical documentation for more information) and filters it to accommodation and actual attendance distribution. It renames some essential columns. It also accounts for our API pagination, so the query returns all results. It is an involved process with multiple steps - the following Power Query is the final output of this multi-stage transformation.

{% hint style="info" %}
If you renamed the Query to something other than "PredictHQ Connection" as per our earlier steps, also rename the reference in lines 2 and 11 of this code:
{% endhint %}

{% code lineNumbers="true" fullWidth="true" %}

```powerquery
let
    #"PredictHQ Connection" = List.Generate( () =>
    [URL = "https://api.predicthq.com/v1/events/?active.gte=2024-01-01&active.lt=2024-04-01&active.tz=America/Los_Angeles&category=community,conferences,concerts,expos,festivals,performing-arts,sports&state=active,predicted&phq_attendance.gte=1&place.scope=5391959&limit=500",
     Result = Json.Document(Web.Contents(URL, [Headers=[Authorization="Bearer [api_token]"]]))],
    each [URL] <> null,
    each [
        URL = [Result][next],
        Result = Json.Document(Web.Contents(URL, [Headers=[Authorization="Bearer [api_token]"]]))
    ]
),
    #"Converted to Table" = Table.FromList(#"PredictHQ Connection", Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    #"Expanded Column1" = Table.ExpandRecordColumn(#"Converted to Table", "Column1", {"Result"}, {"Column1.Result"}),
    #"Expanded Column1.Result" = Table.ExpandRecordColumn(#"Expanded Column1", "Column1.Result", {"results"}, {"Column1.Result.results"}),
    #"Expanded Column1.Result.results" = Table.ExpandListColumn(#"Expanded Column1.Result", "Column1.Result.results"),
    #"Expanded Column1.Result.results1" = Table.ExpandRecordColumn(#"Expanded Column1.Result.results", "Column1.Result.results", {"id", "title", "description", "category", "labels", "rank", "local_rank", "phq_attendance", "entities", "duration", "start", "start_local", "end", "end_local", "updated", "first_seen", "timezone", "location", "geo", "impact_patterns", "scope", "country", "place_hierarchies", "state", "private", "predicted_event_spend", "predicted_event_spend_industries", "phq_labels"}),
    #"Expanded impact_patterns" = Table.ExpandListColumn(#"Expanded Column1.Result.results1", "impact_patterns"),
    #"Expanded impact_patterns1" = Table.ExpandRecordColumn(#"Expanded impact_patterns", "impact_patterns", {"vertical", "impact_type", "impacts"}, {"impact_patterns.vertical", "impact_patterns.impact_type", "impact_patterns.impacts"}),
    #"Expanded impact_patterns.impacts" = Table.ExpandListColumn(#"Expanded impact_patterns1", "impact_patterns.impacts"),
    #"Expanded impact_patterns.impacts1" = Table.ExpandRecordColumn(#"Expanded impact_patterns.impacts", "impact_patterns.impacts", {"date_local", "value", "position"}, {"impact_patterns.impacts.date_local", "impact_patterns.impacts.value", "impact_patterns.impacts.position"}),
    #"Filtered Rows" = Table.SelectRows(#"Expanded impact_patterns.impacts1", each ([impact_patterns.vertical] = "accommodation" and [impact_patterns.impacts.position] = "event_day")),
    #"Changed Number Type" = Table.TransformColumnTypes(#"Filtered Rows",{{"impact_patterns.impacts.value", Int64.Type}}),
    #"Changed Date Type" = Table.TransformColumnTypes(#"Changed Number Type", {
    {"impact_patterns.impacts.date_local", type date},
    {"start", type datetime}, {"end", type datetime},
    {"start_local", type datetime}, {"end_local", type datetime}
    }),
    #"Extracted Date" = Table.TransformColumns(#"Changed Date Type", {
        {"start", DateTime.Date, type date}, {"end", DateTime.Date, type date},
        {"start_local", DateTime.Date, type date}, {"end_local", DateTime.Date, type date}
    }),
    #"Changed Type" = Table.TransformColumnTypes(#"Extracted Date",{{"phq_attendance", Int64.Type}}),
    #"Renamed Columns" = Table.RenameColumns(#"Changed Type", {
    {"impact_patterns.impacts.date_local", "date_local"},
    {"impact_patterns.impacts.value", "attendance_per_day"}
    })
in
    #"Renamed Columns"
```

{% endcode %}

Click **Close & Apply** and wait for the data transformation to finish processing through multiple API pages.

After this step the data is now ready to start building a report with, as the query has loaded and transformed it in Power BI. A template of this API Connection report pre-built is available at the end in the [Example API Connection Report Template](#example-api-connection-report-template) section.

## Guide to building the report

Using either of the two earlier methods will get PredictHQ Events data loaded and transformed in the same format ready to be used in a report. The Power Query code transforms only the columns this guide uses.

This guide creates a connected chart and table that covers the defined time period and shows the attendance per day in the chosen location - in the example San Francisco city as a whole. The chart breaks up attendance per day for the visualization, but the table shows event details and attendance in full, not split by day. The report shows date results in UTC, use the "\_local" date columns for the local date.

To begin, insert the blank visuals:

1. On the **Insert** tab, click **New Visual** to insert a blank chart.
2. Click **New Visual** again to insert a blank table.
3. Place the chart first so it takes up half the screen.
4. Place the table second so it fills the other half.

To group the chart and table:

1. Shift-click both boxes to select them.
2. Right-click one of them.
3. Click **Group** -> **Group**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FRwwjon0xYvhB84yc9CA0%2FGroup%20Visuals.png?alt=media&amp;token=6fa54d37-1341-4f1c-8f08-9b5f16e53c43" alt="A blank chart and table in Power BI grouped together"><figcaption><p>Blank chart and table grouped</p></figcaption></figure>

Before the next step of filling in the chart and table, add Filters for the page:\
in the **Filters on this page** section under **Filters**, drag the 'date\_local' field from the **Data** tab.

To set the date filter:

1. Change the drop-down to **Advanced filtering**.
2. Add the following:

**is on or after** start of the selected date range AND **is before** the day after the date range ends - in the filter menu, click **Apply filter**.\
In the example, those dates are anything on or after the 1st of January 2024 and anything before 1st of April 2024.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FkrtxFpkArns5KDvVXuIF%2FFilter%20by%20date%20range.png?alt=media&amp;token=6a9b716d-472c-4f47-9818-42ae1d665373" alt="The Filters on this page pane with an advanced date_local filter set"><figcaption><p>date_local Filter on page</p></figcaption></figure>

To fill the chart axis:

1. Fill the **X-axis** with the date\_local field.
2. Fill the **Y-axis** with the attendance\_per\_day field (this should default to a SUM which is correct).

For the table, drag these fields over and resize the columns as needed to fit everything:

Table: id, title, category, phq\_attendance, start\_local, end\_local

For all fields that involve a date (date\_local, start\_local, end\_local), remove the default **Date Hierarchy** format to get the actual date showing:

1. In the **Visualizations** column, open the dropdown for the field.
2. Select the field name instead of **Date Hierarchy**.

If you prefer **Date Hierarchy**, leave this as is.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FuoLKHc09DWCGGRtHP2sp%2FRemove%20Date%20Hierarchy.png?alt=media&amp;token=1e0cd288-3862-4299-a77c-40337e197201" alt="The date_local field menu with Date Hierarchy turned off"><figcaption><p>Remove Date Hierarchy</p></figcaption></figure>

For phq\_attendance in the table use the drop down to remove the summary, this summary isn’t actually grouping anything so is an unnecessary default that should be removed. Note that we only want to stop the summarization in the table, leave the chart as is.

To rename the chart title:

1. Click the chart.
2. In the **Visualizations** tab, click **General**, and then click **Title**.
3. Enter “Event Attendance per day in San Francisco”.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Fm2bmyYMsDTXQXyTwdr5o%2FRename%20title.png?alt=media&amp;token=fbb79341-3a29-4210-8625-0533687ebfd2" alt="The Visualizations pane with the chart title set to Event Attendance per day in San Francisco"><figcaption><p>Chart Title Rename</p></figcaption></figure>

To sort by highest to lowest attendance, click the **phq\_attendance** column in the table twice.

The final result should look like the following:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FATK4GgqUiZVN1md8unBL%2FFinal%20Result.png?alt=media&amp;token=b54bab24-ae07-4f06-9c40-0aa5d781986f" alt="The finished Power BI report with a daily attendance chart and a table of events"><figcaption><p>Final Report Result</p></figcaption></figure>

The final report screenshot shows how this analysis can be used; by clicking a spike (or any period on the chart) the report shows the events active during that period. The table data does not show the attendance per day like the chart, but the overall attendance of the event's full duration.

A useful addition to this basic view could be a drill down on the table by adding a new table visual to the group that has the 'id', 'date\_local', and 'attendance\_per\_day' columns, showing how the attendance of an event has been spread out over multiple days (if it is a multi-day event). For more understanding of multi-day events, see our [Working with Multi-day Events](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-multi-day-and-umbrella-events) documentation.

You can add your own data to this chart to compare peaks and troughs of attendance vs sales in a basic comparison report. For deeper analysis into these kinds of reports, we suggest using our [Beam](https://docs.predicthq.com/api/beam) functionality to provide a deeper insight as to which types of events impact demand, as the Events API gives only a high-level view of the story without any additional analysis from PredictHQ to provide more in-depth information.

### Example API connection report template

The following is a downloadable Power BI template that automatically creates the example report used throughout this guide, using the API Connection method.

Upon opening the template, it prompts you to enter an API Access Token. Entering this token enables the report to automatically populate and build according to the parameters set forth in this guide.\
Wait 10-20 seconds between each step as data populates and data runs in the background.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Fm45PyxzdWMGh6rLM39zL%2FFill%20variable%20on%20template.png?alt=media&amp;token=3049a34f-b4b4-47f3-b62a-60b60140b02e" alt="The Power BI template prompt asking for a PredictHQ API Access Token"><figcaption><p>Fill PredictHQ API Access Token in the report when prompted</p></figcaption></figure>

Once the data connection has loaded for a bit you might be prompted for a connection method screen, as in the following screenshot. Select **Anonymous** and click **Connect**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2Ff8H06efYHQRvHWqCWK9M%2FTemplate%20Connection.png?alt=media&amp;token=ebc59a86-d373-426e-b43f-54a8b78201bd" alt="The Power BI connection method screen with Anonymous selected"><figcaption><p>Since the PredictHQ API Access Token has already been entered, select Anonymous here</p></figcaption></figure>

If there are any issues with this template refer to the [API Connection Method](#api-connection-method) and ensure all settings match with those steps.

#### Example report:

{% file src="/files/eWzLr7IwUeKonR177Szs" %}


# Connecting to PredictHQ APIs with Microsoft Excel

Learn how to connect PredictHQ data to Microsoft Excel using APIs.

## Overview

The data used in this guide is based on a popular location, in our case San Francisco City as a whole. Change the location from San Francisco to the location you want to look at.

The main steps in this guide are:

1. Building Report Parameters around a Location
   * Example Parameters for this Guide
2. Select an Input method
   * API connection
3. View events data in Excel

**Requirements:**

1. API: [API Access Token](https://docs.predicthq.com/getting-started/api-quickstart)
2. Microsoft Excel

### Example parameters for this guide:

1. **Date**: user-defined, this tutorial uses a 3-month period from January 1st to March 31st 2024
2. **Categories**: community, conferences, concerts, expos, festivals, performing-arts, sports - these are our [attended categories](https://docs.predicthq.com/getting-started/predicthq-data/event-categories)
3. **Event State**: Active and Predicted
4. **Predicted Attendance** (`phq_attendance`): attended events only - filtered to events with an attendance of at least 1
5. **Location**: San Francisco city (place ID [5391959](https://www.geonames.org/5391959/san-francisco.html))

You can substitute a specific latitude and longitude for an individual store, or scope the location even wider depending on need. We suggest utilizing our [Predicted Impact Area API](https://docs.predicthq.com/api/impact-area/get-impact-area) to hone in on a specific shop location and pull only events within a more accurate area based on those results. For now, we will look at the citywide events in San Francisco as our example.

### How to get events data via PredictHQ's API

This guide provides details on how to load PredictHQ's event data into Microsoft Excel using the Events API. We provide examples for Excel running in Microsoft Windows. In this tutorial we'll show you how to connect to the API and load data into a Spreadsheet. In Microsoft Excel, create a new empty Spreadsheet.

PredictHQ has a number of different APIs that can be used to build reports, in this example, we will stick to the Events API. Starting this process assumes you have created a PredictHQ API access token by following the [API Quickstart guide](https://docs.predicthq.com/getting-started/api-quickstart).

Microsoft Excel connects using the URL for the [Events API](https://docs.predicthq.com/api/events/search-events): `https://api.predicthq.com/v1/events/` but you must add query parameters to this URL for the Excel connection, in line with the parameters outlined in the [Example Parameters for this Guide](#example-parameters-for-this-guide).

Following these parameters and the [Events API](https://docs.predicthq.com/api/events/search-events) documentation the result is a URL string like the following:

{% code overflow="wrap" fullWidth="true" %}

```url
https://api.predicthq.com/v1/events/?active.gte=2024-01-01&active.lt=2024-04-01&active.tz=America/Los_Angeles&category=community,conferences,concerts,expos,festivals,performing-arts,sports&state=active,predicted&phq_attendance.gte=1&place.scope=5391959&limit=500
```

{% endcode %}

{% hint style="info" %}
Note: Scope uses the Place ID (geonames ID) for San Francisco (see our [tech docs for info on Place ID](https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-place-id)). If you were looking for events happening around a business location you would use the [within parameter](https://docs.predicthq.com/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-latitude-longitude-and-radius) with the latitude and longitude of your business location and the area from the Predicted Impact Area API.
{% endhint %}

Time zone parameter (active.tz) filters results based on that given time zone, even though the API returns date results in UTC.

Limit parameter allows for more results returned per “page” which allows for faster loading, rather than the default 10 per page.

See also our [filtering guide](https://docs.predicthq.com/getting-started/guides/events-api-guides/filtering-and-finding-relevant-events) for details on how to query the Events API for events impacting your locations.

With this API query string, you can start loading event data into Microsoft Excel.

First, create a new Spreadsheet. Then, to open the data connection options:

1. Click the **Data** tab.
2. On the **Data** tab, click **Get Data**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FYDHehhWirQ2u5SLVhSXh%2Fimage.png?alt=media&amp;token=f90d9b48-2912-41e2-b055-a66ca9e3b2b1" alt="The Data tab in Microsoft Excel with the Get Data menu open"><figcaption></figcaption></figure>

The PredictHQ API uses Bearer token authorization, so the connection needs the API Access Token request header. To set it up:

1. In the connection dialog, click the **Advanced** tab, not the default **Basic** tab.
2. Add the HTTP request header, using the details that follow.

Add the HTTP request header with the following information:

1. **URL parts**: our created Events API URL from earlier: `https://api.predicthq.com/v1/events/?active.gte=2024-01-01&active.lt=2024-04-01&active.tz=America/Los_Angeles&category=community,conferences,concerts,expos,festivals,performing-arts,sports&state=active,predicted&phq_attendance.gte=1&place.scope=5391959&limit=500`
2. **HTTP request header parameters**:
   1. For the header name, enter `Authorization`
   2. For the header value, enter `Bearer <api_token>`. where `<api_token>` stands for your PredictHQ API Access Token. Replace `<api_token>` with your actual API Access Token. Leave the ‘Bearer ’ part in. The following screenshot shows the fields once you enter your API key.\
      \
      ![The HTTP request header fields in Excel with Authorization in the first field and Bearer followed by the API token in the second field](https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FrKlpB1AfI8Ceo81DJsfm%2Fimage.png?alt=media\&token=f89026ac-5695-417f-807c-0ab199e5f14d)\\

The filled-out information should look like this (except that you replace api\_key with your actual api\_key)

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FKMTEG4hZViKQq4JWgVuO%2FAPI%20Connection.png?alt=media&amp;token=e7cf9c2a-38c5-477d-b5b9-ca39e6355fa4" alt="The Excel web connection dialog with the Events API URL and the Authorization header filled in"><figcaption><p>Web Connection URL and Header</p></figcaption></figure>

After clicking **OK**, the Data Transformation page opens where you can choose data shaping options before building the report.

The Query name defaults to the connection URL string parameters, which don't look neat. To rename the Query:

1. Enter a relevant name. This guide uses “PredictHQ Connection”.
2. If you use a different name, change the Power Query to match.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FV8TO1nOO4y2OpJwmoY5F%2FAPI%20Rename%20connection%20Query.png?alt=media&amp;token=8142fe09-4f59-4126-ae9c-fe38b0e95aa6" alt="The Data Transformation page with the Query name changed to PredictHQ Connection"><figcaption><p>Rename the Query</p></figcaption></figure>

To format and expand some columns, paste the following code into the **Advanced Editor** for this Query. To open the Advanced Editor:

1. Under **Queries**, right-click the Query name.
2. Click **Advanced Editor**.

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FyvkSwMoIbfuhZVP78cDc%2FAPI%20go%20to%20Advanced%20Editor.png?alt=media&amp;token=143d7fbb-a606-4164-a9ee-e81d2fea661f" alt="The right-click menu for the renamed Query in the Queries pane with Advanced Editor selected"><figcaption><p>Right click renamed Query -> <strong>Advanced Editor</strong></p></figcaption></figure>

To update the Power Query code:

1. Replace the entire existing Power Query code with the following code.
2. In Lines 4 and 8, replace ‘\[api\_token]’ with the PredictHQ API Access Token you used previously.

{% hint style="info" %}
This example doesn't work unless you replace the \[api\_token] with your token.\
Lines 2 and 11 refer to the Query name. If you've named it something other than "PredictHQ Connection", replace it here as well.
{% endhint %}

This code expands out the 'impact\_patterns' column (see [Predicted Impact Patterns ](https://docs.predicthq.com/getting-started/predicthq-data/impact-patterns)in our technical documentation for more information) and filters it to accommodation and actual attendance distribution. It renames some essential columns. It also accounts for our API pagination, making sure the query returns all results. The final output of this multi-stage transformation is the following Power Query:

{% code lineNumbers="true" fullWidth="true" %}

```powerquery
let
    #"PredictHQ Connection" = List.Generate( () =>
    [URL = "https://api.predicthq.com/v1/events/?active.gte=2024-01-01&active.lt=2024-04-01&active.tz=America/Los_Angeles&category=community,conferences,concerts,expos,festivals,performing-arts,sports&state=active,predicted&phq_attendance.gte=1&place.scope=5391959&limit=500",
     Result = Json.Document(Web.Contents(URL, [Headers=[Authorization="Bearer [api_token]"]]))],
    each [URL] <> null,
    each [
        URL = [Result][next],
        Result = Json.Document(Web.Contents(URL, [Headers=[Authorization="Bearer [api_token]"]]))
    ]
),
    #"Converted to Table" = Table.FromList(#"PredictHQ Connection", Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    #"Expanded Column1" = Table.ExpandRecordColumn(#"Converted to Table", "Column1", {"Result"}, {"Column1.Result"}),
    #"Expanded Column1.Result" = Table.ExpandRecordColumn(#"Expanded Column1", "Column1.Result", {"results"}, {"Column1.Result.results"}),
    #"Expanded Column1.Result.results" = Table.ExpandListColumn(#"Expanded Column1.Result", "Column1.Result.results"),
    #"Expanded Column1.Result.results1" = Table.ExpandRecordColumn(#"Expanded Column1.Result.results", "Column1.Result.results", {"id", "title", "description", "category", "labels", "rank", "local_rank", "phq_attendance", "entities", "duration", "start", "start_local", "end", "end_local", "updated", "first_seen", "timezone", "location", "geo", "impact_patterns", "scope", "country", "place_hierarchies", "state", "private", "predicted_event_spend", "predicted_event_spend_industries", "phq_labels"}),
    #"Expanded impact_patterns" = Table.ExpandListColumn(#"Expanded Column1.Result.results1", "impact_patterns"),
    #"Expanded impact_patterns1" = Table.ExpandRecordColumn(#"Expanded impact_patterns", "impact_patterns", {"vertical", "impact_type", "impacts"}, {"impact_patterns.vertical", "impact_patterns.impact_type", "impact_patterns.impacts"}),
    #"Expanded impact_patterns.impacts" = Table.ExpandListColumn(#"Expanded impact_patterns1", "impact_patterns.impacts"),
    #"Expanded impact_patterns.impacts1" = Table.ExpandRecordColumn(#"Expanded impact_patterns.impacts", "impact_patterns.impacts", {"date_local", "value", "position"}, {"impact_patterns.impacts.date_local", "impact_patterns.impacts.value", "impact_patterns.impacts.position"}),
    #"Filtered Rows" = Table.SelectRows(#"Expanded impact_patterns.impacts1", each ([impact_patterns.vertical] = "accommodation" and [impact_patterns.impacts.position] = "event_day")),
    #"Changed Number Type" = Table.TransformColumnTypes(#"Filtered Rows",{{"impact_patterns.impacts.value", Int64.Type}}),
    #"Changed Date Type" = Table.TransformColumnTypes(#"Changed Number Type", {
    {"impact_patterns.impacts.date_local", type date},
    {"start", type datetime}, {"end", type datetime},
    {"start_local", type datetime}, {"end_local", type datetime}
    }),
    #"Extracted Date" = Table.TransformColumns(#"Changed Date Type", {
        {"start", DateTime.Date, type date}, {"end", DateTime.Date, type date},
        {"start_local", DateTime.Date, type date}, {"end_local", DateTime.Date, type date}
    }),
    #"Changed Type" = Table.TransformColumnTypes(#"Extracted Date",{{"phq_attendance", Int64.Type}}),
    #"Renamed Columns" = Table.RenameColumns(#"Changed Type", {
    {"impact_patterns.impacts.date_local", "date_local"},
    {"impact_patterns.impacts.value", "attendance_per_day"}
    })
in
    #"Renamed Columns"
```

{% endcode %}

The code in the Advanced Editor should look like the following screenshot:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FxjRmtqSuwA9NGsajAW40%2FAPI%20Power%20Query%20complete.png?alt=media&amp;token=c657f660-d5bc-4f50-a49e-c4892123ee70" alt="The Advanced Editor in Excel showing the complete Power Query code"><figcaption></figcaption></figure>

Click **Close & Apply** and wait for the data transformation to finish processing through multiple API pages.

After this step the data is now ready to start building a report with, as Excel has successfully loaded and transformed it. You should see a Spreadsheet like the following screenshot:

<figure><img src="https://2312509647-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtNhzHETmXsrWeVBndqqJ%2Fuploads%2FaWl7MQorZVMbUB406J0a%2Fimage.png?alt=media&amp;token=4c041723-c27c-42cc-b1a5-d15ec4df73cc" alt="An Excel spreadsheet populated with PredictHQ event data after the query finishes loading"><figcaption></figcaption></figure>

You now have a connection to the API that you can refresh to get updated data.


# Python SDK

The official PredictHQ Python Client provides a consistent, pythonic interface to our API.

<table data-view="cards"><thead><tr><th></th><th data-hidden></th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>PyPi</strong></td><td>Get the PredictHQ Python SDK on PyPi.</td><td></td><td><a href="https://pypi.org/project/predicthq/">https://pypi.org/project/predicthq/</a></td></tr><tr><td><strong>GitHub</strong></td><td>View the code on GitHub.</td><td></td><td><a href="https://github.com/predicthq/sdk-py">https://github.com/predicthq/sdk-py</a></td></tr></tbody></table>

## Example

### Installation

Install the SDK with pip:

```bash
pip install predicthq
```

### Setup the SDK

Initialize the client with your access token:

```python
from predicthq import Client

# Initialises PredictHQ client library using your access token.
# Note: You can find/create your access token at https://control.predicthq.com/clients
phq = Client(access_token="$API_TOKEN")
```

### Search events

Perform a basic search of events using the `q`, `rank_level`, and `country` parameters:

```python
for event in phq.events.search(q="Foo Fighters", rank_level=[4, 5], country='US'):
    print(event.rank, event.category, event.title, event.start.strftime('%Y-%m-%d'))
```

By default, the event search returns only the first 10 results. If you want to paginate or access more results at once, look at either using limit/offset parameters or at using the `iter_all()` helper.

## Further examples

Browse our [use case examples](https://github.com/predicthq/sdk-py/tree/master/usecases) on our GitHub repository.

## Found an issue?

[Log an issue](https://github.com/predicthq/sdk-py/issues/new) on our GitHub repository.




---

[Next Page](https://docs.predicthq.com/llms-full.txt/1)

