Highlighting Access Performances on a Website

This document provides technical guidance for web developers to integrate and display information about accessible performances on a client's website using the Spektrix API.

Prep

Understanding Spektrix Concepts & Attribute Types

• Understanding Instance Attributes: Instance Attributes are custom data fields that can hold additional information for Instances. . Each client system can have its own sets of Attributes. We have a glossary of terms and also additional content on our Support Centre.

• Attribute Types: Though it is possible to set up different Attribute types (checkbox, dropdown, free text), it is likely that attributes to signify access performances will be a checkbox. If an attribute is marked as true, it should be displayed on the performance listing for that instance.

Understanding Client Needs

With the above information in mind, ensure you are working with the client to understand their specific needs and develop a solution that matches what they are envisioning.

• Existing Event and Instance Attributes: Do they have any existing event or Instance Attributes related to Accessibility (or any other data they would like displayed)? Understanding the current Attribute structure will help us determine if any new Attributes need to be created or if existing ones can be utilized.
• Future Needs: It's important to discuss potential future requirements with the client. Do they anticipate adding new accessibility Attributes or display options in the future? Considering these potential needs will help ensure the integration is scalable and adaptable to future changes.
• Display Preferences: How does the client envision a user interacting with the Accessibility information? Is it merely to display this information on their website? Would it be for Events, Instances, or both? For example, will they want this data to inform how shows are filtered? Or is it just icons being displayed next to certain Instances? Do they expect this to be icons, labels, tooltips, or something else?
• Accessibility Attributes: Understand the specific types of accessible performances they offer and how they are mutually exclusive or not (e.g., Audio Described, Captioned, Sign Language Interpreted, Wheelchair Accessible).

API Endpoint

Retrieving Instance Data

To retrieve Instance data for a particular event, we can use the following endpoint:

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

• Replace {{clientname}} with the client’s system name
• Replace {{eventId}} with the specific event ID
• Include start_from and start_to parameters (YYYY-MM-DD format) to filter results by date for optimal performance. More on filtering is available here.

For example, you could get a response that looks like:

[
    {
        isOnSale: false,
        planId: "2401AMBSVDSNBDLGKMKJVPMHNLQGTKHSV",
        priceList: { id: "11006ARBDQVDLHDNSGMTTRRNQLQCLBPSP"},
        event: { id: "10001AJDMSTLMNDPDNVDDGJGHCCDBRDDD" },
        start: "2021-11-01T19:30:00",
        startUtc: "2021-11-01T19:30:00",
        startSellingAtWeb: "2023-10-01T00:00:00",
        startSellingAtWebUtc: "2023-09-30T23:00:00Z",
        stopSellingAtWeb: "2021-11-01T18:30:00",
        stopSellingAtWebUtc: "2021-11-01T18:30:00Z",
        webInstanceId: null,
        cancelled: false,
        id: "25201ANDKMVTTJTBHCHVPRBNBQSNTLMKN",
        hasBestAvailableOverlay: true,
        attribute_AccessCaptioned: false,
        attribute_AccessSigned: false
    },
    {
        isOnSale: false,
        planId: "2401AMBSVDSNBDLGKMKJVPMHNLQGTKHSV",
        priceList: { id: "7401ABQKCMHPSMGCDJCDKPNHPKRBSBRLS" },
        event: { id: "10001AJDMSTLMNDPDNVDDGJGHCCDBRDDD" },
        start: "2021-11-04T19:30:00",
        startUtc: "2021-11-04T19:30:00",
        startSellingAtWeb: "2023-10-01T00:00:00",
        startSellingAtWebUtc: "2023-09-30T23:00:00Z",
        stopSellingAtWeb: "2021-11-04T18:30:00",
        stopSellingAtWebUtc: "2021-11-04T18:30:00Z",
        webInstanceId: null,
        cancelled: false,
        id: "25202ARQMPJNTJRKCMTBCKCJPMRQJMJCC",
        hasBestAvailableOverlay: true,
        attribute_AccessCaptioned: true,
        attribute_AccessSigned: false
    },
    {
        isOnSale: false,
        planId: "2401AMBSVDSNBDLGKMKJVPMHNLQGTKHSV",
        priceList: { id: "7401ABQKCMHPSMGCDJCDKPNHPKRBSBRLS" },
        event: { id: "10001AJDMSTLMNDPDNVDDGJGHCCDBRDDD" },
        start: "2021-11-06T19:30:00",
        startUtc: "2021-11-06T19:30:00",
        startSellingAtWeb: "2023-10-01T00:00:00",
        startSellingAtWebUtc: "2023-09-30T23:00:00Z",
        stopSellingAtWeb: "2021-11-06T18:30:00",
        stopSellingAtWebUtc: "2021-11-06T18:30:00Z",
        webInstanceId: null,
        cancelled: false,
        id: "25203ARMVCNDBJMGQSMPRDQDDRHSGKJTL",
        hasBestAvailableOverlay: true,
        attribute_AccessCaptioned: true,
        attribute_AccessSigned: true
    }
]

Excellent! You'll notice that there are two Attributes set up for Access called attribute_AccessCaptioned and attribute_AccessSigned. Two of the three Instances have true set for the captioned performances and only the final third Instance has true set for signed performances.

note

Attributes on each individual system will be unique: they will not necessarily be named as in this example nor will they necessarily be boolean values.

You can then use this data to surface information based upon each Event and Instance as you and your client have seen fit based upon your discussions earlier. As mentioned, this could be used in a calendar filtering mechanism or a set of icons next to each Instance to denote them.

Other Important Considerations

• Caching: Given that the information for these Events and Instances is unlikely to change frequently or on a regular basis, these API calls are designed to be made server-side. We recommend that you set up a regular (say overnight) job that syncs changes to these as well as a way for a client to trigger on-demand sync should they need to make an immediate change to their Attributes or any other part of their Event or Instance information.
• Date Ranges: As noted above, for optimal performance, filter by date range using start_from & start_to, and InstanceStart_from and InstanceStart_to, especially when retrieving data.

Next Steps

Implementation and Testing

1. Refer to Spektrix API Documentation: Consult the Spektrix API documentation for detailed information about endpoints, parameters, and response formats.
2. Test API Calls: Thoroughly test API calls with the client's Spektrix system to ensure accurate data retrieval and filtering.
3. Implement and Display: Integrate the API calls into the website's code and display the accessible performance information according to the client's specifications and preferences.