# EventSeries

{% hint style="info" %}
For an introduction to data publishing via open data feeds, and `EventSeries`, `SessionSeries` and `ScheduledSessions`, please refer to [this page](https://developer.openactive.io/publishing-data/data-feeds) of the OpenActive Developer Docs.
{% endhint %}

## Composition of `EventSeries`

The entire API is built around delivering physical activities to consumers. The most important endpoint delivering an app on top of the imin Events API, which helps customers find physical activities, is `/events-api/v2/event-series` (see [Events API Reference](https://docs.imin.co/platform-products/search/imin-events-api/api-reference) for Swagger reference documentation). So, what is an `EventSeries`?

An `EventSeries` is composed of three main types of objects:

* `EventSeries`: a *particular physical activity*;<br>
* `SessionSeries`: a *particular location* - an `EventSeries` can have multiple `SessionSeries` items as children; and<br>
* `ScheduledSession`: a *particular time* or according to a *particular schedule* - a `SessionSeries` can have multiple `ScheduledSession`s items as children.

### Examples

1. A local volunteering organization named **BeneficialRun** is organizing a **Run** in **Romford** called **Run and plant trees in local park**. This session is going to take place on **Thursday 13th September at 7:30pm**.<br>
2. These is a leisure centre named **MoreGood Leisure Centre** in **Moorgate, London**. They host **Swimming Lessons** every **Tuesday at 8:00am starting from 23rd October and running for 6 months**. The swimming lessons are for **Intermediate** swimmers and the instructor's name is **Brad Chadley**.

In the above examples (these are made up), the values in bold directly correlate to fields in an `EventSeries`, a `SessionSeries` or a `ScheduledSession`. For example, in the first example, the `EventSeries` would have a `.name` field with value: **Run and plant trees in local park**.

### Specifications

The specification for an `EventSeries` is defined in the [API Reference](https://docs.imin.co/platform-products/search/imin-events-api/api-reference). It is a stricter sub-set of the OpenActive Specification for [`Event`](https://www.openactive.io/modelling-opportunity-data/#describing-events-code-schema-event-code-).

## Types of `EventSeries`

### One-to-One

Example #1 above is a physical activity that only happens at one place and at a specific time. Therefore, the `EventSeries` that describes it will have only *one* `SessionSeries`, which will in turn have only *one* `ScheduledSession`. As such, this an example of a **One-to-One `EventSeries`**.

Snippet from Example #1's session:

```javascript
{
  "type": "EventSeries",
  "name": "Run and plant trees in local park",
  // other fields that describe the type of physical activity...
  "subEvent": [
    "type": "SessionSeries",
    // fields that describe the location of the physical activity...
    "subEvent": [
      {
        "type": "ScheduledSession",
        "startDate": "2018-09-13T18:30:00Z", // equal to 7:30pm in British Summer Time
        "endDate": "2018-09-13T20:00:00Z",
        "duration": "PT90M" // ISO-8601 Duration. This means "90 minutes"
      }
    ]
  ]
}
```

### One-to-Many

Example #2 above is a physical activity that occurs on *many* occasions. If the same activity is rolled out in other leisure centres, it may also occur in *many* locations. Therefore, the `EventSeries` will have *one or more* `SessionSeries` items, each of which will have *one or more* `ScheduledSession` items. As such, this is an example of a **One-to-Many `EventSeries`**.

Snippet from Example #2's session:

```javascript
{
  "type": "EventSeries",
  "name": "Swimming Lessons",
  // other fields that describe the type of physical activity...
  "subEvent": [
    {
      "type": "SessionSeries",
      "location": {
        "type": "Place",
        "name": "MoreGood Leisure Centre"
      },
      // other fields that describe the location of the physical activity...
      "subEvent": [
        {
          "type": "ScheduledSession",
          "startDate": "2018-10-23T07:00:00Z", // 08:00 in British Summer Time
          "endDate": "2018-10-23T08:00:00Z",
          "duration": "PT1H" // ISO-8601 Duration. This means "1 hour"
        },
        {
          "type": "ScheduledSession",
          "startDate": "2018-10-30T08:00:00Z", // BST ends on 25th October, so this is now 08:00 in GMT
          "endDate": "2018-10-30T09:00:00Z",
          "duration": "PT1H"
        },
        // and so on until April 23rd...
      ],
    },
    {
      "type": "SessionSeries",
      "location": {
        "type": "Place",
        "name": "SomewhereElse Leisure Centre"
      },
      "subEvent": [ /* ... */ ]
    },
    // ...etc
  ]
}
```