Filtering Events from the API
In the following article, links will be referenced as originating from system.spektrix.com. If you have implemented a custom domain for your Integration, please replace system.spektrix.com with your chosen subdomain.
Although we provide Iframes to show event listings, you may wish to create your own using data from our API and allow users to be able to filter these. The below guide walks through the calls to look up events, their instances and how to filter these using URI parameters. For more details about the API, please visit this page and for a full list of all available URI options for these and other calls, please visit our full endpoint guide.
The below is all based on public information via the API and does not require any authentication. You will need to replace {{clientname}} with the Spektrix clientname of the organisation you are working with.
In the below, if pulling Id's from APIv3 to use alongside our Iframes, only the initial integer values are needed for an argument. e.g an ID of 1234ABCDEFGHIJK needs to be shortened to 1234.
Events
v3/events
Using v3/events, you can pull a full list of all Events that have instances set as "Visible" to Web in the Admin interface of Spektrix.
GET https://system.spektrix.com/{{clientname}}/api/v3/events
{
"description": "Event Description",
"htmlDescription": "<div id>\r\n Clients Web Copy \r\n</div>",
"duration": Duration in Minutes,
"imageUrl": "link to image url",
"isOnSale": true,
"name": "Event Name",
"instanceDates": "Date Range of Instances",
"thumbnailUrl": "link to thumbnail image url",
"webEventId": Optional Client ID,
"id": "Event ID",
"firstInstanceDateTime": "YYYY-MM-DDTHH:MM:SS",
"lastInstanceDateTime": "YYYY-MM-DDTHH:MM:SS",
"attribute_Name": "attribute value"
}
As this can provide a large data set, it is possible to add on a series of URI Parameters to help drill down to what you need. The full list can be found here.
When pulling Events we advise only pulling the data required, and recommend running calls in small date batches using the available parameters below starting from "today" unless historic event data is required.
These Parameters can be used in conjunction with each other, in any order.
GET
https://system.spektrix.com/{{clientname}}/api/v3/events?instanceStart_from={{instanceStart_from}}&instanceStart_to={{instanceStart_to}}&onSale={{onSale}}&name={{name}}&attribute_{{name}}={{attributevalue}}&instanceattribute_{{name}}={{value}}
Parameter | Expected Value |
---|---|
instanceStart_from | Date in YYYY-MM-DD (will accept datetime from firstInstanceDateTime output of v3/events) |
instanceStart_to | Date in YYYY-MM-DD (will accept datetime from lastInstanceDateTime output of v3/events) |
onSale | "true" or "false" |
attribute_{{name}} | Event Attribute name and value, see below for detailed steps |
instanceattribute_{{name}} | Instance Attribute name and value, see below for detailed steps |
name | Value is the event name. If the string contains spaces, these will need to be URL encoded |
v3/events/{id}/instances
Passing the returned Event ID from the above call into the v3/events{{id}}/instances endpoint will return all visible instances for that specific event.
As above, URI Parameters can be added to help drill down to what you need.
When pulling Instances we advise only pulling the data required, and recommend running calls in small date batches using the available parameters below starting from "today" unless historic instance data is required.
These Parameters can be used in conjunction with each other, in any order.
GET
https://system.spektrix.com/{{clientname}}/api/v3/events/{{id}}/instances?start_from={{start_from}}&start_to={{start_to}}&attribute_{{name}}={{attributevalue}}
Parameter | Expected Value |
---|---|
start_from | Date in YYYY-MM-DD (will accept datetime from firstInstanceDateTime output of v3/events) |
start_to | Date in YYYY-MM-DD (will accept datetime from lastInstanceDateTime output of v3/events) |
attribute_{{name}} | Instance Attribute name and value, see below for detailed steps |
v3/instances
It is also possible to retrieve all instances for any event. The response for this API call can become very large, so it is best to use it only in combination with the URI Parameters below.
When pulling Instances we advise only pulling the data required, and recommend running calls in small date batches using the available parameters below starting from "today" unless historic instance data is required.
These Parameters can be used in conjunction with each other, in any order.
GET
https://system.spektrix.com/{{clientname}}/api/v3/instances?startFrom={startFrom}&startTo={startTo}&eventName={eventName}&attribute_{{name}}={{attributevalue}}&eventattribute_{{name}}={{eventattributevalue}}
Parameter | Expected Value |
---|---|
startFrom | Date in YYYY-MM-DD (will accept datetime from firstInstanceDateTime output of v3/events) |
startTo | Date in YYYY-MM-DD (will accept datetime from lastInstanceDateTime output of v3/events) |
attribute_{{name}} | Instance Attribute name and value, see below for detailed steps |
eventattribute_{{name}} | Event Attribute name and value, see below for detailed steps |
eventname | Value is the event name. If the string contains spaces, these will need to be URL encoded |
Using Attributes
To filter using attributes in the v3/events or v3/events/{{id}}/instances or v3/instances call, you must provide the respective event or instance attribute parameter in the following format.
?attribute_(Attribute Name In PascalCase)=value
For example, if you have an Event attribute called "Event Genre", and the value the client has set for this is "Comedy". This would be set up as...
?attribute_EventGenre=Comedy
If the value is a string and contains spaces, these will need to be URL encoded. If my attribute value is "Musical Comedy", this would be used as...
?attribute_EventGenre=Musical%20Comedy
If a client is using a checkbox attribute, these can be filtered using 1
if ticked or 0
if unticked.
?attribute_AttributeName=1