This guide walks you through creating API applications, generating authentication tokens, and searching for events with the PredictHQ API.

If you don't have an account yet, create one here. If you have an account but no API subscription or trial, start your free 30-day trial here.

You will need to make a number of HTTP requests to the PredictHQ HTTP API. Examples of these requests are included in raw HTTP, cURL, and the Python Requests library - use the links at the top right to switch between these options. Alternatively, you can construct these requests yourself in any standard HTTP client of your choice.

Create Application

The first step to interacting with the PredictHQ API is to create an application. This is done from the Developers section of the Web App.


An "application" is an entity in our system that represents your application that will be making API calls. API authentication credentials are attached to applications.

Don't worry if you don't have an actual application - anything that makes API calls (including you via a HTTP client) can be considered an application in this context.

Under Applications, select "Create application" or the "+" button. Give the application a title and description, and save. Your application will be created, and credentials generated for it. Save the client secret somewhere as you won't be able to see it again within the Web App.

Client IDs and Secrets

The Client ID and Client Secret are like a username and password that authenticate your application. They aren't used directly in making most API requests, however. Instead, they are exchanged for tokens, which are used to make the actual requests.

Make sure to keep the client secret secure - anyone who has it can impersonate your application!

Generate Authentication Token

Now that you have an application you can generate a token for it. When viewing the application, select "Generate access token". You can give the token a description and select which scopes the token will have access to. To complete this guide your token will need to have the "Events" scope, but the others are optional.


Scopes are different permissions you can give to a token. Each API endpoint requires a token to have a specific scope. This allows a given token to have access to some endpoints, but not others, reducing the risk if it is compromised.

After entering the client secret you saved earlier, select "Generate new token" and save the generated token somewhere - as with the client secret, you won't be able to see it again within the Web App.

API Token Generation

Tokens can also be generated via the API, rather than using the Web App. See the Authentication documentation for details.

Your token allows you to make requests to the event endpoints of the API. We'll start by doing a simple event search.

A GET request to the /v1/events/ path at https://api.predicthq.com will perform an event search. You will need to authenticate your request by providing the token, formatted as a Bearer token, in the Authorization header. See the examples to the right for details, but make sure to replace $ACCESS_TOKEN with your token!

Trailing Slashes

Note the / at the end of the path for this endpoint's URL. Make sure to include this trailing slash on all paths in endpoint URLs, or you will get an error.

This request will return the first page of the events that you have access to, sorted in reverse chronological order. The events you have access to are determined by the details of your API subscription.

Subscription Details

You can see see your subscription's event visibility window in the Developers section of the Web App.

To get the events you're looking for you'll need to narrow down your results using search parameters. These are query parameters you can add to the request URL. Check the Events documentation for the full list of available parameters.

The q parameter performs a text search on the title and description of events. Add the query parameter q=jazz to your previous request to search for events that include "jazz".


Text search results are ranked based on their relevance to the search term(s). By default results are sorted by relevance, and then in reverse chronological order if they have the same relevance.

Most other search parameters are boolean filters - an event either matches or it doesn't - so don't affect relevance.

Country Filter

Next, let's filter the results to a specific country by passing a country code to the country parameter. Add the query parameter country=US to your previous request to only include events that are occurring in USA.

Country Codes

The country parameter takes two-letter ISO country codes. You can find a list of codes here.

Date Filter

We can filter the results to a specific date range using the active set of parameters.

Active Events

An event is considered active during a date range if it starts before the end of the range, and ends after the start of the range - in other words, if the event's run time overlaps at all with the selected range.

As the API will only return events that fall within your subscription's event visibility window, you will need to set the date range to use for this filter based on the current date. Set $START_DATE to today's date, and $END_DATE to two weeks from now. Each date should be formatted as yyyy-MM-dd.

Event Visibility

The event visibility window determines how far in the future and the past you can see events. It is defined by a number of days e.g. 365 means you can see events up to a year in the future, and up to a year in the past. You can see see your subscription's event visibility window in the Developers section of the Web App.

Add the query parameters active.gte=$START_DATE, active.lte=$END_DATE, and active.tz=America/Los_Angeles to your previous request to only include events that are active between $START_DATE and $END_DATE, using the Los Angeles timezone.


Our results are still sorted by relevance to our full-text search. Instead, let's get the most important events first. Add the query parameter sort=rank to your previous request to sort results based on their rank.

PredictHQ Ranks

All PredictHQ events are ranked with our proprietary algorithm, providing an easy way to compare events. The rank endeavours to describe the relative impact of an event.

What's Next?

Congratuations, you've built a search for the top Jazz events in the USA happening in the next two weeks using the PredictHQ API!

Now that you've got the basics down, why not learn how to get the search results you want first with our Relevance Guide, or have a look around the rest of the documentation to find out more about what our API offers.