The Seevibes Developper API

Introduction

The API allows you to access to Seevibes functionalities related to Twitter in real times

  • Get current EPG
  • Get tweets related to a program
  • Get hashtags and user related to a program

The API use JSON as a format to display the output JSONP is supported (use callback=<yourcallback> on all the services)

PUSH: A push version is available for some of the services , contact us to know more

Get An API KEY

You must register and get an API KEY To get the API KEY:

you will see your API KEY

send an email to info@seevibes.com in case of problem

All request must be sent to api.tvtweet.fr end point

example: http://api.tvtweet.fr/countries/France/trends.json?api_key=<YOUR API KEY>

/countries/<country>/channels/programs.json

Will return the program (EPG) of the day in json format The result is an array of json object, each object contain two fields :

  • :channel_name the name of the channel
  • : programs the list of programs for this day in an array form

Each program will contains :

  • The id of the program
  • The title
  • The description

Parameters :

  • <Country> : England,France
  • date : optional parameter for a program in a different date, format date=dd_mm_yyyy

Example :

http://api.tvtweet.fr/countries/England/channels/programs.json ?date=2_1_2012-03-02

result:

[
  {
    "channel_name": "ARTE",
    "programs": [
      {
        "rating": null,
        "category": "Documentaire",
        "title": "L'\u00e9l\u00e9gance selon Crist\u00f3bal Balenciaga",
        "channel_id": "4f1c5efaa6b6a3dde8000001",
        "_id": "4f508487a6b6a30964000048",
        "credits": [
          {
            "name": "Josu Venero",
            "role": "director"
          }
        ],
        "description": "Un portrait du couturier fran\u00e7ais d'origine espagnole Crist\u00f3bal Balenciaga, l'un des plus grands de sa g\u00e9n\u00e9ration : d\u00e9couverte de son art et de sa post\u00e9rit\u00e9. ",
        "endTime": "2012-03-05T01:15:00+01:00",
        "startTime": "2012-03-05T00:15:00+01:00",
        "image": null
      },{
        "rating": 2,
        "category": "Documentaire",
        "title": "Karlheinz Stockhausen",
        "channel_id": "4f1c5efaa6b6a3dde8000001",
        "_id": "4f508487a6b6a30964000049",
 "credits": [
          {
            "name": "Norbert Bus\u00e8",
            "role": "director"
          },
          {
            "name": "Thomas von Steinaecker",
            "role": "director"
          }
        ],
        "description": "Au milieu des ann\u00e9es 50, ….. Portrait d'un artiste visionnaire. ",
        "endTime": "2012-03-05T02:05:00+01:00",
        "startTime": "2012-03-05T01:15:00+01:00",
        "image": null      
      }
   ]
}

The information is repeated for each program of each channel

/programs/<id prog>.json

Return detailled info about a program Contains :

  • title
  • description
  • startTime
  • endTime

Some field are dynamic and updated during the show

  • tweetCount : total number of tweets found on this program
  • tags : the tags found during the program
  • tweets : the list of tweets for this program, only if optionnal parameters « tweets » is set to 1. Note that the prefered method is to use the « tweets.json » method instead of this option

Example :

http://api.tvtweet.fr/programs/4f20978c23ce06571b000035.json

Sample output :

{
  "tags": [
    [
      "dpda",
      3881
    ],
    [
      "fh2012",
      1181
    ],
    [
      "hollande",
      571
    ]
  ],
  "program": {
    "rating": null,
    "title": "Des paroles et des actes",
    "channel_id": "4cebf8b26378a10ff08e722e",
    "_id": "4f20978c23ce06571b000035",
    "negative": 29.0,
    "positive": 332.0,
    "description": "Des paroles et des actes",
    "endTime": "2012-01-26T22:40:00+01:00",
    "startTime": "2012-01-26T20:35:00+01:00",
    "image": null,
    "tweetCount": 4266
  }
}

/programs/<id prog>/tweetsGraph.json

Return the minute by minute numbers of tweet for the specified program Contains :

  • startTime of the graph, in UTC. Usually 30 minutes before the show
  • endTime of the graph, in UTC. Usually 30 minutes after the show
  • title
  • dim : dimention of the graph, default is 1
  • data : an array of the data, minute/minute . The size of the array is endTime-startTime in minutes

Example :

http://analytics.tvtweet.com/programs/5300c49eee758c57e400003a/tweetsGraph.json

Sample output :

{
  "startTime":"2014-02-22 19:25:00 UTC",
  "endTime":"2014-02-22 22:55:00 UTC",
  "title":"The Voice, la plus belle voix",
  "id":"5300c49eee758c57e400003a",
  "annotations":null,
  "dim":1,
  "data":[80,43,42,40,39,50,67,53,62,62,67,79,76,81,62,67,83,80,91,91,81,89,127,174,166,132,146,121,124,117,201,195,189,170,193,190,488,922,1015,1412,1285,1270,1045,875,1017,1107,979,918,1155,1382,1635,1617,2025,1411,1144,2000,1384,1380,1398,1192,1271,1248,1117,1230,1076,1123,1478,1536,1405,1257,1762,1485,1012,949,1234,1014,1017,931,1104,1154,790,707,581,438,456,402,391,554,733,1173,1546,1625,1112,1243,1119,1120,1467,1107,1197,1170,1153,1367,1598,2266,3133,2842,2038,1801,2133,1491,1163,1004,799,643,630,565,689,1608,1354,934,734,699,629,651,610,701,824,983,768,753,1022,857,693,748,720,769,720,736,882,830,772,965,1175,1277,921,959,1062,887,799,704,554,580,648,568,452,466,650,495,444,411,328,293,287,341,347,531,709,734,572,497,491,470,592,449,441,422,299,290,237,275,268,237,228,217,225,181,185,214,210,209,219,181,132,151,139,121,131,138,128,101,94,96,94,94,105,87,90,86,103,90]}

/programs/<id prog>/tweets.json

TweetId from a program,sorted by date, most recent first

Options :

  • nbParPage : number of tweets returner per request, default is 500
  • page : page number
  • from : last tweet id. If present , only tweet more recent than last tweet id are returned. Note that id is internal id (_id field ).

Sample:

http://api.tvtweet.fr/programs/4f20978c23ce06571b000035/tweets.json?page=3&nbParPage=50

fetch tweets between 150 and 200 from the latest one

Sample output :

[
  {
    "_id": "4f29b8c823ce066712005264",
    "tweet": {
			<ID OF THE TWEET>
     }
  },
  {
    "_id": "4f29b8ac23ce06671200524a",
    "tweet": {
 
			<ID OF THE TWEET>
 
    }
  },
  {
    "_id": "4f29b6d923ce06671200501c",
    "tweet": {
			<ID OF THE TWEET>
     }
  }
 <etc….>
]

/programs/<id prog>/mostRetweeted.json

Most tweeted tweets for a program, ordered by number of retweet, most retweeted first

Sample:

http://api.tvtweet.fr/programs/4f20978c23ce06571b000035/mostRetweeted.json

Sample output :

[
"mostRetweeted": [
    {
      <id>
    },
    {
       <Second most retweeded >
    }
  }
]

/programs/<id prog>/hashtags.json

Full list of hashtag FOUND in the program

Sample:

http://api.tvtweet.fr/programs/4f20978c23ce06571b000035/hashtags.json

Sample output :

[ 
  ["thevoice",127880],
  ["tf1",4470],
  ["voicebattles",4081],
  ["maximilien",1858],
  ["battles",1745],
  ["manon",1242],
  ["thevoicefrance",1140],
  ["rt",1034],
  ["battle",1032],
  ["nw",917],
  .....
]

/programs/<id prog>/info.json

Return informations about a program, including official tag

Sample:

http://api.tvtweet.fr/programs/4f20978c23ce06571b000035/info.json

Sample output :

{
   "channel_id":"4d29aeb58dc338b1271784cc",
   "endTime":"2013-05 15T17:15:00Z",
   "officialTag":"#LGJ",
   "peakTime":null,"peakVolume":0,
   "startTime":"2013-05-15T16:55:00Z",
    "title":"Le grand journal",
    "tweetCount":598,
    "tweetsMin":-0.0,
    "usersCount":395
}

Countries

/countries/<country>/trends.json

Provide the current trends in term of program popularity

Parameters :

  • duration (default=600), number of seconds of sampling time

Return a JSON containing the current number of tweets for each channel in the current country, for the last ten minutes. The fields are:

  • Duration : Sample time , 120 seconds default
  • Count : total number of tweets in the last sample time about thèses country channels

Note : count/duration=number of tweets/seconds

  • Trends : a hash containing the number of tweets in the last sample time and the name of the current program for each channel.

For each program, the channel name is returned, the program title and the number of tweet on this program. For program where hit=0, they are not returned

Example :

http://api.tvtweet.fr/countries/France/trends.json

Sample result:

{
  "duration": 600,
  "count": 32,
  "length": 2,
  "trends": {
    "France2": {
      "program": "Toute une histoire",
      "hit": 5
    },
    "TF1": {
      "program": "Les feux de l'amour",
      "hit": 27
    }
  }
}

/countries/<country>/statsfull.json

Weekly stats

Return the program list order by number of tweets for the last seven days for the specified country Options :

  • date : starting date . Default is current day-7 days
  • range: number of days to compute the stats, default is 7
  • agg: perform show aggregation , default is true
  • d : instead of specify a date, d can be used to specify the number of days before the current date. Exemple: d=1 (and range=1) will display yesterday stats

Exemple, to get the yesterday ranking:

http://api.tvtweet.com/countries/France/statsfull.json?d=1&range=1&agg=false&api_key=<your_api_key>

Result:

[
  {
    "_id": "536b8015fc8eb5d7bf00016e",
    "category": "Emission sportive",
    "channel_id": "4d29aec88dc338b1271784cd",
    "channel_name": "W9",
    "cle_genre": "641",
    "customTags": [
 
    ],
    "endTime": "2014-05-14T21:00:00Z",
    "engRate": null,
    "gender": {
      "U": 28342,
      "M": 7839,
      "F": 2445,
      "percent_male": 76.22,
      "percent_female": 23.77
    },
    "image": null,
    "impressions": 43788804,
    "liveCount": 18160,
    "liveUsersCount": 9116,
    "negative": 566.0,
    "officialTag": "#benfc ",
    "peakTime": "2014-05-14T21:29:00Z",
    "peakVolume": 795,
    "pluri_emi_id": "77553647",
    "pluri_id": "101972923",
    "positive": 2404.0,
    "rating": null,
    "reach": 16663650,
    "retweetCount": 17009,
    "sport": {
      "championnat": {
        "annee": "2013/2014",
        "libelle": "Ligue Europa",
        "manche": "Finale"
      },
      "evenement": "Benfica Lisbonne (Por) / FC S\u00e9ville (Esp)"
    },
    "startTime": "2014-05-14T18:35:00Z",
    "tagsCount": 1382,
    "title": "Football: Benfica Lisbonne (Por) / FC S\u00e9ville (Esp)",
    "tweetCount": 38853,
    "tweetsMin": 125.24137931034483,
    "usersCount": 17575
  },{
  // second program of day....
  },
] 

/countries/<country>/now.json

return in a summy form what is currently playing now for the selected country

the return is a json containing a “program” hash, the key being the channel name, and the content another hash with the following fields:

  • hit : number of tweets in the past duration period
  • channel_tag : the “official” tag for this channel
  • program: an object describing the current program for this channel

with the following field:

  • id: program id
  • title: program title
  • description: description of the program
  • startTime
  • endTime
  • official_tag : official tag of the program. Can be empty
  • proposed_tag : an alternate, automatically generated tag that could be used

Additionnal parameters:

  • duration : sample of duration to compute tweet hits. Default is 120

Example

http://api.tvtweet.fr/countries/France/now.json?api_key=<your api key>

And a sample answer:

{
{
  "duration": 120,
  "count": 11,
  "currentPrograms": [
    {
      "channel_name": "ARTE",
      "programs": [
        {
          "proposedTag": "",
          "starTime": "2012-04-06T10:30:00+02:00",
          "title": "360\u00b0-GEO",
          "id": "4f74e9a2636b35326e00000e",
          "description": "La plus petite des trois \u00eeles Anglo-Normandes, accessible uniquement par ferry, a abrit\u00e9 la derni\u00e8re soci\u00e9t\u00e9 f\u00e9odale d'Europe jusqu'\u00e0 l'introduction de la d\u00e9mocratie en 2008. ",
          "endTime": "2012-04-06T11:15:00+02:00",
          "officalTag": ""
        }
      ],
      "hit": 0,
      "channel_tag": "#arte"
    },
    {
       <other prog...>
 
    }
  ]
}

Channels

/channels/<channel id>/tweets.json

Use this to retreive current tweets associated with a channel. See “programs/<id>/tweets.json for a compltete description

Parameters

  • from: the latest id

/channels/<channel id>/tweetsGraph.json

Provide a minute by minute graph of the Twitter activity on this channel, for the specified period

Parameters

  • startDate: date and time to start the result , in the format DD_MM_YYY_HH_MM , exemple 21_4_2013_12_35 for 21/4/2013 12:35
  • endDate : date and time for the end

It is recommended to keep startDate and endDate in the same day

The output is an object with a “tweets” attribute, an array with an entry per minute where the value is the number of tweets in this minute. Exemple: <pre>

{"channel":"4cebfa416378a10ff08e7232",
"startTime":"2013-04-23T03:00:00+02:00",
"endTime"  :"2013-04-23T03:06:00+02:00",
"tweets": [5,6,10,2,110,12]}

</pres>

for the 6 minute periode, you have the 6 values for each minute of the number of tweets/minute

Users

User related fonction are mainly for “tagging” user . You can be notified of events generated by tagged user, using the Push API. You must have sepcial privileges to access to this part of the API.

/user/<id>/addAndTag.json

TBD

/user/<id>/updateTagList.json

TBD

/user/<id>/removeTag.json

TBD


Page Tools