Jamie Maguire

Software Architect / Consultant / Developer / Microsoft AI MVP

Analytics and Big Data, C#, Chatbots, Prototyping, Social Media, Twitter

MyAnalytics and the Twitter Labs Metrics API

Since I started the blog, I’ve found myself regularly checking analytics across Google, LinkedIn and Twitter.

I do this to help identify which content resonates with readers and sometimes use the levels of engagement (comments, likes or shares) and impressions/views to help me figure out the types of content I should be creating more of.

The main values I typically check are:

  • Google Analytics: pageviews, duration on a page, number of users and locations
  • LinkedIn: number of comments, shares, reactions (likes, etc.)
  • Twitter:  number of comments, retweets, impressions, and likes

All of this is a manual process. It basically involves me logging into Google Analytics, LinkedIn and Twitter then clicking through each post to (again) manually eyeball each of the main metrics I’m interested in.

Twitter Labs and the Metrics API

Twitter recently launched a Developer Labs initiative which gives developers earlier insights into new APIs being developed on the platform.  You get the chance to provide feedback to the DevRel and Product Teams through this initiative and potentially influence the design.

One of the APIs, that caught my interest was the Metrics API. Using this API, you can surface analytics insights for a single Tweet or collection of Tweets.

At the time of writing, you can extract the following engagement insights using this API:

  • impressions
  • Retweets
  • Quote Tweets
  • likes
  • replies
  • video views
  • video view quartiles

This got me thinking.  I could use this API to automate the manual checks from a Twitter analytics perspective and in this blog post, we’ll see exactly how to do this in C#.

How do you access the Twitter Metrics API?

You can get started with Twitter Labs for free by visiting https://developer.twitter.com/en/account/labs.  After you’ve activated your account, you’re good to go. The documentation is easy to follow and creating an account is straightforward enough.

When your account is created, you’ll be granted a series of secret keys and tokens. Keep these safe or event encrypt them as you’ll need these to make requests to the Metrics API. You may even want to use a password manager.

Consuming the Metrics API with Postman

Armed with your tokens and keys, you can now start to make calls to the Metrics API.  For reference, I’m using the following Tweets from my personal Twitter account.

For context, I had recently published two blog posts showing developers about new chatbot technology that had been released by the Microsoft Bot Framework Team.

In this first Tweet (above) and Status ID: 1233703627887431680, you can see some of the following key metrics:

  • 2 Comments
  • 13 Retweets
  • 32 Likes
  • 1 Quote

As  I’m the author of the Tweet, I also get access to further analytics for this Tweet:

In this second Tweet (Status ID: 1236742806925971464), you can see the following metrics:

  • 2 comments
  • 9 retweets
  • 22 likes

And the associated analytics:

Note: At the time of writing, Link clicks and Detail expands are only available through the Engagement API.   The Engagement API is a commercial API that is available through an Enterprise or annual subscription agreement.

Now that we have an idea of what values to expect, we can give the Metrics API a test in Postman.  Here you can see the Tweet Ids being passed into Postman and the response we get back:

Metrics API JSON Response

If we take a closer look at the underlying JSON, we can see we have the metrics for each Tweet:

{

    "data": [

        {

            "tweet_id": "1233703627887431680",

            "tweet": {

                "like_count": 32,

                "retweet_count": 13,

                "quote_count": 1,

                "reply_count": 2,

                "impression_count": 4521

            }

        },

        {

            "tweet_id": "1236742806925971464",

            "tweet": {

                "like_count": 22,

                "retweet_count": 9,

                "quote_count": 0,

                "reply_count": 2,

                "impression_count": 2937

            }

        }

    ]

}

Consuming the Metrics API with C#

Next, we’ll write some C# that consumes the Metrics API and hydrate a strongly typed object from the returned JSON.

DTO (Domain Transfer Objects)

First, we create the following DTOs to represent the incoming data from the Metrics API:

public class Tweet
{

    [JsonProperty("like_count")]

    public int like_count { get; set; }


    [JsonProperty("retweet_count")]

    public int retweet_count { get; set; }


    [JsonProperty("quote_count")]

    public int quote_count { get; set; }


    [JsonProperty("reply_count")]

    public int reply_count { get; set; }


    [JsonProperty("impression_count")]

    public int impression_count { get; set; }

}

public class Data
{

    [JsonProperty("tweet_id")]

    public string tweet_id { get; set; }


    [JsonProperty("tweet")]

    public Tweet tweet { get; set; }

}

public class TweetMetrics
{

    [JsonProperty("data")]

    public IList<Data> data { get; set; }

}

(Note: I explained why creating DTOs is a good practice in my Instagram series.  You can find out more about that here.)

Next, we create a method GetTweetMetrics that creates an authorised request to the Metrics API endpoint.  This method does a few things:

  • Sets the OAuth Authentication data (using the keys from the earlier step)
  • Sets the endpoint URL and type (GET)
  • Adds the list of Tweet Ids to get metrics for
  • Invokes the request
  • Takes the JSON string response from the Metrics API
  • Serializes the JSON response to the DTO TweetMetrics
public TweetMetrics GetTweetMetrics(List<string> tweetIds)
{

    oAuth.AccessSecret = _AccessTokenSecret;

    oAuth.AccessToken = _AccessToken;

    oAuth.ConsumerKey = _ConsumerKey;

    oAuth.ConsumerSecret = _ConsumerSecret;


    RequestBuilder rb = 

new RequestBuilder(oAuth, "GET", "https://api.twitter.com/labs/1/tweets/metrics/private");


    rb.AddParameter("ids", string.Join(",", tweetIds));


    TweetMetrics fullSearchResult = new TweetMetrics();


    string result = rb.Execute();


    TweetMetrics tweetMetrics = JsonConvert.DeserializeObject<TweetMetrics>(result);


    return tweetMetrics;

With everything in place, we can now run this and examine the data we get back in Visual Studio.  Here you can see we have returned two Tweets:

If we expand the first node (item 0) we can see the metrics for our Tweet with tweet id 1236742806925971464:

We can expand the second node (item 1) and get the metrics for tweet id 1233703627887431680:

Note: there may be subtle inaccuracies due to the real-time nature of Twitter. As I capture the debugging information and screenshots for this blog, users will have accessed the Tweets we are referencing and increased the metrics!

Further Thoughts and Use Cases

So, there you have it: How to integrate the Twitter Labs Metrics API using C#.  I’ll be merging this code and API into another tool I’ve built called Social Opinion. It’ll form part of new functionality I’m calling MyAnalytics.

MyAnalytics will surface all main analytics I typically check each day and will save me a bit of time.  Here are some other ideas:

Azure

Embed code in an Azure Function or Azure Web Job that periodically pulls data directly from the Metrics API.  You can then push the data directly into a datastore such as Azure SQL then visualise this data using a product like Power BI.

Chatbot

A conversational agent could be used to interact with data from the Metrics API. For example, you can add Natural Language Understanding using technology such as Microsoft LUIS, and you can create a chatbot which you can ask questions such as:

  • What was my best performing tweet in the last 30 days?
  • How many Tweets received over 100 comments?

Ideal for digital marketers, content creators, and data specialists.

Web Application

House the data in a web application (with other datasets) to give you an easy to view dashboard that contains the analytics you care about.  This is what I’ll be using it for!

Summary

In this blog post, we’ve introduced the Twitter Labs Metrics API. We’ve explored the data you can extract, how to consume the API using C# and explored some of the use cases you might deploy this in.

Got a question?

Want to know more?

Drop me a message below or reach out on social.

JOIN MY EXCLUSIVE EMAIL LIST
Get the latest content and code from the blog posts!
I respect your privacy. No spam. Ever.

Leave a Reply