Questions? Feedback? powered by Olark live chat software

The TweetReach API - Getting Started

The TweetReach API offers read-only programmatic access to some TweetReach Tracker data for customers subscribed to select TweetReach Pro Plans. The API is available to TweetReach Pro subscribers at the Plus, Medium or higher plan levels.

Access to the TweetReach API is provided via secure HTTPS GET requests to the TweetReach API 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 TweetReach API, you will first need to obtain an API Key to use in your requests to TweetReach. After that you can make requests to the TweetReach API URLs to fetch your data.

Obtain an API Key

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

  1. Log in to your TweetReach Pro subscription as the primary account holder
  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 TweetReach 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 TweetReach 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>

 

Concepts

API Key

Every request to the TweetReach API must contain an API key for authentication purposes. You can create, regenerate or delete your API key from your Account settings in your TweetReach Pro portal.

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 TweetReach Pro 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 TweetReach 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 TweetReach 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 TweetReach 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 TweetReach statistics, please offer attribution and a link back to TweetReach.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.
Have more questions? Submit a request

Comments

Article is closed for comments.