API Documentation

Contact

If you have any questions, encounter bugs, or just want to say hello, send us an email at dev@spotwatch.io.

Contents

Schema

Time Formats

Pagination

API Key

Ads

Broadcasts

Broadcast Blocks

Batch Requests

Masked Requests

Push Messages

Misc Request

Object Fields

Schema

The Spotwatch API is accessible via HTTPS through api.spotwatch.io. You can pass arguments either as query strings or as JSON content with the content type application/json. Successful requests return 200 OK, while failed requests return either 400 Bad Request or 403 Forbidden with an error message in text/plain.

Most requests require a valid API key. The API key can be provided either as a parameter or as a header field Authorization with the type key.

Using API key as a query parameter

    
        $ curl -i 'https://api.spotwatch.io/get-ad
        ?ad_fields=categories
        ' -H '
        Authorization: key
         your-key'
    

Using API key in a JSON body

    
        $ curl -i 'https://api.spotwatch.io/get-ad
        ' -d '
        {"key":"your-key"
        ,"ad_fields":["categories"]}'
    

Error response example

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Argument(s) missing. Expected [key, id], got [key, ad_fields], missing [id].

Success response example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "categories" : [ "telecommunication", "electronics", "mobile" ]
}

Time Formats

By default, timestamps are provided in ISO 8601 format in UTC. You can specify the desired time format for timestamps in your requests using the time_fmt parameter.

Accepted values for time_fmt are:

Plain Format

The plain format returns a timestamp adjusted to the timezone set for your API key. By default, the timezone is Europe/Berlin.

Set your timezone with

/set-timezone-for-api-key

Arguments

Example

    
        /set-timezone-for-api-key
        ?key=your-key
        &tz=Europe/London
    

Default timezone set to [Europe/London].

Date Arguments

Requests with date arguments, usually indicated with a *_to / *_from postfix, accept either ISO 8601, unix or a short day format YYYY-MM-DD.

Example

    
        /get-ads
        ?key=your-key
        &lastseen_from=2022-06-30
        &lastseen_to=1656592050
    

Pagination

Requests potentially returning huge datasets accept an optional page_lim argument:

and return an additional page object with fields:

Example

    
        /get-broadcasts
        ?key=your-key
        &time_fmt=unix
        &page_lim=1000
    

Returns

{
    "page": {
        "index": 0,
        "prev": null,
        "next": "/hl0fserktnimhbcnfcmq",
        "results_total": 424588,
        "pages_total": 425
    },
    "results": [
        ...
    ]
}

The prev and next fields are links to the next / previous pages.

    
        api.spotwatch.io/hl0fserktnimhbcnfcmq
    
      
     
    
        retuns the next page
    

API Key

Get your key with

/get-api-key

Arguments

Returns

Your API key as text/plain.

Example

    
        /get-api-key
        ?email=you@email.com
        &pw=your-password
    

    
        $ curl https://api.spotwatch.io/get-api-key
         -d '
        {"email":"you@email.com"
        ,"pw":"your-password"}'
    

Response

z8ragt1hfjsakilrfc4ehr3plfdt89b0

Ads

Get a single ad with

/get-ad

Arguments

Returns

The ad with given ID as application/json.

Example

    
        /get-ad
        ?key=your-key
        &id=3893859079416045
    

{
    "id": 3893859079416045,
    "created": "2022-03-31T06:07:07Z",
    "lastseen": "2022-06-12T22:26:26Z",
    "duration": 20,
    "brand": "vodafone",
    "description": "allnet flat",
    "categories": [ "telecommunication" ],
    "nbroadcasts": 1,
    "broadcasts": [
        {
            "id": 39840,
            "time": "2022-06-11T18:08:46Z",
            "region": "de",
            "channel": "vox",
            "ad": 3893859079416045,
            "block": 1259,
            "blockindex": 3
        }
    ],
    "related": [ 2798804439039186 ],
    "media": {
        "video": {
            "mp4": "/klwc7ilp41lgb8kiopye"
        },
        "image": {
            "preview": "/9dgnbp81g6jndapeazyy",
            "grid": "/pjbphmperbfaopf4qx8s"
        }
    }
}

Get multiple ads with

/get-ads

Arguments

Returns

Page and array containing matched ads as application/json.

Example

    
        /get-ads
        ?key=your-key
        &category=telecommunication
        &ad_fields=id,lastseen,media
        &time_fmt=unix
    

{
    "page": { ... }
    "results": [
        {
            "id": 6353806529225371,
            "lastseen": 1656592050,
            "media": {
                "video": {
                    "mp4": "/klwc7ilp41lgb8kiopye"
                },
                "image": {
                    "preview": "/azfe4d2qwcmk0shik1gw",
                    "grid": "/pjbphmperbfaopf4qx8s"
                }
            }
        },
        ...
    ]
}

Broadcasts

Get a single broadcast with

/get-broadcast

Arguments

Returns

The broadcast with given ID as application/json.

Example

    
        /get-broadcast
        ?key=your-key
        &id=39840
    

