Analytics API

Follow

Our Analytics API is now available for anyone to use

Technical description

The Base URL for the API:  http://api.po.st/analytics/v1/

Query Format:

http://api.po.st/analytics/v1/<report>.json?<params>

.json – Indicates the type of the requested resource. Currently we support only json

report –  Type of report (daily / content / services / country). We provide 4 reports similar to the ones that are available in the UI:

http://api.po.st/analytics/v1/daily.json

http://api.po.st/analytics/v1/content.json

http://api.po.st/analytics/v1/services.json

http://api.po.st/analytics/v1/country.json

Parameters:

Parameter NameTypeDescriptionDefault value

access-token

string

Required, shall be issued to each publishers for access to the API,

Access Token is found under Settings in the top right hand corner of the Po.st Dashboard

 

pubkey

string

Required, a report is built for a specific pubkey, Publisher Key (pubkey) is found under Account in the Po.st Dashboard

 

period-from

period-to

period

date (ISO 8601 YYYY-MM-DD)

date

today|yesterday|week|month

Parameters that specify the filter by date for the report.

If you set period - the other two are ignored 

period=today

period-from=today

period-to=today

sort

name columns (optional symbol "-"):

clicks/shares – for all reports, plus:

date – for daily report

url – for content report

service – for service report

country – for country report

Indicates a column to sort. Add a "-" character to the name of the column to indicate the decreasing direction of sorting. 

For all reports = shares-

For daily = date-

start

integer

The first line of the data, starting with 1. Together with the max option allows for pagination.

1

max

integer

The maximum number of rows to be included in the report.

 

 

Answer Format:

Daily

{
    "rows" : [
        {
            "date" : "2013-05-01",
            "shares" : 15,
            "clicks" : 20
        },
        {
            "date" : "2013-05-01",
            "shares" : 12,
            "clicks" : 22
        },
        ...
    ],
    "totalRows" : 14
}

Content

{
    "rows" : [
        {
            "url" : "http://exampe.com/article-1",
            "shares" : 15,
            "clicks" : 20
        },
        {
            "url" : "http://exampe.com/article-2",
            "shares" : 12,
            "clicks" : 22
        },
        ...
    ],
    "totalRows" : 14
}

Services

{
    "rows" : [
        {
            "service" : "Facebook",
            "serviceCode" : "facebook",
            "shares" : 15,
            "clicks" : 20
        },
        {
            "service" : "Twitter",
            "serviceCode" : "twitter",
            "shares" : 12,
            "clicks" : 22
        },
        ...
    ],
    "totalRows" : 14
}

Country

{
    "rows" : [
        {
            "country" : "USA",
            "countryCode" : "US"
            "shares" : 15,
            "clicks" : 20
        },
        {
            "country" : "Australia",
            "countryCode" : "AU"
            "shares" : 12,
            "clicks" : 22
        },
        ...
    ],
    "totalRows" : 14
}

Errors

If a lookup request to the API has an error occur, it is returned as an http response with the appropriate http status code in the body of the response json:

{
 "error" : {
                "status" : 404
                "code" : 1,
                "message" : "Not found",
                "details" : "Resource located at  '/analytics/v1/browser' path was requested but it doesn't exists",
                "moreInfo" : "http://support.po.st/issue14",
 }

Status

Code

Message

 

 

400

41

Missing Parameter

Required parameters 'access-token' is missing.

Required parameters 'pubkey' is missing.

No set access-token or pubkey options.

400

42

Invalid Parameter

Invalid parameter 'period' with value 'today1'. Supported values are 'today', 'yesterday', 'week', 'month'.

You should define both parameters 'period-from' and 'period-to' or no one.

Invalid parameter 'period-from, period-to' with value '2013-08-26, 2013-08-24'. The dates are mixed up'.

Invalid parameter 'sort' with value 'xcb'. Supported values are 'clicks', 'shares', 'date', 'url', 'service',
'country'. And you can use '-' at the end for descending sorting, for a example 'shares-'.

The report type 'services' doesn't support sorting parameter 'date'.

Invalid parameter 'start' with value '-5'. Parameter value should be nonnegative integer.

Invalid parameter 'max' with value '-5'. Parameter value should be nonnegative integer.

Incorrectly set one of the parameters. For example 'year' for the period, -5 to max, etc.

400

43

Rate Limited

You have exceeded the rate limit.

Exceeded the number of requests for the same token.

401

44

Authentication Failed

The publisher with access-token '4fce641b-0cb6-11e3-afe7-2716faa64e93' is not found.

 

404

45

Not Found

Resource located at '/analytics/v1/services1.svn' path was requested but it doesn't exists

In the URL, incorrectly specified report type or format of the answer. In this case services1 and svn.

500

51

Internal Error

Something has gone wrong!

Unexpected internal error.

503

52

Service Unavailable

 

 

 

Rate Limits

100 requests / hour

Example

Request for the top 50 URLs looking for the pubkey "xyz"

https://api.po.st/analytics/v1/content.json?access-token=ABC&pubkey=xyz&period=week&max=50

 

Answer

{
    "rows": [
        {
            "url" : "http://exampe.com/article-1",
            "clicks" : 46,
            "shares" :55
        },
        {
            "url" : "http://exampe.com/article-2",
            "clicks" : 72,
            "shares" : 36
        },
        ...
    ],
  "totalRows": 118
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk