alt text

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:

value formatting output example
iso8601 YYYY-MM-DDTHH:MM:SSZ 2022-03-31T06:07:07Z *default
unix integer 1678454850
plain YYYY-MM-DD HH:MM:SS 2022-03-31 08:07:07
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

required

key string your API key
tz string the timezone to set

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:

 
page_lim integer sets the limit for results per page
no limit / all on one page when -1
default 200

and return an additional page object with fields:

 
index integer current page index
zero based
prev string link to the previous page
null if first page
next string link to the next page
null if last page
results_total integer total number of results
(all pages combined)
pages_total integer total number of pages

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

required

email string your email
pw string your password

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

required

key string your API key
id integer the ad ID
optional

ad_fields string(s)
comma-separated or json array
fields the ad object shall contain
default all
broadcast_fields string(s)
comma-separated or json array
fields the nested broadcast objects shall contain
default all except program genre subgenre ad
time_fmt time format

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 ]
}

Get multiple ads with

/get-ads

Arguments

required

key string your API key
optional

ids integers(s)
comma-separated or json array
filter by Ad-ID(s)
category string(s)
comma-separated or json array
filter by categories
product string(s)
comma-separated or json array
filter by product(s)
event string(s)
comma-separated or json array
filter by event(s)
brand string(s)
comma-separated or json array
filter by brand
region string(s)
comma-separated or json array
filter by region
unidentified bool include ads which are not identified
default true
self_promo bool include self promotional ads
default true
created_from date lower limit for creation date
created_to date upper limit for creation date
lastseen_from date lower limit for last seen date
lastseen_to date upper limit for last seen date
time_seen_from date only return ads broadcasted from time_seen_from
time_seen_to date only return ads broadcasted until time_seen_from
duration_from integer lower limit for ad duration
in seconds
duration_to integer upper limit for ad duration
in seconds
ad_fields string(s)
comma-separated or json array
fields the ad objects shall contain
default all
broadcast_fields string(s)
comma-separated or json array
fields the nested broadcast objects shall contain
default all except program ad
keyword string(s)
comma-separated or json array
only return ads which contain one of given keyword(s)
time_fmt time format

Returns

Page and array containing matched ads as application/json.

Example

    
        /get-ads
        ?key=your-key
        &category=telecommunication
        &ad_fields=id,lastseen
        &time_fmt=unix
    
{
    "page": { ... }
    "results": [
        {
            "id": 6353806529225371,
            "lastseen": 1656592050
        },
        ...
    ]
}


Broadcasts


Get a single broadcast with

/get-broadcast

Arguments

required

key string your API key
id integer the broadcast ID
optional

broadcast_fields string(s)
comma-separated or json array
fields the broadcast object shall contain
default all
time_fmt time format

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

required

key string your API key
optional

channel string(s)
comma-separated or json array
filter by channel
region string(s)
comma-separated or json array
filter by region
ad_category string(s)
comma-separated or json array
filter by ad category
ad_brand string(s)
comma-separated or json array
filter by ad brand
time_from date lower limit for broadcast date
time_to date upper limit for broadcast date
ad_id integer(s)
comma-separated or json array
only return broadcasts for given Ad-ID(s)
broadcast_fields string(s)
comma-separated or json array
fields the broadcast objects shall contain
default all
time_fmt time format

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

required

key string your API key
ad integer the ad ID
optional

broadcast_fields string(s)
comma-separated or json array
fields the broadcast objects shall contain
default all
region string(s)
comma-separated or json array
return broadcasts for specific region(s)
default all
fmt string return format, csv or json
default json
csv_delimiter string delimiter for the returned csv
default ,
time_fmt time format

Returns

An array containing all broadcast objects for given ad as

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

required

key string your API key
id integer the block ID
optional

ad_fields string(s)
comma-separated or json array
fields the nested ad objects shall contain
default id only
broadcast_fields string(s)
comma-separated or json array
fields the nested broadcast objects shall contain
default id only
time_fmt time format

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

required

key string your API key
optional

channel string(s)
comma-separated or json array
filter by channel
region string(s)
comma-separated or json array
filter by region
start_from date lower limit for broadcast date
start_to date upper limit for broadcast date
ad_fields string(s)
comma-separated or json array
fields the nested ad objects shall contain
default id only
broadcast_fields string(s)
comma-separated or json array
fields the nested broadcast objects shall contain
default id only
ad_id integer(s)
comma-separated or json array
list only blocks which contain any of the specified ad ID(s)
time_fmt time format

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

