Seevibes API Endpoint Documentation

/api/v1/metrics/:market_code/:start_on[/:interval]

This endpoint returns all account accessible values in one API call.

URL Parameters

:market_code

Identifies which market you want values of. Valid values are simple text strings: usa, canada, quebec.

:start_on

Selects the date for which you want values of. Data about your account is kept for at least one year. You may query any date accessible to you at any time. Dates must be formatted as ISO-8601 dates, such as 2012-04-13.

Weekly reports start on Sunday. Querying for another day will return an error.

Query Parameters

No query parameters are available.

HTTP Response Codes

The API responds with Content-Type set to application/json. The API responds with a top-level JSON object of the following format:

{
    "interval": "1 day", 
    "market_code": "usa", 
    "market_name": "USA", 
    "start_at": "2013-05-02 07:00:00 +0000",
    "end_at": "2013-05-03 07:00:00 +0000",
    "movie": [
        {
            "category": "movie", 
            "female_negative_count": 0,
            "female_negative_pct": 0.0, 
            "female_count": 5,
            "female_pct": 1.0, 
            "female_positive_count": 0,
            "female_positive_pct": 0.0, 
            "geo": [
                [
                    "unknown", 
                    5,
                    1.0
                ]
            ],
            "interactions_count": 5, 
            "male_negative_count": 0,
            "male_negative_pct": 0.0, 
            "male_count": 0,
            "male_pct": 0.0, 
            "male_positive_count": 0,
            "male_positive_pct": 0.0, 
            "name": "10000 BC", 
            "negative_count": 0,
            "negative_pct": 0.0, 
            "positive_count": 0,
            "positive_pct": 0.0
        }, 
    ], 
    "tv": [
        {
            "category": "tv", 
            "female_negative_pct": 0.0, 
            "female_pct": 0.0, 
            "female_positive_pct": 0.0, 
            "geo": [
                [
                    "united states, texas, waco",
                    1.0
                ]
            ],
            "interactions_count": 0, 
            "male_negative_pct": 0.0, 
            "male_pct": 0.0, 
            "male_positive_pct": 0.0, 
            "name": "Angel", 
            "negative_pct": 0.0, 
            "positive_pct": 0.0
        }, 
    ]
}

interval

The report's interval - it's length. Valid values are 1d for 1 day (24 hours), 1w for weekly (7 days) and 1m for monthly (from the 1st to the next 1st, excluded).

market_code

The report's market. Simple text string like usa or canada.

market_name

The report's market, in human viewable form. Longer text strings, with proper capitalization, such as USA or Canada National.

start_at/end_at

The instants for which this report includes interactions. The instants are in UTC. These values become more important when DST transitions occur.

movie/tv/actors

Arrays of objects representing the actual values for the named shows, movies and actors. Keys with a suffix of _pct are percentages, where 1.0 is 100%. Keys with a suffix of _count are integer counts. The geo key is an array of arrays where the first element is the geo location, and the 2nd is the percentage of interactions in that location.

/api/v1/market/:market?start_on=:start_on[&interval=:interval]

This endpoint return a json object containing every show related to the requested market

URL Parameters

:market

Identifies which market you want values of. Valid values are simple text strings: usa, canada, quebec, france.

Query Parameters

:start_on

Selects the date for which you want values of. Data about your account is kept for at least one year. You may query any date accessible to you at any time. Dates must be formatted as ISO-8601 dates, such as 2012-04-13. This param is mandatory. Note that if the selected date is not a sunday, the system automatically change the date to the previous sunday. Also note that the Market Insight values are recalculated weekly.

Response Body

The API responds with Content-Type set to application/json. The JSON object returned will contain multiple shows object, one for each show related to the market you requested. Here is an example of those object :

{
      "id": "7168f586-daec-11e0-9b8e-40402761cfca",
      "show_name": "La victoire de l'amour",
      "channel_ids": [
        "71bf4666-daec-11e0-9b8e-40402761cfca"
      ],
      "channel_names": [
        "TVA"
      ],
      "market_id": "d4c13fb0-db2c-012e-ebb6-40400fe46aa7",
      "category_ids": [
        "a00624d4-0497-49c4-b070-1d25c7d2ade1"
      ],
      "seevibes_score": 84.2691230118197,
      "interactions": 263179,
      "twitter_interactions": 0,
      "facebook_interactions": 263179,
      "twitter_pct": 0.0,
      "facebook_pct": 100.0,
      "participants": 70251,
      "twitter_participants": 0,
      "facebook_participants": 70251,
      "impressions": 58707380,
      "twitter_impressions": 0,
      "facebook_impressions": 58707380,
      "male_pct": 22.2775655785865,
      "female_pct": 77.7224344214135,
      "frequency": 3.76315793551954,
      "facebook_frequency": 3.76315793551954,
      "twitter_frequency": 0.0,
      "airs_daily": true,
      "feedback": 0.0,
      "facebook_engagement": 0.0,
      "twitter_engagement": 0.0,
      "engagement": 0.0
}

Authentication

Authentication is done through Basic authentication. Use your Seevibes API Token as the Basic username, and no password. For example, if your authentication token was c2VldmliZXMtdG9rZW46, you would encode your authentication credentials in an Authorization header like this:

Authorization: Basic c2VldmliZXMtdG9rZW46

HTTP Response Codes

The API returns the following HTTP response codes:

200 OK

Request succeeded. The HTTP body contains the values.

400 Bad Request

The submitted request was incorrect. The HTTP body will explain the exact reason, but the most likely errors are incorrect market or a date to which you do not have access.

401 Unauthorized

The Authorization header was absent from the HTTP Request, or the credentials were incorrect, or the credentials expired.

50x Internal Server Error

An error occured server-side, or we were upgrading. Retry your requests every minute until it succeeds.


Page Tools