Places, Countries and Locations

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.

Making Requests

Examples of these requests are included in raw HTTP, cURL, and the Python Requests library - use the links on the menu bar at the top right to switch between these options.


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

  • GET v1/places/?q=Nottingham,England HTTP/1.1
    Authorization: Bearer $ACCESS_TOKEN
    
  • curl -X GET "https://api.predicthq.com/v1/places/?q=Nottingham,England" \
         -H "Authorization: Bearer $ACCESS_TOKEN"
    
  • import requests
    
    response = requests.get(
        url="https://api.predicthq.com/v1/places/",
        headers={
          "Authorization": "Bearer $ACCESS_TOKEN",
          "Accept": "application/json"
        },
        params={
            "q": "Nottingham,England"
        }
    )
    
    print(response.json())
    

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.

  • GET v1/events/?place.scope=2641170&active.gte=2018-03-01&active.lte=2018-03-31&category=sports&sort=rank HTTP/1.1
    Authorization: Bearer $ACCESS_TOKEN
    
  • 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"
    
  • import requests
    
    response = requests.get(
        url="https://api.predicthq.com/v1/events/",
        headers={
          "Authorization": "Bearer $ACCESS_TOKEN",
          "Accept": "application/json"
        },
        params={
            "place.scope" : "2641170",
            "active.gte" : "2018-03-01",
            "active.lte" : "2018-03-31",
            "category" : "sports",
            "sort" : "rank"
        }
    )
    
    print(response.json())
    

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.


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. Please Download CSV for a list of all supported airport codes and their respective place ids.

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.

  • GET v1/events/?place.scope=LAX&active.gte=2018-03-03&active.lte=2018-03-03&category=concerts&sort=rank HTTP/1.1
    Authorization: Bearer $ACCESS_TOKEN
    
  • 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"
    
  • import requests
    
    response = requests.get(
        url="https://api.predicthq.com/v1/events/",
        headers={
          "Authorization": "Bearer $ACCESS_TOKEN",
          "Accept": "application/json"
        },
        params={
            "place.scope" : "LAX",
            "active.gte" : "2018-03-03",
            "active.lte" : "2018-03-03",
            "category" : "concerts",
            "sort" : "rank"
        }
    )
    
    print(response.json())
    

A snippet of the results are shown below:

    "count": 73,
    "results": [
        {
            "id": "XS5tQbpjKtFeUShTPt",
            "title": "Demi Lovato with DJ Khaled and Kehlani",
            "category": "concerts",
            ...

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.

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

  • GET v1/events/?within=2mi@-37.80036998,144.9715749&active.gte=2018-04-01&active.lte=2018-04-30&category=conferences,expos&sort=rank HTTP/1.1
    Authorization: Bearer $ACCESS_TOKEN
    
  • 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"
    
  • import requests
    
    response = requests.get(
        url="https://api.predicthq.com/v1/events/",
        headers={
          "Authorization": "Bearer $ACCESS_TOKEN",
          "Accept": "application/json"
        },
        params={
            "within" : "2mi@-37.80036998,144.9715749",
            "active.gte" : "2018-04-01",
            "active.lte" : "2018-04-30",
            "category" : "conferences,expos",
            "sort" : "rank"
        }
    )
    
    print(response.json())
    

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.

  • GET v1/events/?country=US&category=public-holidays,school-holidays&active.gte=2018-01-01&active.lte=2018-12-31 HTTP/1.1
    Authorization: Bearer $ACCESS_TOKEN
    
  • 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"
    
  • import requests
    
    response = requests.get(
        url="https://api.predicthq.com/v1/events/",
        headers={
          "Authorization": "Bearer $ACCESS_TOKEN",
          "Accept": "application/json"
        },
        params={
            "country" : "US",
            "active.gte" : "2018-01-01",
            "active.lte" : "2018-12-31",
            "category" : "public-holidays,school-holidays"
        }
    )
    
    print(response.json())
    

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.

  • GET v1/places/?id=6295630,6255149,6252001,5165418 HTTP/1.1
    Authorization: Bearer $ACCESS_TOKEN
    
  • curl -X GET "https://api.predicthq.com/v1/places/?id=6295630,6255149,6252001,5165418" \
         -H "Authorization: Bearer $ACCESS_TOKEN"
    
  • import requests
    
    response = requests.get(
        url="https://api.predicthq.com/v1/places/",
        headers={
          "Authorization": "Bearer $ACCESS_TOKEN",
          "Accept": "application/json"
        },
        params={
            "id" : "6295630,6255149,6252001,5165418"
        }
    )
    
    print(response.json())