This end point returns all the Places of the targeted Company/organization

Finds a specific Sporfie Event for a given place and time.

The end point looks for the event that started after, and within one hour of, the given date and time and returns its unique identifier. If there are several matching events (multiple events on that place within the same hour), the key of the first one is returned.

Important: the date & time information must be given in UTC, not local time.

Returns the key of the event currently active on the given place.

If no event is currently active on that place a 404 is returned instead.

Finds events belonging to a given company/organization and having a given state.

The results are paginated and include a trimmed-down representation of found events. For the full event data about a particular event and separate request should be made on the Event data endpoint with the event key retrieved from this list.

Event states

Three event states are supported:

• future - the event has not started yet
• current - the event has started but not finished yet
• past - the event has finished

Event ordering

The order of events in the response depends on the state of the events:

• future - increasing order of scheduled start time
• current - increasing order of start time
• past - decreasing order of start time

This end point returns all the relevant data for the given event key.

Note event data changes over time as the event unfolds, e.g. live streams are started and stopped, moments are captured, etc.

This API returns a snapshot of the event data at the time of the request. To stay informed of changes in the event data, use the Watch API.

eventKey may either be a Sporfie-internal event key, or an event's externalID.

Deletes an event.

eventKey may either be a Sporfie-internal event key, or an event's externalID.

An event may only be deleted if it is not currently running (has started and has not yet ended).

Creates an event in the Sporfie database.

The event's externalID is set to the value of the eventKey parameter. Upon successful event creation, the event's internal ID is returned in the response in the eventKey field. The event may thereafter be referred to either by its externalID or its internal eventKey.

You are free to choose your external ID as you see fit, within the following constraints:

• ASCII characters in the character set [-_0-9a-zA-Z]
• maximum length of 64 bytes
• unique and not already used in the context of your access to this system

Only the name and location fields are mandatory in the body data, if placeKey is not set. If placeKey is set, location field is optional because the location will be inherited from the place. name may not be emtpy.

The sport field must be one of the following code:

• baseball: Baseball
• basketball: Basketball
• beachvolleyball: Beach Volleyball
• bowling: Bowling
• football: Football
• frontenis: Frontenis
• futsal: Futsal
• golf: Golf
• hockey: Hockey
• lacrosse: Lacrosse
• other: Other
• soccer: Soccer
• tennis: Tennis
• unihockey: Floorball
• volleyball: Volleyball

If the given sport is not one of those, or if not provided, other will be used.

If placeKey is present, then so must scheduledStartTime and scheduledEndTime.

When provided, scheduledStartTime and scheduledEndTime must both be present and be in the future and scheduledEndTime must be greater than scheduledStartTime by at least 5 minutes.

The thumbnailURL must point to a publicly accessible image resource. The image is copied by the Sporfie system and may be resized or cropped to fit Sporfie's requirements.

Modifies an existing event.

eventKey may either be a Sporfie-internal event key, or an event's externalID.

No field is mandatory in the body data. Only fields present in the body data will be updated in the event, other fields will be left unmodified. The location and metadata fields are considered as atomic values in that respect.

When present, scheduledStartTime and scheduledEndTime must be in the future. Current values of scheduledStartTime and scheduledEndTime must be in the future to be modifiable. The value of placeKey may not be modified if scheduledStartTime is in the past.

The thumbnailURL must point to a publicly accessible image resource. The image is copied by the Sporfie system and may be resized or cropped to fit Sporfie's requirements.

Immediately closes an event.

When an event is closed, its live streams stop and no new clip generated.

Add a score entry in the score stream of the event.

eventKey may either be a Sporfie-internal event key, or an event's externalID.

Delete a score entry from the score stream.

Register for notification on event changes.

Call this end point when you need to be notified of changes on a specific event.

eventKey may either be a Sporfie-internal event key, or an event's externalID.

Once registered, your webhook will be called whenever anything changes in the event. A change of any of the following event property will trigger a callback

• event info (name, location, sport, pin codes, teams, start date, end date, organization, public pages, tags)
• moment addition or state change (e.g. new video)
• highlights video addition
• media file (full event recording) addition or update
• live stream changes

Your webhook is called with the updated event data:

POST {webhook}
{
   ... // Event data, in the same format as returned by the Event data end point
}

This registration call is idempotent, calling it several times will register only one webhook for a given event and any previously registered webhook will be replaced with the new one.

When you don't need to be notified of updates anymore, call the same endpoint with the DELETE verb to unregister.

Important: the registration is valid for a maximum of 12 hours, after which you webhook will be unregistered. To maintain your webhook, you must re-register it within that time limit.

Call this endpoint to unregister from notifications on a given Event.

event_key may either be a Sporfie-internal event key, or an event's externalID.

Use this end point to validate your overlay templates.

You can specify a source video to use using sourceURL or use our default test video by not providing a sourceURL.

The source video is trimmed down to 15 seconds.

Your overlays will be applied to the video and the resulting video's URL is returned in the answer to the call. The video is available for 1 hour at that URL.

The video generation process takes about 30 seconds (up to a minute on the first call) to complete.

Creates a Click and triggers the recording of a Moment with video clips.

All currently active cameras generate a video clip for the requested time range and upload it to the Sporfie system to create a multi-angle Moment.

eventKey may either be a Sporfie-internal event key, or an event's externalID.

If no startTime and endTime are provided, the default settings for the event's sport are used to compute a recording window.

The score field is an unconstrained dictionary containing the score information for that moment in time. It is stored as is and will appear at that time stamp in the event's score stream.

