Client APIs
At its core, SyncTV is an API driven service. The APIs themselves are easy enough for developers to understand, but understanding the ecosystem is a little trickier. We've created the following tutorials to help you get your head around it.

Topics:

  • Views

This document describes the API for updating and monitoring the viewing progress of media.

Note:
Each call to the SyncTV V2 API described in this section requires a MD5 hash signature.
See the Authorization (User) API for details on generating the MD5 hash signature.
Actions

Url:

  • [GET] /api/v2/media/:id/start.[xml|json]

Declare the point (in seconds) at which the user started watching the specified media.

Note:
This will return only success or failure, no content.
Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
Example Request

The following URL marks the watch start point for media 1 at the watched_time value.
[GET] https://service_name.synctv.com/api/v2/media/1/start.xml?watched_time=4435&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Integer) offset — Used for pagination of response data (default: 25 items per response). Specifies the offset of the next block of data to receive.
  • (Integer) watched_time — Total time (in seconds) watched.
Example Response
XML JSON

<response>
  <code>1</code>
  <message>Successfully completed.</message>
</response>

Url:

  • [GET] /api/v2/media/:id/ping.[xml|json]

Update the watched_time attribute.

Note:
This will return only success or failure, no content.
Note:
Recommended frequency: Every five to fifteen minutes.
Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (Integer) watched_time
    Total time (in seconds) watched.
Example Request

The following URL marks a watch heartbeat point for media with ID == 1
[GET] https://service_name.synctv.com/api/v2/media/1/ping.xml?watched_time=4435&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <code>1</code>
  <message>Successfully completed.</message>
</response>

Url:

  • [GET] /api/v2/media/:id/stop.[xml|json]

Declare the point (in seconds) at which the user stopped watching the specified media.

Note:
This will return only success or failure, no content.
Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (Integer) watched_time
    Total time (in seconds) watched.
Example Request

The following URL marks the point at which the user stopped watching media 1.
[GET] https://service_name.synctv.com/api/v2/media/1/stop.xml?watched_time=4435&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <code>1</code>
  <message>Successfully completed.</message>
</response>

Url:

  • [GET] /api/v2/media/views.[xml|json]

DEPRECATED: This API is deprecated and may be removed from future releases, use the Activities API instead.

List of all views.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
Example Request

The following example returns a list of views for for the current account
[GET] https://service_name.synctv.com/api/v2/media/views.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Integer) media_id — Filters response to include only views of the specified media (e.g. media_id=1).
Example Response
XML JSON

<response>
  <views>
    <view>
      <id>1</id>
      <account_id>1</account_id>
      <account_profile_id nil="true"/>
      <media_id>1</media_id>
      <client_id>1</client_id>
      <watched_time>1000</watched_time>
      <type>Account::Activity::MediaView</type>
      <created_at>2014-05-01T21:24:37Z</created_at>
    </view>
    <view>
      <id>2</id>
      <account_id>2</account_id>
      <account_profile_id nil="true"/>
      <media_id>2</media_id>
      <client_id>2</client_id>
      <watched_time>2000</watched_time>
      <type>Account::Activity::MediaView</type>
      <created_at>2014-05-01T21:24:37Z</created_at>
    </view>
  </views>
</response>