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) the short domain to use; either bit.ly, j.mp, or bitly.com or a custom short domain. The default for this parameter is the short domain selected by each user in their bitly account settings. Passing a specific domain via this parameter will override the default settings.

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.
  • The default value for the domain parameter is selected by each user from within their bitly account settings at https://bitly.com/a/settings/advanced.

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

/v3/user/save_custom_domain_keyword

Save a custom keyword for a custom short domain.

This endpoint is only available to paid customers.

Authentication: oauth2

Parameters

  • keyword_link - the short domain and keyword combination
  • target_link - the bitly short URL the specified keyword will map to
  • overwrite - Optional. true|false. Ovewrite existing entry if one exists. Default: false.

Return Values

  • keyword_link the specified link
  • target_link the bitly short URL the specified keyword will map to
  • aggregate_link the bitly aggregate link for the bitly short URL
  • is_new boolean indicating whether this keyword is new

Error Codes

  • INVALID_KEYWORD the keyword portion of keyword_link is invalid
  • INVALID_CNAME the cname portion of keyword_link is invalid
  • INVALID_LOGIN the authenticated user does not match the owner of the cname
  • WOULD_OVERWRITE setting this keyword_link would overwrite an existing keyword on this domain. Pass "overwrite=true" to override this error.