{
    "id": 39840,
    "time": "2022-06-11T18:08:46Z",
    "region": "de",
    "channel": "vox",
    "ad": 3893859079416045,
    "block": 1259,
    "blockindex": 3,
    "program": "gute zeiten, schlechte zeiten",
    "genre": "serien",
    "subgenre": "daily soap"
}

Get multiple broadcasts with

/get-broadcasts

Arguments

Returns

Page and array containing matched broadcasts as application/json.

Example

    
        /get-broadcasts
        ?key=your-key
        &channel=rtl,dmax
        &ad_brand=sony
        &time_from=2022-06-09
        &time_fmt=plain
        &broadcast_fields=ad,time,region,channel
    

{
    "page": { ... },
    "results": [
        {
            "ad": 2371504209363725,
            "time": "2022-05-06 18:40:10",
            "region": "de",
            "channel": "dmax",
        },
        ...
    ]
}

Get all broadcasts for an ad with

/get-broadcasts-for-ad

Arguments

Returns

An array containing all broadcast objects for given ad as

• application/json on fmt=json
• text/csv on fmt=csv

Example

    
        /get-broadcasts-for-ad
        ?key=your-key
        &ad=2798804439039186
        &fmt=csv
        &csv_delimiter=;
    

"id";"time";"region";"channel";"ad";"block";"blockindex"
"47501";"2022-06-09 01:00:00";"de";"rtl";"3392276504707697";"5922";"0"
...

Broadcast blocks

Get a single broadcast block with

/get-block

Arguments

Returns

The block with given ID as application/json.

Example

    
        /get-block
        ?key=your-key
        &id=1259
        &ad_fields=id,duration
    

{
    "id": 1259,
    "region": "de",
    "channel": "rtl",
    "start": "2022-06-09T01:00:00Z",
    "finish": "2022-06-09T01:01:31Z",
    "program": "two and a half men",
    "genre": "serien",
    "subgenre": "comedyserie",
    "ads": [
        {
            "id": 3392276504707697,
            "duration": 20
        },
        ...
    ]
}

Get multiple broadcast blocks with

/get-blocks

Arguments

Returns

Page and array containing matched block objects as application/json.

Example

    
        /get-blocks
        ?key=your-key
        &start_from=2022-06-11
    

{
    "page": { ... }
    "results": [
        {
            "id" : 661,
            "region": "de",
            "channel" : "sat1",
            "start" : "2022-06-11T01:00:00Z",
            "finish" : "2022-06-11T01:01:31Z",
            "program": "navy cis",
            "genre": "serien",
            "subgenre": "krimiserie"
            "ads" : [
                {
                    "id" : 767171625096234
                },
                ...
            ]
        }
    ]
}

Batch Requests

Make multiple API requests in one go with

/batch

Arguments

Returns

A map (mapkey -> result) of json objects with form:

{
    "code": "", "reply": ""
}

Example

$ curl https://api.spotwatch.io/batch -H 'Authorization: key your-key' -d '{
    "requests": [
        {
            "mapkey": "first",
            "path": "/get-block",
            "args": { "id": 810, "ad_fields": ["id", "brand"] }
        },
        {
            "mapkey": "second",
            "path": "/get-block",
            "args": { "id": 14426, "ad_fields": ["id", "brand"] }
        }
    ]
}'

Result

{
    "first": {
        "code": 200,
        "reply": {
            "id": 810,
            "region": "de",
            "channel": "viva",
            "start": "2022-06-25T07:45:38Z",
            "finish": "2022-06-25T07:46:18Z",
            "ads": [
                { "id": 504038989557373, "brand": "goodgame.de" },
                { "id": 3996816512810860, "brand": "wimdu.de" }
            ]
        }
    },
    "second": {
        "code": 400,
        "reply": "Block ID [14426] not found."
    }
}

Masked Requests

To avoid exposing sensible information in urls, mask requests with

/mask

Arguments

Returns

Generated link in text/plain.

Example

$ curl https://api.spotwatch.io/mask -d '{
    "key": "your-key",
    "allow_args": true,
    "path": "/get-ad",
    "args": {
        "ad_fields": ["id", "brand", "description", "media"],
        "time_fmt": "plain"
    }
}'

/t1o0rc7lt1887qjnruje

The generated link can be called with arguments when allow_args is set to true:

    /t1o0rc7lt1887qjnruje
    ?id=8763496104749285

Broadcast Push Messages via Webhooks

Set a webhook for broadcast push messages with

/set-push-broadcast

Arguments

Push messages are sent over HTTP/HTTPS using the POST method with a Content-Type of application/json. To verify a given endpoint, the server will send a ping message:

{ "ping": "random-string" }

The server expects the random string to be sent back as text/plain.

When setting an endpoint, you can pass an optional argument called token. This token can be any string of your choosing and will be included with every push message sent to the endpoint. You can use this token on your end to verify that the request comes from an authorized source.

Please note that only one endpoint can be set at any given time. Setting a new endpoint will overwrite the previous one.

Setting an Endpoint

To set an endpoint, use the following API call:

    /set-push-broadcast
    ?key=your-key
    &url=https://your-domain.net/your-webhook-endpoint
    &token=your-chosen-token