The players field is optional and lists the players involved in the Moment. When present, this information is used by the Sporfie WebApp to allow the user to filter Moments by player on the Event page.

The metadata field is an optional dictionary that may be used by the caller to store any custom information he/she may want to associate with the Moment. It is stored as is in the Moment generated by the click. See the description of the field for restrictions on the content of this dictionary.

The generated video clips may be augmented with overlays. The list of of overlays to apply is passed in overlays. See the definition of Overlay for details. All clips have the same overlays.

Note retrieving the clips and applyfing the overlays takes a few seconds. Getting a positive response from the server does not indicate that the videos are available, only that the request has been accepted and that the process of generating the videos is under way.

Overlays

An Overlay is a still picture burned into a video clip at a fixed location with a fixed size starting at a given time and for a given duration.

Overlay image

There are two ways to provide the picture to be burned in

• a URL to a valid PNG or JPG file
• a URL to an HTML template and a matching list of values for placeholders found in the HTML template

Image url

The imageSource url must point to a freely accessible and valid PNG or JPEG file. When burned into the video, the aspect ratio of the image is maintained.

Template

The templateSource url must point to a freely accessible and valid HTML file.

The HTML may contain any number of placeholders that shall be replaced by values found in the values dictionary.

The template must meet the following requirements:

• a meta entry specifying the natural rendering size for the scoreboard must be present in the file <meta renderWidth="410" renderHeight="27"/>. The rendered overlay will have the specified size. Note that this is not the final size that the overlay will have in the video, that size is specified by heightPercentOfHeight (see below).
• all CSS must be included in the HTML file in <style> entries
• no <script> entry is permitted
• placeholders in the template shall be framed with square braquets so as to ensure proper replacement without interference with the rest of the HTML. For instance the placeholder text1 shall be used in the HTML as [text1], e.g. <div>[text1]</div>.
• The keys of the values dictionary are the name of the placeholders, without the braquets, e.g. { "text1": "Training session" }. All placeholders found in the template must have a value in the values dictionary (which can be an empty string if needed).
• to allow for round corners and visually separated elements, the template is rendered over a transparent background, so <body> must be given a background-color if one does not want a transparent background.
• external fonts may be referenced in <style> entries as @font-face, e.g.

      @font-face {
        font-family: 'Roboto';
        font-style: normal;
        font-weight: 400;
        src: url(https://fonts.gstatic.com/s/roboto/v27/KFOmCnqEu92Fr1Me5Q.ttf) format('truetype');
      }

The downloaded template and the values are used to generate a PNG image, which is then burned into the video at the given location and time.

Here is a sample template:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta renderWidth="410" renderHeight="27" />
    <style>
      @font-face {
        font-family: 'Roboto';
        font-style: normal;
        font-weight: 400;
        src: url(https://fonts.gstatic.com/s/roboto/v27/KFOmCnqEu92Fr1Me5Q.ttf) format('truetype');
      }
      body {
        width: 100vw;
        height: 100vh;
        margin: 0;
        overflow: hidden;
        font-family: 'Roboto';
      }
      .Score {
        background-color: white;
        color: black;
        font-size: 20px;
        text-align: center;
      }
      .team {
        font-size: 80%;
        display: inline-block;
        padding: 0.1em 0.4em;
        background-color: white;
        color: black;
        vertical-align: middle;
        width: 5em;
        white-space: nowrap;
        overflow: hidden;
        text-overflow: ellipsis;
        text-transform: uppercase;
      }
      .score {
        font-weight: bold;
        display: inline-block;
        padding: 0.1em 0.4em;
        background-color: black;
        color: white;
        vertical-align: middle;
        min-width: 2em;
      }
      .period {
        display: inline-block;
        padding: 0.2em 1em;
        height: 100%;
        font-size: 65%;
        font-weight: bold;
        vertical-align: middle;
        min-width: 2em;
      }
    </style>
  </head>
  <body>
    <div class="Score">
      <div class="team">[home_team]</div>
      <div class="score">[left]</div>
      <div class="period">[period]</div>
      <div class="score">[right]</div>
      <div class="team">[away_team]</div>
    </div>
  </body>
</html>

Placement and sizing

The overlay image is placed in the position specified by position:

position: {
  horizontal: 'left' | 'center' | 'right',
  vertical: 'top' | 'center' | 'bottom'
}

For instance:

{
  ...
  "position": { "horizontal": "left", "vertical": "center" }
  ...
}

will position the overlay on the left side of the video, vertically centered.

The size of the image in the video is defined by the heightPercentOfHeight or widthPercentOfWidth parameter, which specifies the height or width of the image in percent of the height or width of the video. Exactly one of the two parameters must be specified, the other dimension is computed according to the aspect ratio of the image. If both parameters are present, heightPercentOfHeight takes precendence.

When the overlay is placed in a corner or a side, a margin is added vertically and horizontally to detach the overlay from the border of the video. The size of this margin (both horizontally and vertically) is a percentage of the video's width (marginPercentOfWidth) or height (marginPercentOfHeight), either one parameter may be specified, but not both. If both are present, marginPercentOfHeight takes precedence.

Placement in time

Unless specified otherwise, the overlay is shown from the start to the end of the video.

The startTime and duration parameters allow to time the display of the overlay more precisely.

This end point returns the data for a given Moment.

Modifies some properties of a moment.

No field is mandatory in the body data. Only fields present in the body data will be updated in the moment, other fields will be left unmodified.