Transitioning from Google's URL Shortener API to the Bitly API

For those of you coming to Bitly from Google, welcome! If you formerly used Google to shorten links and retrieve data programmatically or simply want to start doing so with Bitly, this guide is for you. The Bitly API allows you to shorten, brand, and share links through existing or custom integrations, retrieve link-level and user-level analytics programmatically, and more. For inspiration on how the Bitly API can help you streamline your current processes and user experiences, check out some of its most popular uses.

Migrating from Google's URL Shortener API to the Bitly API is straightforward and simple, though our API has additional endpoints that offer more options. We'll go through each of those endpoints in detail, but first you'll need to know how to obtain authorization and different levels of access to the Bitly API.

Authorization

Similar to Google URL Shortener, the Bitly API uses OAuth 2.0 access tokens to identify your application and authorize your account. Unlike Google's tokens, Bitly access tokens do not expire after a set period of time. You can generate a token and reuse it in perpetuity. If your token leaks, you can expire it through our web application.

An OAuth 2.0 access token both identifies the account and authorizes API endpoint requests.

Rate Limits

Free accounts have a rate limit of 10000 new short URLs created per month, 1000 requests to our URL shorten endpoint per hour, and 100 requests to our URL shorten endpoint per minute. Higher limits are available for paid accounts, as are additional functionality, including deep linking. If you are interested in a commercial account, please contact our sales team.

Application using a single account

Most folks using the Bitly API will be writing one or more applications that are used with a single account, such as a CMS integration or bulk shortening script that creates all short URLs in a single account. For this use case, you don't need to worry about implementing entire OAuth 2.0 flows just to obtain an access token. Instead, you can use our Generic Access Token. Log in to Bitly and navigate to the OAuth Apps page, click "Generic Access Token", enter your Bitly password, copy the access token, and paste it into your application for use in making API requests.

Application designed for multiple users

For applications where you expect to have multiple users, each with their own Bitly account, you may need to implement the full OAuth 2.0 web flow, as described on our Authentication.

API Endpoints

Google's URL Shortener has four functions: shortening a long URL, expanding a short URL, retrieving a short URL's analytics, and retrieving a user's link history. The Bitly API has matching API endpoints for shortening, expanding, and retrieving link history, and has multiple endpoints that allow retrieval of different types of analytics data. Bitly endpoints all take GET requests, rather than other HTTP verbs, and require input as URL-encoded query parameters, rather than JSON.

Shorten a long URL

To shorten a long URL http://google.com/, send the following request: GET https://api-ssl.bitly.com/v3/shorten?access_token=XXXX&longUrl=http%3F%2A%2Agoogle.com%2A and you will receive the following response:

{
  "data": {
    "global_hash": "900913", 
    "hash": "ze6poY", 
    "long_url": "http://google.com/", 
    "new_hash": 0, 
    "url": "http://bit.ly/ze6poY"
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

Full documentation for the endpoint is available at /v3/shorten.

Expand a short URL

To expand a short URL http://bit.ly/ze6poY, send the following request: GET https://api-ssl.bitly.com/v3/expand?access_token=XXXX&shortUrl=http%3A%2F%2Fbit.ly%2Fze6poY and you will receive the following response:

{
  "data": {
    "expand": [
      {
        "global_hash": "900913", 
        "long_url": "http://google.com/", 
        "short_url": "http://bit.ly/ze6poY", 
        "user_hash": "ze6poY"
      }
    ]
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

Full documentation for the endpoint is available at /v3/expand.

Retrieving your link history

You can only retrieve the link history for the account represented by the access token you are providing; other users' link history is not available to maintain our users' privacy.

To retrieve your link history, send the following request: GET https://api-ssl.bitly.com/v3/user/link_history?access_token=XXXX and you will receive the following response:

{
  "data": {
    "link_history": [
      {
        "aggregate_link": "http://4sq.com/bGUucR", 
        "archived": false, 
        "client_id": "a5a2e024b030d6a594be866c7be57b5e2dff9972", 
        "created_at": 1331669360, 
        "link": "http://4sq.com/xnRb5V", 
        "long_url": "http://foursquare.com/", 
        "modified_at": 1331669360, 
        "title": null, 
        "user_ts": 1331669360
      }, 
      {
        "aggregate_link": "http://nyti.ms/16tOHV", 
        "archived": false, 
        "client_id": "a5a2e024b030d6a594be866c7be57b5e2dff9972", 
        "created_at": 1331669349, 
        "link": "http://nyti.ms/xr5jgq", 
        "long_url": "http://nytimes.com/", 
        "modified_at": 1331669350, 
        "title": "The New York Times - Breaking News, World News & Multimedia", 
        "user_ts": 1331669349
      }, 
      {
        "aggregate_link": "http://bit.ly/2V6CFi", 
        "archived": false, 
        "client_id": "a5a2e024b030d6a594be866c7be57b5e2dff9972", 
        "created_at": 1331663117, 
        "link": "http://bit.ly/zhheQ9", 
        "long_url": "http://www.google.com/", 
        "modified_at": 1331663117, 
        "title": "Google", 
        "user_ts": 1331663117
      }
    ], 
    "result_count": 3
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

As part of the response, you will see a field output result_count, which tells you how many links are in your history. By default results are paginated, with the default page size being 50 results returned. You can add limit and offset parameters to the query to control the number of results returned, and which page of results to return. Full documentation for the endpoint is available at /v3/user/link_history.

Analytics

Google provides analytics that are all wrapped into a single call, including all-time totals of clicks on the specific short URL, clicks on the long URL, referrers counts, clicks by country, clicks by browser and platform, and most-recent clicks for the last month, week, day and last two hours. Bitly's API breaks these analytics out into different endpoints and combinations of calls.

Click counts

The primary endpoint you will need for retrieving click counts is /v3/link/clicks. By varying the query parameters you include, you can control the time period for which you want to retrieve clicks. The parameters you will need to use are unit, units, and unit_reference_ts.

The unit parameter controls the scope of the request, and can be month, week, day, hour, or minute. The parameter defaults to day.

The units parameter controls the number of units to count backwards, and must be a positive integer or -1. The default for units is -1, which means 'for all time'.

The unit_reference_ts parameter takes a Unix timestamp value, defaults to the current moment, and is the point in time from which the units parameter counts backwards.

These three units are a bit complicated, so they deserve a few examples to make things clear. For our first example, we want to know clicks for all time, so we use the defaults, day, -1 and now. We can omit the parameters entirely, since we are asking for default values: GET https://api-ssl.bitly.com/v3/link/clicks?access_token=XXXX&link=http%3A%2F%2Fbit.ly%2Fze6poY and we receive the following response:

{
  "data": {
    "link_clicks": 1292, 
    "tz_offset": -4, 
    "unit": "day", 
    "unit_reference_ts": null, 
    "units": -1
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

Next, we want to find the clicks from the month of July 2016. Our parameters will be month, 1 and for unit_reference_ts, we use a timestamp of 1470009599, which translates to 11:59:59pm, July 31, 2016 UTC. Our request looks like: GET https://api-ssl.bitly.com/v3/link/clicks?access_token=XXXX&link=http%3A%2F%2Fbit.ly%2Fze6poY&unit=month&units=1&unit_reference_ts=1470009599 and we receive the following response:

{
  "data": {
    "link_clicks": 32, 
    "tz_offset": -4, 
    "unit": "month", 
    "unit_reference_ts": 1470009599, 
    "units": 1
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

Next, we want to find the clicks per day for the month of July 2016. To achieve this, we need to introduce a new parameter, rollup, which takes values of either true (the default) or false. In this case, we will use false. Our request looks like: GET https://api-ssl.bitly.com/v3/link/clicks?access_token=XXXX&link=http%3A%2F%2Fbit.ly%2Fze6poY&unit=day&units=31&unit_reference_ts=1470009599&rollup=false and we receive the following response:

{
  "data": {
    "link_clicks": [
      {
        "clicks": 0, 
        "dt": 1469937600
      }, 
      {
        "clicks": 1, 
        "dt": 1469851200
      }, 
      {
        "clicks": 0, 
        "dt": 1469764800
      }, 
      {
        "clicks": 0, 
        "dt": 1469678400
      }, 
      {
        "clicks": 2, 
        "dt": 1469592000
      }, 
      {
        "clicks": 1, 
        "dt": 1469505600
      }, 
      {
        "clicks": 0, 
        "dt": 1469419200
      }, 
      {
        "clicks": 2, 
        "dt": 1469332800
      }, 
      {
        "clicks": 1, 
        "dt": 1469246400
      }, 
      {
        "clicks": 0, 
        "dt": 1469160000
      }, 
      {
        "clicks": 1, 
        "dt": 1469073600
      }, 
      {
        "clicks": 2, 
        "dt": 1468987200
      }, 
      {
        "clicks": 0, 
        "dt": 1468900800
      }, 
      {
        "clicks": 0, 
        "dt": 1468814400
      }, 
      {
        "clicks": 2, 
        "dt": 1468728000
      }, 
      {
        "clicks": 0, 
        "dt": 1468641600
      }, 
      {
        "clicks": 0, 
        "dt": 1468555200
      }, 
      {
        "clicks": 1, 
        "dt": 1468468800
      }, 
      {
        "clicks": 0, 
        "dt": 1468382400
      }, 
      {
        "clicks": 4, 
        "dt": 1468296000
      }, 
      {
        "clicks": 3, 
        "dt": 1468209600
      }, 
      {
        "clicks": 0, 
        "dt": 1468123200
      }, 
      {
        "clicks": 0, 
        "dt": 1468036800
      }, 
      {
        "clicks": 3, 
        "dt": 1467950400
      }, 
      {
        "clicks": 2, 
        "dt": 1467864000
      }, 
      {
        "clicks": 1, 
        "dt": 1467777600
      }, 
      {
        "clicks": 2, 
        "dt": 1467691200
      }, 
      {
        "clicks": 1, 
        "dt": 1467604800
      }, 
      {
        "clicks": 1, 
        "dt": 1467518400
      }, 
      {
        "clicks": 1, 
        "dt": 1467432000
      }, 
      {
        "clicks": 1, 
        "dt": 1467345600
      }
    ], 
    "tz_offset": -4, 
    "unit": "day", 
    "unit_reference_ts": 1470009599, 
    "units": 31
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

As you can see from the sample output, each day that has clicks is listed in the link_clicks array. By using the three parameters of unit, units and unit_reference_ts, you can retrieve click counts for any period of time.

Clicks per referrer

To retrieve clicks per referrer, your primary endpoint should be /v3/link/referring_domains. This endpoint will return click counts per referring domain. The endpoint, much like /v3/link/clicks, also takes unit, units and unit_reference_ts to establish the time period for which you want to retrieve data.

We also have two additional endpoints for referrer information, /v3/link/referrers and /v3/link/referrers_by_domain. The /v3/link/referrers endpoint will return specific referring web pages and their referring click counts, and /v3/link/referrers_by_domain groups the same data by domain. However, these endpoints have significantly lower rate limits than /v3/link/referring_domains, so if the information returned by /v3/link/referring_domains meets your needs, you are better off using that endpoint. You will be able to make more calls and retrieve more information.

Clicks per country

To retrieve clicks per country, you will call /v3/link/countries. This endpoint also takes unit, units and unit_reference_ts to specify the time period. The returned data consists of a list of two-letter country codes and the number of clicks per country.

Clicks by operating system or platform

Bitly does not currently offer API endpoints to retrieve clicks by operating system or platform. Instead, we offer that information as part of our data stream, an option we offer to our paid customers.