Questions? Feedback? powered by Olark live chat software

Union Metrics Help

Have questions? We've got answers!

Using our Twitter API

The Union Metrics Twitter API offers read-only programmatic access to some Twitter Tracker data. The API is available to all suite subscribers, as well as certain customers on our legacy TweetReach Pro plans.

Access to the Union Metrics Twitter API is provided via secure HTTPS GET requests to the Union Metrics servers. Each request must provide an API Key for authentication. Responses with API data can be formatted in either JSON or XML.

Getting Started

To access the API, you will first need to obtain an API Key to use in your requests to Union Metrics. After that you can make requests to the Union Metrics Twitter API URLs to fetch your data.

Obtain an API Key

The API Key provides authentication to the Union Metrics Twitter API for any eligible subscribers. This key acts like a password to authorize access to your data via the API and should be kept secure. Here are the steps for obtaining your key.

  1. Log in to your Union Metrics accounts as the account owner 
  2. Click the "Account" link at the top right
  3. Locate the "API Access" section on your account information page
  4. Click the "Generate Key" button
  5. The page will reload and display a sequence of numbers and letters - this is your API Key
  6. Copy your API Key for use with all requests to the Union Metrics Twitter API

If you ever believe your API Key security may be compromised and you wish to change it, locate the API Access section of your Account page and click the "Regenerate" button.

Request Some Data

You can try out the Union Metrics Twitter API in your web browser by making a request to an API resource. Below is an example URL:

https://api.tweetreach.com/1/trackers.xml?api_key={api_key}

Just replace {api_key} in the above URL with your API Key and paste the full URL into your web browser. You'll see a response that lists out all the Trackers in your account. It will look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <data>
    <value>
      <group>
        <id>1</id>
        <label>Tracker 1</label>
        <type>tracker</type>
      </group>
      <reach>16084370</reach>
      <exposure>37610326</exposure>
      <activity>44666</activity>
      <contributors>38551</contributors>
      <retweets>15814</retweets>
      <replies>2309</replies>
      <normal>26543</normal>
    </value>
    <value>
      <group>
        <id>2</id>
        <label>Tracker 2</label>
        <type>tracker</type>
      </group>
      <reach>2950319</reach>
      <exposure>34449748</exposure>
      <activity>4536</activity>
      <contributors>1111</contributors>
      <retweets>2599</retweets>
      <replies>478</replies>
      <normal>1459</normal>
    </value>
  </data>
</response>

 

API Key

Every request to the Union Metrics Twitter API must contain an API key for authentication purposes. You can create, regenerate or delete your API key from your Account settings in your Union Metrics account.

API Key Security

Keep your API Key secure and do not share it with anyone. If you suspect your API key has been compromised, you may generate a new key by doing the following:

  1. Click your Account link in your Union Metrics portal
  2. Click the "Regenerate" button in the "API Access" section of your Account page
  3. Begin using the new API key in API requests

Resources and URLs

The Union Metrics Twitter API comprises a set of HTTPS URLs that represent different types of data such as a Tracker or list of contributors within a Tracker. A resource is essentially a URL for a specific type of data. 

All URLs are structured as follows.

https://api.tweetreach.com/{version}/{path}.{format}?{parameters}&api_key={api_key}

The components of the URL are as follows:

  • version - The version of the API. Currently the only supported value is 1
  • path - This is the path to an API resource such as trackers. Paths may contain / (e.g. trackers/99).
  • format - The format of the response data. json and xml are currently supported.
  • parameters - Standard HTTP parameters formatted as key2=value2&key2=value2
  • api_key - The API key found in your TweetReach Pro account

Common URL Parameters

There are two parameters that will be used throughout the API: period and group.

Period Parameter

Example (for October 1st, 2011): period=day-201110010000

The period parameter restricts the data being returned by an API endpoint to a range of time. This parameter is formatted as follows:

{type}-{YYYYMMDDhhmm}

The components of the period are:

  • type - One of day, week, month
  • YYYYMMDDhhmm - The formatted date and time of the first time in the specified period. (e.g. month-201105010000 for the month of May, 2011). The date and time must be specified in the same time zone as the Tracker data being requested.

There is also a special period known as the all period. It may be specified as period=all. This will not restrict the data by date.

Group Parameter

Example: group=week

The group parameter tells the API endpoint how to "group" or "roll up" the data being requested. For data that represents trends over time, it will often be one of day, week, or month.

Response Data

