API Documentation

Contact

If you have questions, found a bug or just want to say hi, feel free to drop us a mail dev@spotwatch.io.

Contents

Schema

Time Formats

Pagination

API Key

Ads

Broadcasts

Broadcast Blocks

Batch Requests

Masked Requests

API Pushes

Misc Request

Object Fields

Schema

API access is over HTTPS and accessed from api.spotwatch.io. Arguments are passed either as query strings or as content type application/json. Requests always return either 200 OK on success or 400 Bad Request / 403 Forbidden on failure with an error message as text/plain. Most requests require a valid API key as argument. Either pass your key as parameter or as header field Authorization type key in your request.

For instance:

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

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

Reply on failure:

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

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

Reply on success:

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

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

Time Formats

As default all timestamps are returned in ISO 8601 format at UTC, but all requests returning timestamp fields accept an optional argument time_fmt specifying which format to be used.

Accepted values for time_fmt are:

Plain Format

The plain format returns a timestamp at the timezone set for your key. Per 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

API Pushes

Push messages are sent over HTTP/HTTPS POST with content type application/json. To verify a given endpoint, the server will first POST a ping message { "ping": "random-string" } and expect the random string to be sent back as text/plain. You can pass an optional argument token when setting an endpoint. The value of token will be sent with every push message. Only one endpoint per push type is allowed, setting a new endpoint will overwrite the previous one.

For instance, setting an endpoint:

    /set-push-*
    ?key=your-key
    &url=https://domain.net/push-sink
    &token=secret-token

deleting an endpoint:

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

The logic behind /push-sink could look like this:

app.use bodyParser.json()

app.post '/push-sink', (request, response) ->
    body = request.body
    if not (body?.token is 'secret-token')
        # not authorized
        response.end()

    else if body.ping?
        # reply ping
        response.end body.ping
    else
        # handle message
        handlePush body.push_type, body.message
        response.end()

Up to 1.000 push messages will be cached if a given endpoint becomes unavailable. After exceeding the limit, messages will be replaced by FIFO principle. You can access your message cache with

/get-push-cache

Arguments

Returns

Flush link and array containing messages from index 0 up to num_messages - 1 sorted from oldest to newest as application/json.

Example

    /get-push-cache
    ?key=your-key
    &num_messages=100

{
    "flush": "/s55350wz7zuh4722iyia",
    "messages": [
        {
            "push_type": "broadcast"
            "message": { ... }
        },
        ...
    ]
}

Unless auto_flush is set to true, accessing the cache will not flush returned messages. To flush all messages from index 0 up to num_messages - 1, call the flush link:

    /s55350wz7zuh4722iyia

Using your push cache as a message queue

If /push-cache is given as url parameter when setting a push endpoint, messages will not be sent to a remote endpoint but put in your cache instead.

For instance:

    /set-push-*
    ?key=your-key
    &url=/push-cache

Push Types

Set an endpoint for broadcast pushes with

/set-push-broadcast

Arguments

Example

    /set-push-broadcast
    ?key=your-key
    &url=/push-cache
    &ad_fields=brand

Push Message

{
    "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": {
            "brand": "alfa romeo"
        }
    }
}

Misc Requests

Get all available regions with

/get-all-regions

Arguments

Returns

A list of all available regions as application/json.

Get all available channels with

/get-all-channels

Arguments

Returns

A map of all available channels mapped by region as application/json.

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