Mutable Ideas

Notes and ideas about Java, Scala, Big Data, NoSQL, Quality and Software Deploy

Accessing Campaign Metrics on Socialmetrix Quantum

This is the second post about Socialmetrix Quantum API, at this time we’ll use the API to show summary statistics about campaigns. Please refer to the first post in order to get your API token and basic API usage instructions.

We walk you through the process of creating a campaign and assinging posts to it through the web ui, once the information is loaded, we’ll extract this metrics using Quantum API.

Creating a campaign (Using the Web UI)

Log in to Quantum and go to Campaign Tab. Click on Add new Campaign and give a meaningful name to the campaign:

Creating a Quantum Campaign - Step 1

When you complete, you should see your new campaign:

Creating a Quantum Campaign - Step 2

All campaign metrics will be on Zero, it is expected, you need to assign posts to your new created campaign.

Assigning posts to the campaign

Click on the left menu and go to Strem view. Select the posts you know are part of your campaign:

Assigning posts to the campaign - Step 1

Assign the post to the campaign you’ve created, you can also provide the budget spent on this post.

Assigning posts to the campaign - Step 2

Keep assigning posts to your campaign, if you do not provide a budget everything will work as expected you just won’t be able to see the investment metric as part of the results.

Assigning posts to the campaign - Step 3

Once you load several posts to your campaign, the system will recalc the ROI and we can check the information via UI or API, let’s use the API:

Summary of all available campaigns (Using the API)

Select a campaign

Endpoint GET /v1/accounts/YOUR_ACCOUNT_ID/projects/YOUR_PROJECT_ID/campaigns will return a Json Array containing all your campaigns. You must keep the id that will be used to next requests.

1
2
3
curl 'https://api.quantum.socialmetrix.com/v1/accounts/790/projects/14/campaigns' \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: eyJhbGciOiJIUzI1NiJ9.eyJpc3M.........Xl294h4pM7FSLkpq2nUE5_VSgt5KoYIo"
1
2
3
4
5
[
  {"id":790, "name":"Ferias", "accountId":790, "projectId":14, "createdTime":"2016-06-22T15:32:30Z"},
  {"id":789, "name":"Halloween", "accountId":790, "projectId":14, "createdTime":"2016-06-22T15:32:07Z"},
  {"id":788, "name":"Promo Winter", "accountId":790, "projectId":14, "createdTime":"2016-06-22T14:09:23Z"}
]

On my example, the campaign id is 788 for the campaign Promo Winter.

Getting summary information about a specific campaign

Using the endpoint GET /v1/accounts/YOUR_ACCOUNT_ID/projects/YOUR_PROJECT_ID/facebook/campaigns/stat-summary?since=FROM_DATE&until=TO_DATE&ids=CAMPAIGN_ID you can obtain summary statistics about a campaign, keep in mind you must specify the time range for your campaign and it can be partial, ie: You can get a portion related with the engajement for this period.

1
2
3
curl 'https://api.quantum.socialmetrix.com/v1/accounts/790/projects/14/facebook/campaigns/stat-summary?since=2016-05-23&until=2016-06-21&ids=788' \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: eyJhbGciOiJIUzI1NiJ9.eyJpc3M.........Xl294h4pM7FSLkpq2nUE5_VSgt5KoYIo"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "query": {
    "id": "/accounts/790/projects/14/facebook/campaigns/stat-summary",
    "filters": {
      "timezone": "America/Argentina/Buenos_Aires",
      "ids": [
        "788"
      ],
      "since": "2016-05-23",
      "until": "2016-06-21"
    }
  },
  "results": [
    {
      "id": "788",
      "data": {
        "current": {
          "newContents": 4,
          "newInteractions": 90120,
          "investment": 685
        },
        "previous": {
          "newContents": 0,
          "newInteractions": 0,
          "investment": 0
        },
        "lifetime": 709200
      }
    }
  ]
}

Getting main metrics from Campaign Report

Campaign interactions for the period

With your campaign id you can request the main metrics to generate a report, this is a sample campaign report from Quantum UI:

Sample Quantum Campaign Report

1
2
3
curl 'https://api.quantum.socialmetrix.com/v1/accounts/790/projects/14/facebook/campaigns/interactions/count/date?since=2016-05-23&until=2016-06-21&ids=788' \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: eyJhbGciOiJIUzI1NiJ9.eyJpc3M.........Xl294h4pM7FSLkpq2nUE5_VSgt5KoYIo"

