Data Submission API

Overview

Submitting data via the FlipStats API is simple. We provide clients for the most popular players, but should you need a custom player or even server-side software to submit data then this page describes the format in which to submit it properly. The FlipStats API is designed to be:

  • Simple to understand
  • Easy to implement
  • Fast for submitting a lot of data

As such, it provides only a single input and output format: JSON. JSON is an incredibly simple data format that is supported by most programming languages and frameworks. A slight modification of the format, called JSONP, is also supported to allow submission of data via Javascript in a cross-domain fashion.

API overview chart
API flow chart

Submission Example

{ 
  "user_key": "3xj2lKV0", 
  "players": { 
    "player_id": { 
      "runtime_version": "Flash 10.2.4.1", 
      "client_version": "JW FLV 4.5", 
      "streams": { 
        "filename1": { 
          "metadata": { 
            "width": 640, 
            "height": 480, 
            "duration": 67, 
            "container": "mp4", 
            "vcodec": "h264", 
            "bitrate": 768 
          }, 
          "hits": [ 
            { 
              "started": 1234567890, 
              "elapsed": 5.6, 
              "states": [ 
                { 
                  "name": "buffer", 
                  "mediatime": 0.0, 
                  "realtime": 0.0 
                }, 
                { 
                  "name": "play", 
                  "mediatime": 0.0, 
                  "realtime": 1.0 
                }, 
                { 
                  "name": "seek", 
                  "pos": 14.4, 
                  "mediatime": 2.4, 
                  "realtime": 3.4 
                }, 
                { 
                  "name": "buffer", 
                  "mediatime": 14.4, 
                  "realtime": 3.4 
                } 
                { 
                  "name": "play", 
                  "mediatime": 14.4, 
                  "realtime": 5.0 
                } 
              ] 
            }, 
            { 
              ... hit on the same stream ... 
            } 
          ] 
        }, 
        "filename2": { 
          ... hit on another stream ... 
        } 
      } 
    } 
  } 
}

Response Example

{ 
  "status": "ok", 
  "session_id": 23891 
}

Submission Example (cont)

{ 
  "user_key": "3xj2lKV0", 
  "session_id": 23891, 
  "players": { 
    "player_id": { 
      "streams": { 
        "filename1": { 
          "hits": [ 
            { 
              "started": 1234567890, 
              "elapsed": 15.6, 
              "states": [ 
                { 
                  "name": "pause" 
                  "mediatime": 27.6, 
                  "realtime": 18.2 
                } 
              ] 
            } 
          ] 
        }, 
        ... more files ... 
      } 
    } 
  } 
}

Response Example (cont)

{ 
  "status": "ok", 
  "session_id": 23891 
}

Reference (cont)

States

The states are a objects with various required parameters and optional parameters that depend on the type of state.

Field Description Type Default
name The name of the state (see below for possible values) string required
mediatime The time in seconds as a float into the media stream number required
realtime The time in seconds since this hit's started time number required

The name values and other possible fields are listed below:

Value Parameters Description
buffer none Media is loading and not currently playing
play none Media is currently playing
pause none Media is currently paused by user/script action
seek pos:int Seeking to new position in seconds
stop none Media playback has stopped
volume level:float Media playback volume has changed
mute set:bool Media playback volume was muted/unmuted
fullscreen set:bool Media playback was set to or from fullscreen
rate percentage:float Media playback rate has changed
bitrate kbps:int Media bitrate has dynamically changed

For example, this means if you have a seek state it will look similar to: 

{ 
  "name": "seek", 
  "pos": 123, 
  "mediatime": 3.0, 
  "realtime": 3.5 
}

Data Flow

The data flow when dealing with the FlipStats submission API can be thought of as follows:

  1. Client gathers data over time
  2. Client submits data to API
  3. API returns session identifier
  4. Client gathers more data
  5. Client sends new data with session identifier
  6. API responds with same session identifier
  7. Client gathers more data
  8. ...

On the left you will see an example of one such client submission. All the various fields and requirements are described in the reference below. All submissions must be made to the following URL:

» http://api.flipstats.com/submit?data=...

Reference

This reference describes all possible fields, their values, and which of those values are required.

Root

Field Description Type Default
user_key The key to the user under which account this hit is logged string required
session_id Session-unique integer number required after first submission
players Mapping of player id's to player data object required

Players

Field Description Type Default
runtime_version The version of the runtime (Flash, Silverlight, etc) string null
client_version The version of the client app being tracked string null
streams Mapping of stream names to stream data object required

Streams

Field Description Type Default
metadata Mapping of metadata attributes and values object null
hits A list of hits to this stream from the given player id array null

Hits

Field Description Type Default
started Timestamp of when stream was first ready number required
elapsed The number of seconds of video time played number 0.0
loaded_size The number of bytes downloaded number null
states A list of state changes with time information array null

Note: elapsed and loaded_size may be more than the media duration or size, depending on if the user seeks backwards and how the client handles downloading the stream!

Metadata

Field Description Type Default
title The title of the media string null
duration The duration of the media in seconds (-1 for live events) number null
size The size of the media in bytes number null
container The container format for the media string 'unknown'
bitrate Average bitrate over the media stream in kbps (kbits) number null
vcodec The video codec used string 'unknown'
width The width of the video in pixels number null
height The height of the video in pixels number null
framerate The framerate of the video in frames per second number null
thumb A remote path (HTTP) to the thumbnail for this video string null
acodec The audio codec used string 'unknown'
channels The number of audio channels number null

Container

Value Description
unknown The container format is not known
none There is no container (e.g. MP3 file)
mp4 Quicktime / MP4 / 3GP / F4V
avi AVI
flv Flash Video
mkv Matroska
ogg Ogg
mpegps MPEG Program Stream
mpegts MPEG Transport Stream
asf Windows Media

Video Codec

Value Description
unknown The video codec is not known
none There is no video (e.g. MP3 file)
h264 H.264 / AVC / MPEG4 Part 10
flv Flash Video (Sorenson H.263)

Audio Codec

Value Description
unknown The audio codec is not known
none There is no audio (e.g. video-only file)
mp3 MP3 (MPEG1 audio)
aac Advanced Audio Codec (MPEG2/MPEG4 audio)
wma Windows Media Audio
vorbis Ogg Vorbis
pcm Uncompressed audio

Errors

Errors are returned with a reason, for example: 

{ 
  "status": "fail", 
  "reason": "Invalid JSON!" 
}