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

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 2018active.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.

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 holidayscategory=public-holidays,school-holidays, which are happening in the United States of America (US)country=US, in 2018active.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.

curl -X GET "https://api.predicthq.com/v1/places/?id=6295630,6255149,6252001,5165418" \
     -H "Authorization: Bearer $ACCESS_TOKEN"