API Documentation
Event Occurrences¶
Retrieving Occurrences¶
The following request retrieves all event occurrences:
>>> GET("/123/events/occurrences?fields=event_uuid-dtstart-dtend")
{'items': [['11111111-1111-1111-1111-111111111111',
'2012-08-03T10:00:00',
'2012-08-03T12:30:00'],
['22222222-2222-2222-2222-222222222222',
'2012-10-03T10:00:00',
'2012-10-03T12:30:00'],
['33333333-3333-3333-3333-333333333333',
'2012-10-30T21:00:00',
'2012-10-30T23:30:00'],
['33333333-3333-3333-3333-333333333333',
'2012-10-31T21:00:00',
'2012-10-31T23:30:00'],
['33333333-3333-3333-3333-333333333333',
'2012-11-01T21:00:00',
'2012-11-01T23:30:00']]}
The event with the UUID '33333333-3333-3333-3333-333333333333' appears three times because the event has three occurrences due to its recurrence rule (the occurrences happen on three consecutive days).
Filter by Period¶
We can limit the list of occurrences by passing the period parameter to the resource. The following request retrieves the occurrences happening in October 2012:
>>> GET("/123/events/occurrences?fields=event_uuid-dtstart-dtend&period=2012-10-01_2012-10-31")
{'items': [['22222222-2222-2222-2222-222222222222',
'2012-10-03T10:00:00',
'2012-10-03T12:30:00'],
['33333333-3333-3333-3333-333333333333',
'2012-10-30T21:00:00',
'2012-10-30T23:30:00']]}
As you can see, the second occurrence of the event with the UUID '33333333-3333-3333-3333-333333333333' is not returned even though it happens in October ('2012-10-31T21:00:00'). The reason for that is that the second value of the period parameter here is just a date (2012-10-31) which means '2012-11-01T00:00:00' (00:00:00) and the second occurrence of the event happens at '2012-11-01T21:00:00' (21:00:00).
In order to include all occurrences happening in October, we have to send the following request:
>>> GET("/123/events/occurrences?fields=event_uuid-dtstart-dtend&period=2012-10-01_2012-11-01")
{'items': [['22222222-2222-2222-2222-222222222222',
'2012-10-03T10:00:00',
'2012-10-03T12:30:00'],
['33333333-3333-3333-3333-333333333333',
'2012-10-30T21:00:00',
'2012-10-30T23:30:00'],
['33333333-3333-3333-3333-333333333333',
'2012-10-31T21:00:00',
'2012-10-31T23:30:00']]}
The period parameter here is 2012-10-01_2012-11-01.
You can also send dateimes in the period parameter like:
period=2012-10-01T10:00:00_2012-10-01T20:00:00
Note
It is important to keep in mind that the second value of the period parameter is non-inclusive. This means that sending a request with period=_2012-10-01T20:00:00 will not return event occurrences starting on October 1, 2012 at 8pm (20:00) but only those starting before that datetime.
Instead of using dates or datetimes when using the period parameter, you can also use the special value "now", either as start or end of the period:
GET("/123/events/occurrences?fields=event_uuid&period=now_")
GET("/123/events/occurrences?fields=event_uuid&period=_now")
Order by Distance¶
The returned occurrences can be ordered by the distance from a point in time to their start date/time. What does that mean?
Let's say there are two events in the system:
- A one time event (UUID: 77777777-7777-7777-7777-777777777777)
- A recurring event (UUID: 88888888-8888-8888-8888-888888888888) that starts on the day before the above one-time event and has an occurrence on each of the following two days
By sending the parameter order=distance, the returned list will only contain occurrences that start at or after right now and order the occurrences by how close they happen to right now:
>>> GET("/123/events/occurrences?fields=event_uuid-dtstart&order=distance")
{'items': [['88888888-8888-8888-8888-888888888888', '2025-01-01T14:00:00'],
['77777777-7777-7777-7777-777777777777', '2025-01-02T10:00:00'],
['88888888-8888-8888-8888-888888888888', '2025-01-02T14:00:00'],
['88888888-8888-8888-8888-888888888888', '2025-01-03T14:00:00']]}
The first occurrence of the recurring event (88888888-8888-8888-8888-888888888888) comes first in the list because it happens closest to right now. The next occurrence in the list is the occurrence of the one-time event (77777777-7777-7777-7777-777777777777), which happens one day after that first occurrence but before the second occurrence of the recurring event. Last in the list is the last occurrence of the recurring even.
You can change the default dtstart that order=distance uses (i.e. 'right now') by sending a period parameter with a dtstart value:
>>> GET("/123/events/occurrences?fields=event_uuid-dtstart&order=distance&period=2025-01-02T00:00:00_")
{'items': [['77777777-7777-7777-7777-777777777777', '2025-01-02T10:00:00'],
['88888888-8888-8888-8888-888888888888', '2025-01-02T14:00:00'],
['88888888-8888-8888-8888-888888888888', '2025-01-03T14:00:00']]}
The first occurrence we got in the request _without_ a period parameter is now missing since we're only looking for events that start on or after '2025-01-02T00:00:00'.
Information Expansion¶
The event occurrences resource allows for expanding the retrieved information. This means that by sending the parameter expand you can immediately retrieve additional information about the occurrences' events (and even their locations) without having to send individual requests to the events' API resources.
The expand parameter for this resource allows two options:
- event_uuid
- event_uuid.location_uuid
Sending a request with expand=event_uuid will retrieve the event occurrences' start and end date/times as shown above (if specified in the fields parameter) but will expand the event_uuid* to a dictionary containing the event information:
>>> GET("/123/events/occurrences?expand=event_uuid&fields=event_uuid-dtstart-dtend&period=2012-10-30_2012-10-31")
{'items': [[{'allday': False,
'canonical': True,
'content': '<p><strong>Italian Premier</strong></p><p><em>Lemi Ponifasio // Mau</em></p><p>An elegy to nature and its vitality, its enigma.</p>',
'created': '2012-08-08T10:00:00',
'description': None,
'dtend': '2012-10-30T23:30:00',
'dtstart': '2012-10-30T21:00:00',
'email': None,
'event_source': 'import',
'exdates': [],
'ical_uid': '33333333-3333-3333-3333-333333333333',
'issued': '2012-08-08T10:00:00',
'location_alt': None,
'location_uuid': 'dddddddd-dddd-dddd-dddd-dddddddddddd',
'modified': '2012-08-08T10:00:00',
'perma_url_path': None,
'phone': None,
'prices': None,
'print_description': None,
'rdates': [],
'recurrence_id': None,
'rrule': {'byday': None,
'byhour': None,
'byminute': None,
'bymonth': None,
'bymonthday': None,
'bysecond': None,
'bysetpos': None,
'byweekno': None,
'byyearday': None,
'count': 3,
'freq': 'DAILY',
'interval': 1,
'until': None,
'wkst': None},
'sort_title': None,
'state': 'published',
'time_type': 'DATE-TIME',
'title': 'Birds with skymirrors',
'urlname': 'birds-with-skymirrors',
'user_email': None,
'uuid': '33333333-3333-3333-3333-333333333333',
'website': 'http://teatrodiroma.net'},
'2012-10-30T21:00:00',
'2012-10-30T23:30:00']]}
Sending expand=event_uuid.location_uuid will also expand the event information but will also expand the specific event's location_uuid into a dictionary with the location information:
>>> GET("/123/events/occurrences?expand=event_uuid.location_uuid&fields=event_uuid-dtstart-dtend&period=2012-10-30_2012-10-31")
{'items': [[{'allday': False,
'canonical': True,
'content': '<p><strong>Italian Premier</strong></p><p><em>Lemi Ponifasio // Mau</em></p><p>An elegy to nature and its vitality, its enigma.</p>',
'created': '2012-08-08T10:00:00',
'description': None,
'dtend': '2012-10-30T23:30:00',
'dtstart': '2012-10-30T21:00:00',
'email': None,
'event_source': 'import',
'exdates': [],
'ical_uid': '33333333-3333-3333-3333-333333333333',
'issued': '2012-08-08T10:00:00',
'location_alt': None,
'location_uuid': {'closed': False,
'content': None,
'coords': [41.89599, 12.47674],
'created': '2012-01-01T00:00:00',
'description': None,
'email': None,
'fax': None,
'fb_headline': None,
'fb_show_faces': True,
'fb_show_stream': True,
'fb_url': None,
'geoname_id': 3169070,
'lat': 41.89599,
'location_types': [],
'long': 12.47674,
'modified': '2012-01-01T00:00:00',
'opening_hours': None,
'pcode': '00186',
'phone': None,
'price_index': None,
'print_description': None,
'sort_title': None,
'state': 'published',
'street': 'Largo di Torre Argentina',
'streetnumber': '52',
'thumb_url': None,
'title': 'Teatro Argentina',
'twitter_username': None,
'urlname': 'teatro-argentina',
'uuid': 'dddddddd-dddd-dddd-dddd-dddddddddddd',
'website': None},
'modified': '2012-08-08T10:00:00',
'perma_url_path': None,
'phone': None,
'prices': None,
'print_description': None,
'rdates': [],
'recurrence_id': None,
'rrule': {'byday': None,
'byhour': None,
'byminute': None,
'bymonth': None,
'bymonthday': None,
'bysecond': None,
'bysetpos': None,
'byweekno': None,
'byyearday': None,
'count': 3,
'freq': 'DAILY',
'interval': 1,
'until': None,
'wkst': None},
'sort_title': None,
'state': 'published',
'time_type': 'DATE-TIME',
'title': 'Birds with skymirrors',
'urlname': 'birds-with-skymirrors',
'user_email': None,
'uuid': '33333333-3333-3333-3333-333333333333',
'website': 'http://teatrodiroma.net'},
'2012-10-30T21:00:00',
'2012-10-30T23:30:00']]}
Filter by Tag¶
It is also possible to limit the results to events tagged with a specific tag:
>>> PUT("/123/tags/AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA",
... {'type': 'default',
... 'last_name_or_title': 'Andrews',
... 'urlname': 'andrews',
... 'state': 'approved'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'}
We mark one event as about "Andrews" and another as being authored by "Andrews":
>>> PUT("/123/tags/AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA/authored/11111111-1111-1111-1111-111111111111",
... {'created': '2012-08-12T10:00:00'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/authored/11111111-1111-1111-1111-111111111111'}
>>> PUT("/123/tags/AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA/describes/22222222-2222-2222-2222-222222222222",
... {'created': '2012-08-12T10:00:00'})
{'url': 'https://api.metropublisher.com/123/tags/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/describes/22222222-2222-2222-2222-222222222222'}
Then we can query all events related in any way to that tag:
>>> GET("/123/events/occurrences?fields=event_uuid&tag=AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA")
{'items': [['11111111-1111-1111-1111-111111111111'],
['22222222-2222-2222-2222-222222222222']]}
Or only the events that were authored by "Andrews":
>>> GET("/123/events/occurrences?fields=event_uuid&tag=AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA&predicate=authored")
{'items': [['11111111-1111-1111-1111-111111111111']]}