Working with recurring events

The Recurring Events feature provides a linkage between recurrences of the same event:

• Events that recur each year on the same day, such as Christmas Day.

• Events that recur each year (or month, or other frequency) but change date and potentially location, such as the American Society of Hematology Annual Meeting.

As well as being able to see that an event is recurring, it’s also possible to find all recurrences of the same event.

Example use cases

Recurring Events supports use cases such as:

• Demand Forecasting: When analyzing previous years transactions or bookings, you can align demand spikes with a recurring event and predict expected demand increases for future years.

• Labor Optimization: Knowing why you were busy last year and planning your resource requirements for the same period next year. What if the event changes location? Recurring Events allows you to get this visibility and plan accordingly.

The API represents Recurring Events as an Entity of type event-group with recurring info in iCalendar recurring RRULE format.

The following is an example event with a recurring event-group Entity:

{
  "count": 1,
  "results": [
    {
      "id": "3HieM5mavYqPikiHPw",
      "title": "ASH Annual Meeting",
      "category": "conferences",
      "entities": [
        {
          "entity_id": "vAtN2UDcxySFtZFwLRvqcN",
          "name": "ASH Annual Meeting",
          "type": "event-group",
          "category": "conferences",
          "labels": [
            "business",
            "conference",
            "event-group",
            "expo",
            "recurring"
          ],
          "description": "The American Society of Hematology (ASH) Annual Meeting & Exposition provides an invaluable educational experience and the opportunity to review thousands of scientific abstracts highlighting updates in the hottest topics in hematology.",
          "recurring": {
            "ical": "DTSTART;VALUE=DATE:20141206\nDURATION:P4D\nRRULE:FREQ=YEARLY;INTERVAL=1"
          }
        }
      ],
      ...
    }
  ]
}

Find all instances of a recurring event

The entity.id query parameter allows you to find all Events that are linked to the specified Entity ID. This example uses the "ASH Annual Meeting" recurring event-group Entity ID to find all instances of the Event:

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "entity.id" : "vAtN2UDcxySFtZFwLRvqcN",
        "sort" : "start"
    }
)

print(response.json())

A snippet of the results follows:

{
  "count": 9,
  "results": [
    {
      "id": "6NYlQ7BdJdLy",
      "title": "ASH Annual Meeting",
      "start": "2014-12-06T08:00:00Z",
      "end": "2014-12-10T07:59:59Z",
      ...
    },
    {
      "id": "DGMn5WdRKg6R",
      "title": "ASH Annual Meeting",
      "start": "2015-12-05T05:00:00Z",
      "end": "2015-12-09T04:59:59Z",
      ...
    },
    {
      "id": "l3DQOqMooNQJ",
      "title": "ASH Annual Meeting",
      "start": "2016-12-03T08:00:00Z",
      "end": "2016-12-07T07:59:59Z",
      ...
    },
    {
      "id": "CMAXh5scsAcFyMhgGj",
      "title": "ASH Annual Meeting",
      "start": "2017-12-09T05:00:00Z",
      "end": "2017-12-13T04:59:59Z",
      ...
    },
    {
      "id": "K9z9hS3sXqjH3SmYwq",
      "title": "ASH Annual Meeting",
      "start": "2018-12-01T08:00:00Z",
      "end": "2018-12-05T07:59:59Z",
      ...
    },
    {
      "id": "2RxTdCucMNcLZSsEqW",
      "title": "ASH Annual Meeting",
      "start": "2019-12-07T05:00:00Z",
      "end": "2019-12-11T04:59:59Z",
      ...
    },
    {
      "id": "XDs5aBowsAAopqp5yy",
      "title": "ASH Annual Meeting",
      "start": "2021-12-11T05:00:00Z",
      "end": "2021-12-15T04:59:59Z",
      ...
    },
    {
      "id": "3HieM5mavYqPikiHPw",
      "title": "ASH Annual Meeting",
      "start": "2022-12-10T06:00:00Z",
      "end": "2022-12-14T05:59:59Z",
      ...
    },
    {
      "id": "FFRgbLAfquTFajD3Xq",
      "title": "ASH Annual Meeting and Exposition",
      "start": "2023-12-09T19:00:00Z",
      "end": "2023-12-12T22:00:00Z",
      ...
    }
  ]
}

Find a specific recurrence of an Event

In this example, we find the 2019 instance of the "ASH Annual Meeting":

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "entity.id" : "vAtN2UDcxySFtZFwLRvqcN",
        "start.gte" : "2019-01-01",
        "start.lte": "2019-12-31"
    }
)

print(response.json())

A snippet of the results follows:

{
  "count": 1,
  "results": [
    {
      "id": "2RxTdCucMNcLZSsEqW",
      "title": "ASH Annual Meeting",
      "description": "The American Society of Hematology (ASH) Annual Meeting & Exposition provides an invaluable educational experience and the opportunity to review thousands of scientific abstracts highlighting updates in the hottest topics in hematology.",
      "category": "conferences",
      "labels": [
        "conference",
        "expo",
        "health",
        "medical"
      ],
      "rank": 78,
      "local_rank": 100,
      "phq_attendance": 25000,
      "entities": [
        {
          "entity_id": "Urecg72DAWZw5abb9ZExWh",
          "name": "Orange County Convention Center",
          "type": "venue",
          "formatted_address": "9800 International Drive\nOrlando, FL 32819\nUnited States of America"
        },
        {
          "entity_id": "vAtN2UDcxySFtZFwLRvqcN",
          "name": "ASH Annual Meeting",
          "type": "event-group",
          "category": "conferences",
          "labels": [
            "business",
            "conference",
            "event-group",
            "expo",
            "recurring"
          ],
          "description": "The American Society of Hematology (ASH) Annual Meeting & Exposition provides an invaluable educational experience and the opportunity to review thousands of scientific abstracts highlighting updates in the hottest topics in hematology.",
          "recurring": {
            "ical": "DTSTART;VALUE=DATE:20141206\nDURATION:P4D\nRRULE:FREQ=YEARLY;INTERVAL=1"
          }
        }
      ],
      "duration": 345599,
      "start": "2019-12-07T05:00:00Z",
      "end": "2019-12-11T04:59:59Z",
      "updated": "2023-07-07T02:57:03Z",
      "first_seen": "2019-02-21T00:24:36Z",
      "timezone": "America/New_York",
      "location": [
        -81.4697992,
        28.4245227
      ],
      "geo": {
        "geometry": {
          "coordinates": [
            -81.4697992,
            28.4245227
          ],
          "type": "Point"
        },
        "placekey": "zzw-224@8fy-8hr-pgk"
      },
      "scope": "locality",
      "country": "US",
      "place_hierarchies": [
        [
          "6295630",
          "6255149",
          "6252001",
          "4155751",
          "4167060",
          "4178397"
        ],
        [
          "6295630",
          "6255149",
          "6252001",
          "4155751",
          "4167218",
          "4160983"
        ]
      ],
      "state": "active",
      "private": false,
      "predicted_event_spend": 19879000,
      "predicted_event_spend_industries": {
        "accommodation": 14760000,
        "hospitality": 4179000,
        "transportation": 940000
      }
    }
  ]
}