Links

/v3/expand

Given a bitly URL or hash (or multiple), returns the target (long) URL.

Authentication: oauth2 / api key

Parameters

  • shortUrl - refers to one or more bitly links. e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT.
  • hash - refers to one or more bitly hashes. e.g.: 2bYgqR or a-custom-name.

Note

  • Either shortUrl or hash must be given as a parameter.
  • The maximum number of shortUrl and hash parameters is 15.

Return Values

  • short_url - an echo back of the shortUrl request parameter.
  • hash - an echo back of the hash request parameter.
  • user_hash - the corresponding bitly user identifier.
  • global_hash - the corresponding bitly aggregate identifier.
  • error - indicates there was an error retrieving data for a given shortUrl or hash. An example error is "NOT_FOUND".
  • long_url - the URL that the requested short_url or hash points to.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/expand?access_token=ACCESS_TOKEN&shortUrl=http%3A%2F%2Fbit.ly%2Fze6poY

Example 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"
}

/v3/info

This is used to return the page title for a given bitly link.

Authentication: oauth2

Parameters

  • hash refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name ).
  • shortUrl refers to one or more bitly links e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT.
  • expand_user - optional true|false - include extra user info in response.

Return Values

  • short_url - this is an echo back of the shortUrl request parameter.
  • hash - this is an echo back of the hash request parameter.
  • user_hash - the corresponding bitly user identifier.
  • global_hash - the corresponding bitly aggregate identifier.
  • error - indicates there was an error retrieving data for a given shortUrl or hash. An example error is "NOT_FOUND".
  • title - the HTML page title for the destination page (when available).
  • created_by - the bitly username that originally shortened this link, if the link is public. Otherwise, null.
  • created_at - the epoch timestamp when this bitly link was created.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/info?access_token=ACCESS_TOKEN&shortUrl=http%3A%2F%2Fbit.ly%2F1RmnUT

Example Response

{
  "data": {
    "info": [
      {
        "created_at": 1212926400,
        "created_by": null,
        "global_hash": "1RmnUT",
        "short_url": "http://bit.ly/1RmnUT",
        "title": "Google",
        "user_hash": "1RmnUT"
      }
    ]
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/shorten

Given a long URL, returns a bitly short URL.

Authentication: oauth2 / api key

Parameters

  • longUrl - a long URL to be shortened (example: http://betaworks.com/).
  • domain - (optional) refers to a preferred domain; either bit.ly, j.mp, or bitly.com, for users who do NOT have a custom short domain set up with bitly. This affects the output value of url. The default for this parameter is the short domain selected by each user in his/her bitly account settings. Passing a specific domain via this parameter will override the default settings for users who do NOT have a custom short domain set up with bitly. For users who have implemented a custom short domain, bitly will always return short links according to the user's account-level preference.

Notes

  • Long URLs should be URL-encoded. You can not include a longUrl in the request that has &, ?, #, or other reserved parameters without first encoding it.
  • Long URLs should not contain spaces: any longUrl with spaces will be rejected. All spaces should be either percent encoded %20 or plus encoded +. Note that tabs, newlines and trailing spaces are all indications of errors. Please remember to strip leading and trailing whitespace from any user input before shortening.
  • Long URLs must have a slash between the domain and the path component. For example, http://example.com?query=parameter is invalid, and instead should be formatted as http://example.com/?query=parameter.
  • The default value for the domain parameter is selected by each user from within his/her bitly account settings at http://bitly.com/a/account.

Return Values

  • new_hash - designates if this is the first time this long_url was shortened by this user. The return value will equal 1 the first time a long_url is shortened. It will also then be added to the user history.
  • url - the actual link that should be used, and is a unique value for the given bitly account.
  • hash - a bitly identifier for long_url which is unique to the given account.
  • global_hash - a bitly identifier for long_url which can be used to track aggregate stats across all bitly links that point to the same long_url.
  • long_url - an echo back of the longUrl request parameter. This may not always be equal to the URL requested, as some URL normalization may occur (e.g., due to encoding differences, or case differences in the domain). This long_url will always be functionally identical the the request parameter.

When the output format is txt, the only response is the short url.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/shorten?access_token=ACCESS_TOKEN&longUrl=http%3A%2F%2Fgoogle.com%2F

Example 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"
}
© 2013 bitlyTM
handmade in nyc