required

key string your API key
requests json array json objects with form:
{ "mapkey": "", "path": "", "args": {} }
optional

concurrent bool allows concurrent processing of multiple requests
default false

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

required

key string your API key
path string request path
args json request arguments
optional

ttl integer time to live for returned link, in seconds
no limit when -1
default 7200 (2 hours)
ctl integer calls to live for returned link
no limit when -1
default -1
allow_args bool allows late binding for arguments
default false

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", ],
        "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

required

key string your API key
optional

auto_flush bool when set to true, no flush link will be generated
and returned messages will be flushed automatically
default false
num_messages integer max number of messages to return
all when -1
default-1

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

required

key string your API key
url string push endpoint
optional

time_fmt time format
ad_fields string(s)
comma-separated or json array
fields the nested ad object shall contain
default: id created lastseen duration nbroadcasts brand description categories related

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

required

key string your API key

Returns

A list of all available regions as application/json.


Get all available channels with

/get-all-channels

Arguments

required

key string your API key

Returns

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


Get all categories with

/get-all-categories

Arguments

required

key string your API key

Returns

A list of all categories as application/json.


Get all brands with

/get-all-brands

Arguments

required

key string your api key
optional

region string(s)
comma-separated or json array
filter by region
channel string(s)
comma-separated or json array
filter by channel
time_seen_from time format return only brands seen from time_seen_from
time_seen_to time format return only brands seen until time_seen_to

Returns

A list of all brands as application/json.


Get all possible tv genres and subgenres with

/get-all-tv-genres

Arguments

required

key string your API key

Returns

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


Object Fields


Field Type Description
id integer ID of ad
created time format time when ad was generated
lastseen time format last time ad was seen
duration integer ad duration in seconds
brand string the advertised brand,
empty string if no brand assigned
description string short description of advertised content,
empty string if no description made
regions array of strings country code(s) of regions this ad is broadcasted in
categories array of strings categories of ad
broadcasts array of broadcasts all broadcasts of ad
nbroadcasts integer number of broadcasts
self_promo bool true or false if this ad is a broadcaster self promotion
url string visible url in ad,
empty string if ad does not contain an url
related array of integers IDs of ads this ad is looking similar to
cross_region_ads map of string => integer ads broadcasted in other regions which look exactly like this ad,
ad IDs mapped by country code
user_data string custom user data

Broadcast

Field Type Description
id integer ID of broadcast
time time format start time of broadcast
ad integer ID of broadcasted ad
region string region code of broadcast region
channel string name of broadcast channel
block integer ID of broadcast block
blockindex integer position of broadcast in broadcast block starting at 0
block_length integer total number of broadcasts in broadcast block
pic_in_pic bool true or false if broadcast is special picture in picture format
ad_brand string brand of broadcasted ad
ad_categories array of strings categories of broadcasted ad
ad_description string description of broadcasted ad
ad_duration integer duration of broadcasted ad
ad_nbroadcasts integer total number of broadcasts of broadcasted ad
program string name of TV-program during broadcast,
empty string if no program data available
genre string genre of TV-program,
empty string if no program data available
subgenre string subgenre of TV-program,
empty string if no program data available
prev_program string name of TV-program from previous block
prev_genre string genre of TV-program from previous block
prev_subgenre string subgenre of TV-program from previous block
next_program string name of TV-program from next block
next_genre string genre of TV-program from next block
next_subgenre string subgenre of TV-program from next block

Block

Field Type Description
id integer ID of block
start time format start time of broadcast block
finish time format end time of broadcast block
region string region code of broadcast region
channel string name of broadcast channel
ads array of ads ads in this broadcast block, same order as they were broadcasted
program string name of TV-program during broadcast,
empty string if no program data available
genre string genre of TV-program
empty string if no program data available
subgenre string subgenre of TV-program
empty string if no program data available
prev_program string name of TV-program from previous block
prev_genre string genre of TV-program from previous block
prev_subgenre string subgenre of TV-program from previous block
next_program string name of TV-program from next block
next_genre string genre of TV-program from next block
next_subgenre string subgenre of TV-program from next block