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 or sign up for free.

2. An API Key - create one in the next section.

Create an API key

To create a key:

1. Log in to the WebApp.

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:

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

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 for guidance on which API to use for your use case.

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 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, then run Beam, then call the Features API with your analysis_id

I want event-driven forecasts without building a model → Go straight to the Forecasts API

I want to connect an AI assistant to PredictHQ → Set up the PredictHQ MCP server

I want to understand the full integration architecture → Read the Standard integration pattern