Search by Location
There are four different ways you can search for events by location. We also provide a way to understand what geographical areas events apply to.
Places Search example
Finding Sports Events for a specific place
For the following example, we want to find all the sports events that happened in Nottingham, England in March of 2018.
We need to make use of both the /places and /events endpoints to achieve this. First let’s find the Nottingham place id by making a request to the /places API endpoint for Nottingham,England
curl -X GET "https://api.predicthq.com/v1/places/?q=Nottingham,England" \
-H "Authorization: Bearer $ACCESS_TOKEN"The first result in the response (shown below) is the correct location we want:
{
"id": "2641170",
"type": "locality",
"name": "Nottingham",
"county": "Nottingham",
"region": "England",
"country": "United Kingdom",
"country_alpha2": "GB",
"country_alpha3": "GBR",
"location": [
-1.15047,
52.9536
]
}Now we take the place id for Nottingham returned above, place.scope=2641170, to find all the sports events, category=sports, which are active in March of 2018, active.gte=2018-03-01 and active.lte=2018-03-31.
curl -X GET "https://api.predicthq.com/v1/events/?place.scope=2641170&active.gte=2018-03-01&active.lte=2018-03-31&category=sports&sort=rank" \
-H "Authorization: Bearer $ACCESS_TOKEN"A snippet of the results are shown below:
"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. Please see the official Geonames site for more information.
Using place.scope will return 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.
IATA Code search
Find Concert Events using an IATA airport code
For the following 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 (3 character), ICAO (4 character), and UN/LOCODE (5 character) airport codes. A CSV file with all supported airport codes and their respective place ids is available to download.
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.
curl -X GET "https://api.predicthq.com/v1/events/?place.scope=LAX&active.gte=2018-03-03&active.lte=2018-03-03&category=concerts&sort=rank" \
-H "Authorization: Bearer $ACCESS_TOKEN"A snippet of the results are shown below:
"count": 73,
"results": [
{
"id": "XS5tQbpjKtFeUShTPt",
"title": "Demi Lovato with DJ Khaled and Kehlani",
"category": "concerts",
...Radial search
Find events that happen within a certain radius from my location
For the following example, we will find conferences and expos that happened within a 2 mile radius of a specific location, in April 2018.
It can be difficult working out a suitable radius around your location so to make it easier please use our Suggested Radius API.
The /events API 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.
This can be used 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
curl -X GET "https://api.predicthq.com/v1/events/?within=2mi@-37.80036998,144.9715749&active.gte=2018-04-01&active.lte=2018-04-30&category=conferences,expos&sort=rank" \
-H "Authorization: Bearer $ACCESS_TOKEN"A snippet of the results are shown below:
"count": 734,
"results": [
{
"id": "SwBTYbfiAHYDdbkUi7",
"title": "Great Debate: Political Interest Society vs History Society",
"category": "conferences",
...Places Hierarchies and scopes
Find events for specific countries or regions
For the following example, we will find public and school holidays for the United States of America in 2018.
The /events API endpoint allows you to specify a particular country by using the country parameter. This parameter supports the standard 2 character ISO 3166-1 country codes. A full list of these codes can be found here.
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.
curl -X GET "https://api.predicthq.com/v1/events/?country=US&category=public-holidays,school-holidays&active.gte=2018-01-01&active.lte=2018-12-31" \
-H "Authorization: Bearer $ACCESS_TOKEN"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 will be country, otherwise it may be region.
A snippet of the results are shown below:
"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 API endpoint to find information about the place ids mentioned in the hierarchy.