This guide walks you through creating API Clients, generating access tokens, and searching for events with the PredictHQ API.
If you don't have an account yet, create one 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 API Client
An "API Client" is an entity in our system that represents the application that will be making API calls. API authentication credentials are attached to API Clients.
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 API Clients, select "New Client" or the "+" button. Give the API Client a title, description, select which scopes the token will have access to, and save. Your API Client will be created, and credentials generated for it. Save the client secret somewhere as you won't be able to see it again within Control Center.
Scopes are different permissions you can give to an API Client. You select scopes for an API Client and these then apply to access tokens created for the API Client. 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.
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 Access Token
Now that you have an API Client you can generate a token for it. When viewing the Client, select "Create an 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.
See also How to Create an API Token.
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 "Create new token" and save the generated token somewhere - as with the client secret, you won't be able to see it again within Control Center.
API Token Generation
Tokens can also be generated via the API, rather than using Control Center. 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.
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!
/ 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.
You can see see your subscription's event visibility window in the Dashboard in Control Center.
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.
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.
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 parameter takes two-letter ISO country codes. You can find a list of codes here.
We can filter the results to a specific date range using the
active set of parameters.
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
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 Dashboard of Control Center.
Add the query parameters
active.tz=America/Los_Angeles to your previous request to only include events that are active between
$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.
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.
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.