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 but change date and potentially location, such as the American Society of Haematology Annual Meeting.
Note recurring events can also recur at frequencies other than annually.
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
- Demand Forecasting: When analysing previous years transactions or bookings, you can align demand spikes with a recurring event and predict expected demand increases for future years.
- Labour 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.
Example Output
All recurrences of the same event link to event group entity. It can be found on an event record as an array of entities with the type of event-group.
{
...
"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\nRRULE:FREQ=YEARLY;INTERVAL=1"
}
}
],
...
}How can the API be used?
The API focus around searching for events, so after finding an event with an event group entity, you can then search for all instances of the event using the entity.id filter. Combine entity.id with date filters to find instances of the recurring event within certain time periods.
Example One: Find all instances of the ASH Annual Meeting using the
entity_id
GET /v1/events/?entity.id=vAtN2UDcxySFtZFwLRvqcN
{
"count": 6,
"overflow": false,
"next": null,
"previous": null,
"results": [
{
...
"id": "2RxTdCucMNcLZSsEqW",
"title": "ASH Annual Meeting",
"start": "2019-12-07T05:00:00Z",
"end": "2019-12-11T04:59:59Z",
"entities": [...],
...
},
{
...
"id": "K9z9hS3sXqjH3SmYwq",
"title": "ASH Annual Meeting",
"start": "2018-12-01T08:00:00Z",
"end": "2018-12-05T07:59:59Z",
"entities": [...],
...
},
{
...
"id": "CMAXh5scsAcFyMhgGj",
"title": "ASH Annual Meeting",
"start": "2017-12-09T05:00:00Z",
"end": "2017-12-13T04:59:59Z",
"entities": [...],
...
},
{
...
"id": "l3DQOqMooNQJ",
"title": "ASH Annual Meeting",
"start": "2016-12-03T08:00:00Z",
"end": "2016-12-07T07:59:59Z",
"entities": [...],
...
},
{
...
"id": "DGMn5WdRKg6R",
"title": "ASH Annual Meeting",
"start": "2015-12-05T05:00:00Z",
"end": "2015-12-09T04:59:59Z",
"entities": [...],
...
},
{
...
"id": "6NYlQ7BdJdLy",
"title": "ASH Annual Meeting",
"start": "2014-12-06T08:00:00Z",
"end": "2014-12-10T07:59:59Z",
"entities": [...],
...
}
]
}Example Two: Find the 2019 instance of the ASH Annual Meeting using the
entity_id
GET /v1/events/?entity.id=vAtN2UDcxySFtZFwLRvqcN&start.gte=2019-01-01&start.lte=2019-12-31{
"count": 1,
"overflow": false,
"next": null,
"previous": null,
"results": [
{
"relevance": 1,
"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,
"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\nRRULE:FREQ=YEARLY;INTERVAL=1"
}
},
{
"formatted_address": "9800 International Drive\nOrlando, FL 32819\nUnited States of America",
"entity_id": "Urecg72DAWZw5abb9ZExWh",
"type": "venue",
"name": "Orange County Convention Center"
}
],
"duration": 345599,
"start": "2019-12-07T05:00:00Z",
"end": "2019-12-11T04:59:59Z",
"updated": "2019-02-28T03:56:33Z",
"first_seen": "2019-02-21T00:24:36Z",
"timezone": "America/New_York",
"location": [
-81.469799,
28.424523
],
"scope": "locality",
"country": "US",
"place_hierarchies": [
[
"6295630",
"6255149",
"6252001",
"4155751",
"4167060",
"4178397"
],
[
"6295630",
"6255149",
"6252001",
"4155751",
"4167218",
"4160983"
]
],
"state": "active"
}
]
}