> For the complete documentation index, see [llms.txt](https://docs.predicthq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-recurring-events.md). # 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. {% hint style="info" %} **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. {% endhint %} 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: ```json { "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: ```python 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: ```json { "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": ```python 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: ```json { "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 } } ] } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.predicthq.com/getting-started/guides/date-and-time-guides/working-with-recurring-events.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.