Responses include a data section which contains a list of values. Each value contains a group and a set of named data points. The group is controlled by the group parameter and describes the "rollup" used to compute the data points. For example if you request data with a group of "day", each value will contain a set of data points that have been computed for a single day. Groups have 3 attributes:

  • label - This is the human readable description of the group such as "2011-05-01" for a day
  • id - This is an id for the group that can be used to get more data in the API. For example, the id for a Month group can be used as a period for another request to "drill into" a particular Month of data
  • type - The type is the kind of group. This may be a day, week or month. It might also be another value like "tracker" or "contributor".

Response Formats

The API will respond with data formatted according to the format specified in the URL. Typically responses will be as follows:

XML

<response>
  <data>
    <value>
      <group>
        <id>day-20110901</id>
        <label>09/01/2011</label>
        <type>day</type>
      </group>
      <metric1>100</metric1>
      <metric2>200</metric2>
    </value>
    <!-- value will repeat with more data points -->
  </data>
</response>

JSON

{
  data: [
    {group: {id: "day-20110901", label: "2011-09-01", type: "day"}, metric1: 100, metric2: 200 },
    /* more data points go here */
  ]
} 

Dates

Where dates appear in responses, they will be formatted as

YYYY-MM-DD hh:mm Z

Notes:

  • The time component (hh:mm) is optional. If not included, assume 00:00
  • When included hours will be expressed in 24 hour time as 00-23
  • The time zone (Z) is optional. If not included, it should be inferred from the data being retrieved, e.g. Tracker data will be in the Tracker's configured time zone.
  • The time zone format is "+/-hhmm" where hhmm is the number of hours and minutes the time is offset from UTC

In Group Labels

Dates are often used in labels for group types of days, weeks or months. When they are used in this way the label will show the date of the first day in the group:

  • Month: 2011-05-01 for the month of May, 2011
  • Week: 2011-10-02 for the Week beginning on October 2nd, 2011
  • Day: 2011-05-07 for the day May 7th, 2011 

Terms of Service 

Access to the Union Metrics Twitter API is governed by the general TweetReach Terms of Service.

Additional Guidelines

We ask that you observe the following guidelines when working with the API:

  1. Keep requests to a minimum (no more than 60 per hour) and cache aggressively. Do not rely on polling Union Metrics for real-time statistics. Excessive requests in a short time frame may result in suspension of access.
  2. Keep your API Key secure. Do not share it with 3rd parties for any reason. If you believe your key has been compromised you may generate a new key.
  3. When using Union Metrics data publicly, please include attribution and a link back to unionmetrics.com
  4. Be flexible when parsing responses from the API. While we will make every effort not to introduce incompatible changes, we may change response attributes and formats from time to time. It is a very good idea to ensure that your parsing code can handle the introduction of new attributes without additional effort.

 

Trackers Resource

Provides a list of all Trackers that have been configured in your Union Metrics account along with their summary reach, exposure, activity and contributors metrics.

URL

https://api.tweetreach.com/1/trackers.{format}

Parameters 

Name Required? Default Description
period Optional all The id of the period to retrieve data for
group Optional tracker  

Example XML Request

Retrieve information about each tracker during the month of September, 2011.

https://api.tweetreach.com/1/trackers.xml?period=month-20110901&api_key=secret

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <data>
    <value>
      <group>
        <id>1</id>
        <label>#foo</label>
        <type>tracker</type>
      </group>
      <reach>2950319</reach>
      <exposure>34449748</exposure>
      <activity>4536</activity>
      <contributors>1111</contributors>
      <retweets>2599</retweets>
      <replies>478</replies>
      <normal>1459</normal>
    </value>
    <value>
      <group>
        <id>2</id>
        <label>#bar</label>
        <type>tracker</type>
      </group>
      <reach>759080</reach>
      <exposure>4248339</exposure>
      <activity>3333</activity>
      <contributors>1252</contributors>
      <retweets>1898</retweets>
      <replies>209</replies>
      <normal>1226</normal>
    </value>
  </data>
</response>

Contributors Resource

Provides a list of all Contributors within a Tracker including their exposure, activity, retweets, retweet_rate, total_exposure andamplification_multiplier metrics.

URL

https://api.tweetreach.com/1/trackers/{tracker_id}/contributors.{format}

Parameters

Name Required? Default Description
tracker_id Required N/A The id of the Tracker to retrieve data for
period Optional all The id of the period to retrieve data for
group Optional contributor Roll up data for each contributor
sort_by Optional exposure What metric to use to sort the results.
sort_dir Optional desc The direction to sort the results. One of asc or desc

Response

The response groups will contain the following data:

  • label - The user's Twitter screen name
  • id - The user's Twitter id

Example XML Request