This endpoint returns a lot of information about this campaign:

  • .results[].data[]: is a time series where each point represents a day of interactions (summing all posts belonging to this campaign)
  • .results[].currentTotal: contains a sum of all points in the time series for the current period - for convenience
  • .results[].previousTotal: contains a sum of all points in the time series for the previous period, the previous period is defined by a window of same size and ending on the day before our current period.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
  "query": {
    "id": "/accounts/790/projects/14/facebook/campaigns/interactions/count/date",
    "filters": {
      "timezone": "America/Argentina/Buenos_Aires",
      "ids": [
        "788"
      ],
      "since": "2016-05-23",
      "until": "2016-06-21"
    },
    "period": {
      "id": "1d",
      "duration": 86400
    }
  },
  "results": [
    {
      "id": "788",
      "data": [
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":0,"comments":0,"shares":0,"interactions":0},
        {"likes":787,"comments":40,"shares":117,"interactions":944},
        {"likes":1924,"comments":102,"shares":172,"interactions":2198},
        {"likes":14,"comments":10,"shares":1,"interactions":25},
        {"likes":5,"comments":17,"shares":0,"interactions":22},
        {"likes":6,"comments":17,"shares":0,"interactions":23},
        {"likes":7206,"comments":112,"shares":65,"interactions":7383},
        {"likes":33705,"comments":201,"shares":277,"interactions":34183},
        {"likes":25828,"comments":105,"shares":220,"interactions":26153},
        {"likes":18911,"comments":85,"shares":193,"interactions":19189},
        {"likes":0,"comments":0,"shares":0,"interactions":0}
      ],
      "currentTotal": {
        "likes": 88386,
        "comments": 689,
        "shares": 1045,
        "interactions": 90120
      },
      "previousTotal": {
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "interactions": 0
      }
    }
  ]
}

Ranking of Campaign posts by performance (Interactions)

The endpoint GET v1/accounts/YOUR_ACCOUNT_ID/projects/YOUR_PROJECT_ID/facebook/campaigns/CAMPAIGN_ID/posts?since=FROM_DATE&until=TO_DATE retrieves an array containing all posts belonging to a campaign ordered by interactions:

1
2
3
curl 'https://api.quantum.socialmetrix.com/v1/accounts/790/projects/14/facebook/campaigns/788/posts?since=2016-05-23&until=2016-06-21' \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: eyJhbGciOiJIUzI1NiJ9.eyJpc3M.........Xl294h4pM7FSLkpq2nUE5_VSgt5KoYIo"
  • .results[]: each element represents a post
  • .results[].stats: summary statistics for the current post
  • .results[].campaignInfo.investment: the investiment assigned to the current post
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
{
  "query": {
    "id": "/accounts/790/projects/14/facebook/campaigns/788/posts",
    "filters": {
      "timezone": "America/Argentina/Buenos_Aires",
      "ids": null,
      "since": "2016-05-23",
      "until": "2016-06-21"
    }
  },
  "results": [
    {
      "tagsInfo": [],
      "campaignInfo": {
        "content": {
          "category": "post",
          "id": 14198,
          "sourceId": "125056230917537_1035123899910761",
          "contentCreatedTime": "2016-06-17T18:35:00Z"
        },
        "createdTime": "2016-06-22T14:12:18Z",
        "campaign": {
          "id": 788,
          "name": "Promo Winter",
          "accountId": 790,
          "projectId": 14,
          "createdTime": "2016-06-22T14:09:23Z"
        },
        "investment": 235
      },
      "contentInfo": {
        "category": "post",
        "id": 14198,
        "sourceId": "125056230917537_1035123899910761",
        "contentCreatedTime": "2016-06-17T18:35:00Z"
      },
      "id": "125056230917537_1035123899910761",
      "type": 247,
      "message": "Sacolinhas plásticas + grafite = arte consciente. \nConheça o trabalho dessa artista, que faz street art mesclada à reciclagem: goo.gl/1ZMneY",
      "permalink": "http://www.facebook.com/125056230917537/posts/1035123899910761",
      "attachment": "{\"picture\":\"https://scontent.xx.fbcdn.net/v/l/t1.0-9/p720x720/13445368_1035123899910761_5099617137445736001_n.png?oh=78822b009b63c9a42e063435fd798653&oe=57D281F0\",\"description\":\"Sacolinhas plásticas + grafite = arte consciente. \\nConheça o trabalho dessa artista, que faz street art mesclada à reciclagem: goo.gl/1ZMneY\",\"name\":\"Timeline Photos\",\"link\":\"https://www.facebook.com/timbrasil/photos/a.304965662926592.69758.125056230917537/1035123899910761/?type=3\"}",
      "user": {
        "tagsInfo": [],
        "campaignInfo": null,
        "contentInfo": {
          "category": "fb_user",
          "id": null,
          "sourceId": null,
          "contentCreatedTime": null
        },
        "id": "125056230917537",
        "name": "TIM Brasil",
        "comments": 0,
        "posts": 0
      },
      "pageId": "125056230917537",
      "createdTime": "2016-06-17T15:35:00-03:00",
      "lastInteractionTime": "2016-06-20T13:00:00-03:00",
      "stats": {
        "likes": 65305,
        "comments": 255,
        "shares": 586,
        "engagementRate": 0.038307156,
        "interactions": 66146
      },
      "adStatus": "promoted"
    },
    ....
    ....
  ],
  "paging": {
    "previous": null,
    "next": null
  }
}

Wraping up

Using those simple HTTP calls you are able to get your campaigns information and create your custom dashboards.

.

Comments