Filtering Firehose Data

The Firehose contains all data, so your application decides which items to keep. You can filter in two places:

• While you harvest a feed. You discard an item as you read it and never store it. The OpenActive Paging Specification calls this in-stream filtering.
• When you read from your datastore. You store the item, and filter when you query it.

Caution

While you harvest, filter only on values that will never change.

A feed does not send an item again until that item next changes. If your filter changes after you have discarded an item, the only way to get the item back is to harvest the whole feed again. Resyncs are limited.

Filters That Are Safe While You Harvest

A filter is safe to apply while you harvest if it gives the same result for the same item every time. In practice, that means comparing a field with a value that does not change.

These are some examples, not a complete list:

• Sessions by activity. In the session-series feed, check data.superEvent.activity[]["@id"]. For example, keep https://openactive.io/activity-list#f2ea7405-6098-4378-b0fe-4e398a659fc4 (Tennis).
• Sessions that only run online. In the session-series feed, check data.superEvent.eventAttendanceMode. Discard https://schema.org/OnlineEventAttendanceMode to leave these sessions out.
• Facilities by type. In the facility-uses feed, check data.facilityType[]["@id"]. For example, keep https://openactive.io/facility-types#becfafc0-c63f-444c-aed5-a3665f2d172d (Tennis Court).

In the session-series feed, data.superEvent is the EventSeries that the SessionSeries belongs to.

Activity IDs come from the OpenActive Activity List and facility type IDs from the OpenActive Facility Types.

The scheduled-sessions and slots feeds do not contain these fields. Store their items, and link each one to its parent when you read from your datastore. See Cross-Referencing Endpoints.

Include Child Activities

The Activity List is a hierarchy. Tennis, for example, has children such as Padel Tennis and Wheelchair Tennis. A Padel Tennis session may be tagged with Padel Tennis only, and not with Tennis.

To keep everything under an activity, match against that activity and all of its children. In JavaScript you can use skos.js with a copy of the Activity List:

const skos = require('@openactive/skos');

const TENNIS_ID = 'https://openactive.io/activity-list#f2ea7405-6098-4378-b0fe-4e398a659fc4';

// activityList is the JSON from https://openactive.io/activity-list/activity-list.jsonld
const scheme = new skos.ConceptScheme(activityList);
const tennis = scheme.getConceptByID(TENNIS_ID);
const tennisAndChildren = [tennis, ...tennis.getNarrowerTransitive()];
const idsToKeep = tennisAndChildren.map((concept) => concept.id);

New activities are added to the Activity List from time to time, so refresh your copy regularly.

Filters to Apply When You Read

These filters give a different result for the same item at different times. Store the items and apply the filter when you query your datastore.

Filter	Why it cannot be applied while you harvest
By date, e.g. only sessions that start in the next 5 days	”Today” moves. A session that you discard for being too far ahead is not sent again when its date gets closer
By Seller, using the Bookable Sellers feed	The Sellers that are bookable by you change over time. Store the opportunities and the Sellers, and match them when you read