Retrieve a listing of the top 5 contributors from Tracker 1 during the day of September 15th, 2011 order by descending activity.

https://api.tweetreach.com/1/trackers/1/contributors.xml?period=day-20110915&limit=5&sort_by=activity&sort_dir=desc&api_key=secret

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <data>
    <value>
      <group>
        <id>972651</id>
        <label>user1</label>
        <type>contributor</type>
      </group>
      <exposure>2562223</exposure>
      <activity>1</activity>
      <retweets>71</retweets>
      <retweet_rate>71.0</retweet_rate>
      <total_exposure>2673377</total_exposure>
      <amplification_multiplier>1.04</amplification_multiplier>
    </value>
    <value>
      <group>
        <id>94682674</id>
        <label>user2</label>
        <type>contributor</type>
      </group>
      <exposure>2256400</exposure>
      <activity>131</activity>
      <retweets>108</retweets>
      <retweet_rate>0.824</retweet_rate>
      <total_exposure>2466985</total_exposure>
      <amplification_multiplier>1.09</amplification_multiplier>
    </value>
    <value>
      <group>
        <id>42519612</id>
        <label>user3</label>
        <type>contributor</type>
      </group>
      <exposure>1697840</exposure>
      <activity>1</activity>
      <retweets>0</retweets>
      <retweet_rate>0.0</retweet_rate>
      <total_exposure>1697840</total_exposure>
      <amplification_multiplier>1.0</amplification_multiplier>
    </value>
    <value>
      <group>
        <id>3840</id>
        <label>user4</label>
        <type>contributor</type>
      </group>
      <exposure>755729</exposure>
      <activity>6</activity>
      <retweets>5</retweets>
      <retweet_rate>0.833</retweet_rate>
      <total_exposure>770725</total_exposure>
      <amplification_multiplier>1.02</amplification_multiplier>
    </value>
    <value>
      <group>
        <id>745273</id>
        <label>user5</label>
        <type>contributor</type>
      </group>
      <exposure>336626</exposure>
      <activity>29</activity>
      <retweets>19</retweets>
      <retweet_rate>0.655</retweet_rate>
      <total_exposure>360217</total_exposure>
      <amplification_multiplier>1.07</amplification_multiplier>
    </value>
  </data>
</response>
 

Tracker Resource

Provides data about a specific Tracker. Can be used to provide a summary or trend rollup of reach, exposure, activity and contributors metrics.

URL

https://api.tweetreach.com/1/trackers/{tracker_id}.{format}

Parameters

Name Required? Default Description
tracker_id Required N/A The id of the Tracker to retrieve data for. This can be obtained from the Trackers Resource.
period Optional all The id of the period to retrieve data for
group Optional tracker One of tracker, day, week, month. If tracker is specified, the metrics will not be broken down into trend data.

Example XML Request

Retrieve metrics by day for Tracker 1 during the month of September, 2011.