Deleting an Endpoint

To delete an endpoint, use the following API call:

    /delete-push-broadcast
    ?key=your-key

Example Implementation

The following is an exemplary implementation of setting up a webhook and receiving messages:

express = require("express")
axios = require("axios")
crypto = require("crypto")
bodyParser = require("body-parser")

spotwatchApiKey = "your-api-key"
webhookUrl = "https://your-domain.net/spotwatch-webhook"

randomToken = crypto.randomBytes(32).toString("hex")

setupBroadcastWebhook = () ->
    apiRequestUrl = "https://api.spotwatch.io/set-push-broadcast"
    # Pass your webhook URL along with the generated token
    requestBody =
        key: spotwatchApiKey
        url: webhookUrl
        token: randomToken
    try
        await axios.post(apiRequestUrl, requestBody)
        console.log("Webhook set up successfully.")
    catch error
        console.log("Failed to set up webhook => #{error.response?.data}")

handleBroadcastMessage = (message) ->
    # Process and handle the broadcast message
    console.log(message)

app = express()
app.use(bodyParser.json())

# The endpoint which will be called to deliver broadcast messages
app.post "/spotwatch-webhook", (request, response) ->
    body = request.body
    token = body?.token
    # This token should match your generated token
    if token isnt randomToken
        # Unauthorized access
        response.status(403).end()
    else if body.ping?
        # Respond with the incoming ping in clear text
        response.end(body.ping)
    else
        response.end()
        # Handle incoming broadcast message
        handleBroadcastMessage(body.message)

app.listen process.env.PORT, () ->
    # Set up the webhook once the server is running
    setupBroadcastWebhook()

Example Broadcast Push Message

{
    "token": "your-chosen-token",
    "push_type": "broadcast",
    "message": {
        "broadcast": {
            "id": 895797,
            "time": "2022-09-13T13:01:28Z",
            "region": "de",
            "channel": "sport1",
            "ad": 1843718744355554,
            "block": 110529,
            "blockindex": 0,
            "program": "american chopper"
            "genre": "report",
            "subgenre": "dokumentation"
        },
        "timings": {
            "start": "2022-09-13T13:01:28Z",
            "end": "2022-09-13T13:01:48Z",
            "detected": "2022-09-13T13:01:30Z"
        },
        "ad": {
            "id": 1843718744355554,
            "brand": "alfa romeo",
            ...
        }
    }
}

Broadcast Push Messages via Message Queue

You can also set up an internal message queue for broadcast messages. This can be accomplished by passing the special /message-queue URL parameter to /set-push-broadcast as shown below:

    /set-push-broadcast
    ?key=your-key
    &url=/message-queue

If /message-queue is used as the endpoint, new broadcast messages will be queued in an internal queue. The maximum number of queued messages is 1000. If the messages in the queue exceed this maximum number, old messages will be replaced by new ones.

Accessing Your Message Queue

To access your message queue, call:

/get-message-queue

Arguments

Returns

An array containing up to num_messages or all messages, sorted from oldest to newest, in application/json format.

All returned messages are considered delivered and will be removed from the internal queue.

Examples

Fetch all queued messages

    /get-message-queue
    ?key=your-key

Fetch up to 100 queued messages

    /get-message-queue
    ?key=your-key
    &num_messages=100

Sample Response

{
    "messages": [
        {
            "push_type": "broadcast"
            "message": {
                "broadcast": {
                    "id": 181132408,
                    "time": "2024-07-29T19:31:01Z",
                    "region": "de",
                    "channel": "tlc",
                    "ad": 8693926032257232,
                    "block": 1728925,
                    "blockindex": 13,
                    "program": "Dating ohne Grenzen: In 90 Tagen zum Altar"
                    "genre": "report",
                    "subgenre": "reality-soap"
                },
                "timings": {
                    "start": "2024-07-29T19:31:01Z",
                    "end": "2024-07-29T19:31:11Z",
                    "detected": "2024-07-29T19:31:04Z"
                },
                "ad": {
                    "id": 8693926032257232,
                    "brand": "emma",
                    "created": "2024-07-04T04:43:47Z",
                    "lastseen": "2024-07-29T19:31:01Z",
                    "duration": 10,
                    ...
                }
            }
        },
        ...
    ]
}

Misc Requests

Get all available regions with

/get-all-regions

Arguments

Returns

A list of all available regions as application/json.

Get all channels for which data is available, including historical data

/get-all-channels

Arguments

Returns

A map of all available channels mapped by region as application/json or a list as text/csv.

Get all currently tracked channels with

/get-tracked-channels

Arguments

Returns

A map of all available channels mapped by region as application/json or a list as text/csv.

Get all categories with

/get-all-categories

Arguments

Returns

A list of all categories as application/json.

Get all brands with

/get-all-brands

Arguments

Returns

A list of all brands as application/json.

Get all possible tv genres and subgenres with

/get-all-tv-genres

Arguments

Returns

A map of all possible genres and subgenres mapped by region as application/json.

Object Fields

Ad

Ad Media

Broadcast

Block