Statistics server address: https://stats.terratraf.com/api/

Specification

The service is accessed using the JSON-RPC 2.0 protocol. More information about protocol specification you can find in official sources.

While requests to API, you must pass the method from the request body in GET parameters, e.g.:

curl -X POST -d '{
  "jsonrpc": "2.0", 
  "method":"namespace.method", 
  "params": {
    "param1": "value1", 
    "param2": "value2"
  }, 
  "id": 1
}' https://localhost/?namespace.method

How to get statistics for a source

To get statistics, you need to call "stat.getForSource" method.

Request params

Name	Description	Type
token	Source token	string
filter	Filter	object

Source token

The list with available tokens can be found on the Source access page. If you don’t have access to this section, please contact Admin.

There is a special access token for each source. If you don’t set “source” filter in your request, you will get stats on the source to which the token belongs that is specified in the params.

If you’d like to get stats on all sources at once, you can use any available token, but additionally you need to set filter "source": ["all"].

Filter object parameters

The table below describes all possible filters, but please note that depending on user rights some filters, groups or dimensions can be not available.

Name	Description	Type
date_from	Start date. Format: Year-month-day. (Required field)	date
date_to	End date. Format: Year-month-day. (Required field)	date
timezone	Time shift. Possible values: Etc/GMT+0 Etc/GMT-1 Etc/GMT+3	string
main_group	Values groups - "date_day" - by day, - "date_hour" - by hour, - "date_week" - by week, - "date_month" - by month, - "partner" - by partner, - "camp" - by camp, - "creative" - by creative, - "source" - by source, - "country" - by country, - "format" - by format, - "os" - by OS, - "browser" - by browser, - "network" - by network.	array of string
side_group	Data grouped: - "source" - by sources, - "source_geo" - sources + geo, - "source_format" - sources + format, - "source_placement" - sources + placement, - "source_os" - sources + OS, - "source_browser" - sources + browser.	array of string
format	The creative format can be set only for data grouped by source + format. Possible values: "v", "t", and "b", which means video, teaser and banner respectively.	string
source	List of sources	array of string
country	List of countries. To display all countries, please specify the value ["all"]	array of string
placement	List of placements	array of string
os	List of OS. To display all OS, please specify the value ["all"]	array of string
browser	List of browsers. To display all browsers, please specify the value ["all"]	array of string
network	List of networks. To display all browsers, please specify the value ["all"]	array of string

Response params

The response will return an array of objects. Objects can have the following fields:

"source" - source name,
"creative" - unique creative ID,
"bid" - response ID,
"shows" - number of impressions,
"win_rate" - win rate, i.e. percentage of the number of impressions won to the number of all impressions,
"clicks" - number of clicks,
"avg_cpm" - average CPM value,
"request" - number of requests,
"date_day" - day, for data grouped by days,
"date_hour" - hour, for data grouped by hours,
"date_week" - week, for data grouped by weeks,
"date_month" - month, for data grouped by months,
"fill_rate" - fill rate, i.e. percentage of the number of impressions completed to the number of requests,
"format" - the type of creatives: banner, video, teaser, e.g., "b728x90" is a banner of size 728x90px,
"placement" - placement ID,
"os" - OS name,
"browser" - browser name,
"network" - network name.

🚧
Please note
The fields in the response are customized for users and depend on the filters set in the request.

Example of using the method:

// Request
curl -X POST -d '{
    "jsonrpc": "2.0", 
    "method":"stat.getForSource", 
    "params":{
        "token": "FNhw...KZc",
        "filter": {
            "date_from":"2023-08-01",
            "date_to":"2023-08-11",
            "timezone":"Etc/GMT+3",
            "main_group": ["network","source","placement"],
            "side_group": ["source_placement"],
            "network": ["demosite.ru"]
        }
    }, 
    "id": 1
}' "http://localhost/?stat.getForSource"

// Response
{
    "jsonrpc": "2.0",
    "result": [
        {
            "source": "name",
            "placement": 111111,
            "network": "demosite.ru",
            "bid": 591397,
            "shows": 14716,
            "win_rate": 2.49,
            "clicks": 3,
            "avg_cpm": 30.48
        },
        {
            "source": "name",
            "placement": 111112,
            "network": "demosite.ru",
            "bid": 252685,
            "shows": 14598,
            "win_rate": 5.78,
            "clicks": 50,
            "avg_cpm": 31.88
        }
    ],
    "id": 1
}

Since "main_group": ["network","source","placement"] was specified in the example, the result is grouped by network, source and platform. If "main_group" won't contain "placement", this column will be absent in the response despite "side_group": ["source_placement"].

Example of using the method displaying the creative format

Statistics on creative formats you can get only grouped by day and in GMT+3.

// Request
curl -X POST -d '{
    "jsonrpc": "2.0", 
    "method":"stat.getForSource", 
    "params":{
        "token": "EJa...kDy",
        "filter": {
            "date_from":"2023-01-01",
            "date_to":"2023-07-31",
            "timezone":"Etc/GMT+0",
            "main_group": ["format"],
            "side_group": ["source_format"],
            "source": ["all"],
            "format": "b"
        }
    }, 
    "id": 1
}' "http://localhost/?stat.getForSource"

// Response
{
    "jsonrpc": "2.0",
    "result": [
        {
            "format": "b300x250",
            "bid": "0",
            "shows": 1739412,
            "win_rate": 0,
            "clicks": 1341,
            "avg_cpm": 27.28
        },
        {
            "format": "b300x600",
            "bid": "0",
            "shows": 348468,
            "win_rate": 0,
            "clicks": 267,
            "avg_cpm": 24.52
        },
        {
            "format": "b240x400",
            "bid": "0",
            "shows": 336885,
            "win_rate": 0,
            "clicks": 94,
            "avg_cpm": 23.12
        },
        {
            "format": "b970x250",
            "bid": "0",
            "shows": 162341,
            "win_rate": 0,
            "clicks": 133,
            "avg_cpm": 21.24
        },
        {
            "format": "b160x600",
            "bid": "0",
            "shows": 59196,
            "win_rate": 0,
            "clicks": 38,
            "avg_cpm": 25.41
        },
        {
            "format": "b728x90",
            "bid": "0",
            "shows": 15539,
            "win_rate": 0,
            "clicks": 7,
            "avg_cpm": 25.11
        }
    ],
    "id": 1
}

Possible errors

Error code	Description	Comments
-32768 по -32099	JSON-RPC 2.0 errors	Learn more in protocol specification.
0	undefined internal error.
1	undefined internal error.
300	account not found	Account was not found
600	source token not found or not available	Source token was not found or not available
601	invalid timezone	Wrong time shift was specified
602	invalid date_from	Wrong start date was specified
603	invalid date_to	Wrong end date was specified

How to get API request statistics

Specification

How to get statistics for a source

Request params

Source token

Filter object parameters

Response params

🚧
Please note

Example of using the method:

Example of using the method displaying the creative format

Possible errors

Specification

How to get statistics for a source

Request params

Source token

Filter object parameters

Response params

🚧Please note

Example of using the method:

Example of using the method displaying the creative format

Possible errors

🚧
Please note