https://api.tweetreach.com/1/trackers/1.xml?period=month-20110901&group=day&api_key=secret

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <data>
    <value>
      <group>
        <id>day-201109010000</id>
        <label>2011-09-01</label>
        <type>day</type>
      </group>
      <reach>74182</reach>
      <exposure>128459</exposure>
      <activity>63</activity>
      <contributors>53</contributors>
      <retweets>17</retweets>
      <replies>10</replies>
      <normal>37</normal>
    </value>
    <value>
      <group>
        <id>day-201109020000</id>
        <label>2011-09-02</label>
        <type>day</type>
      </group>
      <reach>86349</reach>
      <exposure>103551</exposure>
      <activity>62</activity>
      <contributors>56</contributors>
      <retweets>14</retweets>
      <replies>6</replies>
      <normal>42</normal>
    </value>
    <value>
      <group>
        <id>day-201109030000</id>
        <label>2011-09-03</label>
        <type>day</type>
      </group>
      <reach>10487</reach>
      <exposure>11397</exposure>
      <activity>11</activity>
      <contributors>9</contributors>
      <retweets>0</retweets>
      <replies>1</replies>
      <normal>10</normal>
    </value>
    <value>
      <group>
        <id>day-201109040000</id>
        <label>2011-09-04</label>
        <type>day</type>
      </group>
      <reach>12742</reach>
      <exposure>13340</exposure>
      <activity>9</activity>
      <contributors>8</contributors>
      <retweets>2</retweets>
      <replies>1</replies>
      <normal>6</normal>
    </value>
    <value>
      <group>
        <id>day-201109050000</id>
        <label>2011-09-05</label>
        <type>day</type>
      </group>
      <reach>8512</reach>
      <exposure>8957</exposure>
      <activity>20</activity>
      <contributors>19</contributors>
      <retweets>6</retweets>
      <replies>1</replies>
      <normal>13</normal>
    </value>
    <value>
      <group>
        <id>day-201109060000</id>
        <label>2011-09-06</label>
        <type>day</type>
      </group>
      <reach>31258</reach>
      <exposure>35849</exposure>
      <activity>39</activity>
      <contributors>31</contributors>
      <retweets>7</retweets>
      <replies>6</replies>
      <normal>26</normal>
    </value>
    <value>
      <group>
        <id>day-201109070000</id>
        <label>2011-09-07</label>
        <type>day</type>
      </group>
      <reach>98395</reach>
      <exposure>162613</exposure>
      <activity>68</activity>
      <contributors>51</contributors>
      <retweets>11</retweets>
      <replies>11</replies>
      <normal>46</normal>
    </value>
    <value>
      <group>
        <id>day-201109080000</id>
        <label>2011-09-08</label>
        <type>day</type>
      </group>
      <reach>82340</reach>
      <exposure>106147</exposure>
      <activity>56</activity>
      <contributors>50</contributors>
      <retweets>10</retweets>
      <replies>15</replies>
      <normal>31</normal>
    </value>
    <value>
      <group>
        <id>day-201109090000</id>
        <label>2011-09-09</label>
        <type>day</type>
      </group>
      <reach>39716</reach>
      <exposure>44687</exposure>
      <activity>32</activity>
      <contributors>29</contributors>
      <retweets>6</retweets>
      <replies>6</replies>
      <normal>20</normal>
    </value>
    <value>
      <group>
        <id>day-201109100000</id>
        <label>2011-09-10</label>
        <type>day</type>
      </group>
      <reach>50235</reach>
      <exposure>67307</exposure>
      <activity>21</activity>
      <contributors>20</contributors>
      <retweets>8</retweets>
      <replies>4</replies>
      <normal>9</normal>
    </value>
    <value>
      <group>
        <id>day-201109110000</id>
        <label>2011-09-11</label>
        <type>day</type>
      </group>
      <reach>17709</reach>
      <exposure>18465</exposure>
      <activity>15</activity>
      <contributors>14</contributors>
      <retweets>1</retweets>
      <replies>2</replies>
      <normal>12</normal>
    </value>
    <value>
      <group>
        <id>day-201109120000</id>
        <label>2011-09-12</label>
        <type>day</type>
      </group>
      <reach>79202</reach>
      <exposure>106195</exposure>
      <activity>34</activity>
      <contributors>30</contributors>
      <retweets>9</retweets>
      <replies>8</replies>
      <normal>17</normal>
    </value>
    <value>
      <group>
        <id>day-201109130000</id>
        <label>2011-09-13</label>
        <type>day</type>
      </group>
      <reach>206969</reach>
      <exposure>252890</exposure>
      <activity>51</activity>
      <contributors>31</contributors>
      <retweets>9</retweets>
      <replies>4</replies>
      <normal>38</normal>
    </value>
    <value>
      <group>
        <id>day-201109140000</id>
        <label>2011-09-14</label>
        <type>day</type>
      </group>
      <reach>136619</reach>
      <exposure>163242</exposure>
      <activity>65</activity>
      <contributors>52</contributors>
      <retweets>13</retweets>
      <replies>13</replies>
      <normal>39</normal>
    </value>
    <value>
      <group>
        <id>day-201109150000</id>
        <label>2011-09-15</label>
        <type>day</type>
      </group>
      <reach>487018</reach>
      <exposure>679715</exposure>
      <activity>170</activity>
      <contributors>155</contributors>
      <retweets>30</retweets>
      <replies>14</replies>
      <normal>127</normal>
    </value>
    <value>
      <group>
        <id>day-201109160000</id>
        <label>2011-09-16</label>
        <type>day</type>
      </group>
      <reach>250212</reach>
      <exposure>385598</exposure>
      <activity>85</activity>
      <contributors>79</contributors>
      <retweets>21</retweets>
      <replies>5</replies>
      <normal>60</normal>
    </value>
    <value>
      <group>
        <id>day-201109170000</id>
        <label>2011-09-17</label>
        <type>day</type>
      </group>
      <reach>143321</reach>
      <exposure>191493</exposure>
      <activity>51</activity>
      <contributors>45</contributors>
      <retweets>10</retweets>
      <replies>4</replies>
      <normal>37</normal>
    </value>
    <value>
      <group>
        <id>day-201109180000</id>
        <label>2011-09-18</label>
        <type>day</type>
      </group>
      <reach>47592</reach>
      <exposure>67028</exposure>
      <activity>30</activity>
      <contributors>26</contributors>
      <retweets>2</retweets>
      <replies>1</replies>
      <normal>27</normal>
    </value>
    <value>
      <group>
        <id>day-201109190000</id>
        <label>2011-09-19</label>
        <type>day</type>
      </group>
      <reach>345067</reach>
      <exposure>374071</exposure>
      <activity>55</activity>
      <contributors>49</contributors>
      <retweets>13</retweets>
      <replies>3</replies>
      <normal>39</normal>
    </value>
    <value>
      <group>
        <id>day-201109200000</id>
        <label>2011-09-20</label>
        <type>day</type>
      </group>
      <reach>128272</reach>
      <exposure>136595</exposure>
      <activity>84</activity>
      <contributors>79</contributors>
      <retweets>18</retweets>
      <replies>9</replies>
      <normal>57</normal>
    </value>
    <value>
      <group>
        <id>day-201109210000</id>
        <label>2011-09-21</label>
        <type>day</type>
      </group>
      <reach>81586</reach>
      <exposure>112488</exposure>
      <activity>69</activity>
      <contributors>56</contributors>
      <retweets>21</retweets>
      <replies>13</replies>
      <normal>35</normal>
    </value>
    <value>
      <group>
        <id>day-201109220000</id>
        <label>2011-09-22</label>
        <type>day</type>
      </group>
      <reach>103289</reach>
      <exposure>156587</exposure>
      <activity>58</activity>
      <contributors>45</contributors>
      <retweets>18</retweets>
      <replies>12</replies>
      <normal>28</normal>
    </value>
    <value>
      <group>
        <id>day-201109230000</id>
        <label>2011-09-23</label>
        <type>day</type>
      </group>
      <reach>52407</reach>
      <exposure>67374</exposure>
      <activity>45</activity>
      <contributors>40</contributors>
      <retweets>6</retweets>
      <replies>5</replies>
      <normal>34</normal>
    </value>
    <value>
      <group>
        <id>day-201109240000</id>
        <label>2011-09-24</label>
        <type>day</type>
      </group>
      <reach>101416</reach>
      <exposure>162776</exposure>
      <activity>42</activity>
      <contributors>34</contributors>
      <retweets>14</retweets>
      <replies>2</replies>
      <normal>26</normal>
    </value>
    <value>
      <group>
        <id>day-201109250000</id>
        <label>2011-09-25</label>
        <type>day</type>
      </group>
      <reach>66266</reach>
      <exposure>118169</exposure>
      <activity>17</activity>
      <contributors>14</contributors>
      <retweets>3</retweets>
      <replies>3</replies>
      <normal>11</normal>
    </value>
    <value>
      <group>
        <id>day-201109260000</id>
        <label>2011-09-26</label>
        <type>day</type>
      </group>
      <reach>174336</reach>
      <exposure>253247</exposure>
      <activity>65</activity>
      <contributors>50</contributors>
      <retweets>9</retweets>
      <replies>10</replies>
      <normal>46</normal>
    </value>
    <value>
      <group>
        <id>day-201109270000</id>
        <label>2011-09-27</label>
        <type>day</type>
      </group>
      <reach>48385</reach>
      <exposure>60127</exposure>
      <activity>38</activity>
      <contributors>36</contributors>
      <retweets>10</retweets>
      <replies>2</replies>
      <normal>26</normal>
    </value>
    <value>
      <group>
        <id>day-201109280000</id>
        <label>2011-09-28</label>
        <type>day</type>
      </group>
      <reach>100953</reach>
      <exposure>175408</exposure>
      <activity>67</activity>
      <contributors>54</contributors>
      <retweets>15</retweets>
      <replies>11</replies>
      <normal>41</normal>
    </value>
    <value>
      <group>
        <id>day-201109290000</id>
        <label>2011-09-29</label>
        <type>day</type>
      </group>
      <reach>278796</reach>
      <exposure>363791</exposure>
      <activity>84</activity>
      <contributors>66</contributors>
      <retweets>19</retweets>
      <replies>14</replies>
      <normal>51</normal>
    </value>
    <value>
      <group>
        <id>day-201109300000</id>
        <label>2011-09-30</label>
        <type>day</type>
      </group>
      <reach>112709</reach>
      <exposure>185376</exposure>
      <activity>55</activity>
      <contributors>41</contributors>
      <retweets>16</retweets>
      <replies>7</replies>
      <normal>32</normal>
    </value>
  </data>
</response>

 

 
Have more questions? Submit a request

Comments