Relevance

The PredictHQ API event search endpoint provides a number of parameters that can affect the order results are returned. This guide will get you started using these parameters to prioritize the results that are most relevant to you or your customers.

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.

Prerequisites

This guide assumes a basic working knowledge of the PredictHQ API. If you haven't used the PredictHQ API before, we recommend reading the Quickstart Guide first.

The Scenario

Throughout the guide we'll be using the scenario of adding an "Events Near Me" feature to a mobile application, with the example use case of a user wanting to find a jazz concert to attend. We'll show how information from/about the user can be translated to search parameters that help tailor results to what the user wants.

curl -X GET "https://api.predicthq.com/v1/events/?category=concerts&country=US&active.gte=$CURRENT_DATE" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

curl -X GET "https://api.predicthq.com/v1/events/?q=jazz&category=concerts&country=US&active.gte=$CURRENT_DATE" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

Temporal Relevance

We've filtered out past events, but we're still getting events that are well in the future. The user might still want to go to them, but events that are happening sooner are more important.

We could sort by start ascending so earlier events are returned first. However, this only takes into account the "soon-ness" of the event without considering any other factors of what the user wants, such as the relevance to the q parameter (and the other factors we'll introduce below).

Instead, we'll use the start_around.origin parameter to add proximity of an event's start date to the $CURRENT_DATE as a relevance component, prioritizing events that start soon.

Add parameter start_around.origin=$CURRENT_DATE to our previous request.

Start Around Options

The other start_around.* parameters can be used to tune how the relevance of an event changes as its start date moves away from the origin. See the parameter documentation for details.

curl -X GET "https://api.predicthq.com/v1/events/?start_around.origin=$CURRENT_DATE&q=jazz&category=concerts&country=US&active.gte=$CURRENT_DATE" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

Spatial Relevance

We've prioritized events that are near in time, but what about near in space? We are aiming to build an "Events Near Me" feature after all.

The user's location (as reported by our app) is 40.782409,-73.971885 (lat,lon) - near the American Museum of Natural History in New York. We can use this as our location_around.origin to add the proximity of the event to the user's location as a relevance component.

We'll assume they are happy to travel a km or so, setting location_around.offset so all events within 1km have the same location_around relevance, with the relevance reducing as the distance to the event increases beyond that.

Add parameters location_around.origin=40.782409,-73.971885&location_around.offset=1km to our previous request.

Location Around Options

The other location_around.* parameters can be used to further tune how the relevance of an event changes as its location moves away from the origin. See the parameter documentation for details.

curl -X GET "https://api.predicthq.com/v1/events/?location_around.origin=40.782409,-73.971885&location_around.offset=1km&start_around.origin=$CURRENT_DATE&q=jazz&category=concerts&country=US&active.gte=$CURRENT_DATE" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

Event Rank

Our final relevance adjustment is to prioritize events with higher ranks, as they're more likely to be of interest to the user. Here we're not going to add a parameter that will start influencing relevance automatically, like we have with qstart_around.* and location_around.*. Instead we're going to directly change how the relevance field is calculated by using the relevance parameter.

The relevance parameter controls which relevance components are multiplied together to produce the final relevance field. When it isn't explicitly set it defaults to including all the components from the relevance-influencing parameters used in the search - in our case, qstart_around, and location_around.

Relevance Parameter

See the relevance parameter documentation for more information about the relevance parameter.

We want to add the rank component into the mix, so we need to set the relevance parameter explicity. We still want the existing components, so need to include them, but we'll add rank as well.

Add parameter relevance=rank,q,start_around,location_around to our previous request.

curl -X GET "https://api.predicthq.com/v1/events/?relevance=rank,q,start_around,location_around&location_around.origin=40.782409,-73.971885&location_around.offset=1km&start_around.origin=$CURRENT_DATE&q=jazz&category=concerts&country=US&active.gte=$CURRENT_DATE" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

What's Next?

And there you have it - a search that returns the most relevant results for the user, based on the user's search terms, how soon the events start, how close the events are to the user, and the events' ranks.

Have a look around the rest of the documentation to find out more about what our API offers.