Introduction to the Firehose

How does it work?

Unlike the imin Events API, the Firehose is not a search API. It is a “feed” that is compatible with the OpenActive Modelling Specification and published using the OpenActive Paging Specification (RPDE).

You read a feed from the beginning, one page at a time, and store its items in your own datastore. When you reach the end, you keep polling. The feed then gives you every item that has been added, changed or deleted since you last asked. The OpenActive page How an RPDE data feed works explains this in more detail.

Caution

Terms of use for access to the imin Firehose differ from the standard terms. Please see Firehose Usage Policy & Restrictions.

The Four Feeds

The Firehose has two types of data. Each type has a parent feed and a child feed:

Type	Parent feed	Child feed	Concepts
Events	session-series, containing SessionSeries	scheduled-sessions, containing ScheduledSessions	EventSeries
Facilities	facility-uses, containing FacilityUses	slots, containing Slots	FacilityUses and IndividualFacilityUses

The parent describes the session or facility. The child is a single date and time at which it can be attended or used.

What an Item Looks Like

Every page of a feed contains a list of items. Each item has the same outer structure:

{
  "state": "updated",
  "kind": "SessionSeries",
  "id": "https://firehose-cdn.imin.co/firehose-cdn/refimpl/v2/session-series/https%3A%2F%2Fexample.com%2Fsession-series%2F157",
  "modified": 21343296230,
  "data": {
    "@context": [
      "https://openactive.io/",
      "https://imin.co/",
      "https://openactive.io/ns-beta"
    ],
    "@type": "SessionSeries",
    "@id": "https://firehose-cdn.imin.co/firehose-cdn/refimpl/v2/session-series/https%3A%2F%2Fexample.com%2Fsession-series%2F157",
    "...": "..."
  }
}

• state is updated or deleted. For updated, replace any copy you have stored with data. For deleted, remove the item from your datastore. A deleted item has no data.
• kind is SessionSeries, ScheduledSession, FacilityUse or FacilityUse/Slot.
• id is the item’s identifier. It is the same as data["@id"].
• modified is a number that increases each time the item changes.
• data is the session or facility itself.

Note

In the session-series feed, data.superEvent is the EventSeries that the SessionSeries belongs to. The fields that describe the activity are inside it. These include name, description, activity and organizer.

Identifiers Are Not Links

The @id of an item looks like a URL, but it is only an identifier. For example:

https://firehose-cdn.imin.co/firehose-cdn/refimpl/v2/facility-uses/https%3A%2F%2Fexample.com%2Ffacility-uses%2F1

• It is guaranteed to be unique.
• It does not need to resolve to anything. Do not request it.
• Treat it as an opaque string. Store it and compare it exactly as it is given. Do not parse it, and do not build one yourself, as you cannot rely on its format.

Cross-Referencing Endpoints

A SessionSeries has one or more ScheduledSessions, and a FacilityUse has one or more Slots. Some Slots relate to an IndividualFacilityUse within a FacilityUse.

To link a child to its parent, match these fields:

• ScheduledSession to SessionSeries. The ScheduledSession’s data.superEvent matches the SessionSeries’ data["@id"].
• Slot to a FacilityUse without the individualFacilityUse property. The Slot’s data.facilityUse matches the FacilityUse’s data["@id"]. This Slot represents an aggregation of courts (e.g. 6 badminton courts available).
• Slot to a FacilityUse with the individualFacilityUse property. The Slot’s data.facilityUse matches one of the FacilityUse’s data.individualFacilityUse[]["@id"] IDs. This Slot relates to a single court (e.g. Badminton Court 3).

A child can arrive before its parent, because the two feeds are updated separately. See Orphaned ScheduledSessions.