Filtering Events and Instances

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 (web mode). You will need to replace {{clientname}} with the Spektrix clientname of the organisation you are working with.

Event & Instance IDs

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.

Request

GET

https://system.spektrix.com/{{clientname}}/api/v3/events

Response

[
    {
[
    {
    "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.

Note

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

$expand parameter

Use of special parameter ‘expand’ $expand can reveal additional resources related to the event. Possible values include RelatedEventsto reveal recommended events and RelatedStockItems to reveal related merchandise, where applicable.

v3/events/{{EventId}}/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.

Note

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.

As with events, URI Parameters can be added to help drill down to what you need. 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

Instances

v3/instances

It is also possible to retrieve all instances. 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. These Parameters can be used in conjunction with each other, in any order.

Note

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.

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

The resource isOnSale

The resource isOnSale is exposed for both events (v3/events) and instances (v3/instances or v3/events/{id}/instances).

isOnSale for instances

Indicates whether an instance is marked as “visible” and “on sale” on web in the Admin interface of the system.

isOnSale
true	An instance is set as visible and on sale on web in the Admin interface AND the instance is in the future. The status of the instance does not take into consideration the on sale date, which may be in the future.
false	An instance is set as visible but not on sale on web in the Admin interface OR an instance is in the past and is set as visible on web.

isOnSale for events

Indicates whether an event has instances set as “visible” on web in the Admin interface of the system.

isOnSale
true	An event has at least one instance that is set as ‘visible’ on web in the Admin interface. It will show as isOnSale: true even if the instances are in the past or the start selling date is in the future.

If an event does not meet the criteria to appear as isOnSale: true then by default it will not appear in the API feed.

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 ?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