bitly API Best Practices

Please follow these guidelines when using the bitly API

Rate Limiting

bitly currently institutes per-month, per-hour, per-minute, and per-IP rate limits for each API method, and limits API users to a maximum of five concurrent connections from a single IP address. Our default limits are more than sufficient for nearly all use cases. Please read through this documentation in its entirety to avoid common causes of rate limiting issues.

Caching

Since Bitlinks never change or expire, we ask that you cache data locally wherever possible.

Avoiding API Calls on Page Loads

Most rate limiting issues are caused by extraneous API calls. We ask that you avoid making calls to the bitly API on page loads, and instead make these calls based on explicit user actions (such as clicking a “share” button).

Authenticating End-Users With OAuth 2

If you are shortening URLs on behalf of end-users, we ask that you use our OAuth 2 implementation to authenticate end-users before shortening. URLs shortened in this manner will be added to the specified end-user’s history, allowing the end-user to manage and track his/her shortened URLs. To register an OAuth application, see the page on authentication.

OAuth Token / API Key Security

OAuth access tokens (and API keys) should be treated as secret data and not exposed to users. To ensure the security of your OAuth access token or API key, we strongly suggest that you make requests to the bitly API server-side whenever possible.

Any requests to the bitly API made via client-side JavaScript present the risk of your OAuth token or API key being compromised. It is possible to partially obfuscate the token or key, but anything sent to the browser can be read by a determined user. Most importantly, never include your api_key or access_token inline in the page. Keep any references to your api_key or access_token in code that is contained in external javascript files which are included in the page. For additional security, don't have the key or token itself contained anywhere in your javascript code, but rather make an ajax call to load it, and keep it in a variable stored in a privately scoped method. For an example of this implementation, please see our sample html and included javascript files.

If you have any specific questions about API key and access token security, please don't hesitate to contact us at api@bitly.com.

Custom Short Domains

When shortening a link with an access token for another user, we recommend that you do not set the domain parameter. With no domain parameter, the default is based on the user's preference.

Only specify the domain if the user has the opportunity to pick a valid domain from their domain_preference_options, accessible via the user info endpoint.

HTTP Response Status Codes

Please note that all valid responses in json and xml format will carry an HTTP Response Status Code of 200. This means that invalid, malformed or rate-limited json and xml requests may still return an HTTP response status code of 200. In json and xml responses, the status_code and status_txt values indicate whether a request is well formed and valid. For txt format calls, the HTTP Response Status Codes 403, 500 and 503 are used denote rate limiting, a problem with the request format, or an unknown error.

Checking for Errors

An invalid or rate limited request to the bitly API will not return a short URL. Please check all API responses for errors, and fallback to a long link. Invalid or rate limited API calls made via Javascript will often return http://bit.ly/undefined -- if you are seeing such links, please check the status_code and status_txt values for errors.

Batch Processing

The bitly API does not support shortening more than one long URL with a single API call. However, up to 15 URLs can be handled in one API call using the /v3/lookup, /v3/expand and /v3/clicks endpoints.

High-Volume Shorten Requests

If you need to shorten a large number of URLs at once, we recommend that you leave ample time to spread these requests out over many hours. Our API rate limits reset hourly and monthly. To inquire about high-volume use, please contact our sales team.

URL Encoding

All long URLs sent to the bitly API must be URL encoded, even if these links already contain escaped characters. For more information about URL encoding, see this Wikipedia article.

For example, the link

http://example.com/page?parameter=value#anchor

should be fully escaped to

http%3A%2F%2Fexample.com%2Fpage%3Fparameter%3Dvalue%23anchor

And the link

http://example.com/page%3Fparameter%3Dvalue%23anchor

should be fully escaped to

http%3A%2F%2Fexample.com%2Fpage%253Fparameter%253Dvalue%2523anchor

A valid API call to shorten the link http://example.com/page?parameter=value#anchor would be:

https://api-ssl.bitly.com/v3/shorten?access_token=e663e30818201d28dd07803e57333bed4f15803a&longUrl=http%3A%2F%2Fexample.com%2Fpage%3Fparameter%3Dvalue%23anchor&format=json

Most languages include a function for URL encoding, including urllib.quote() in Python, encodeURIComponent() in JavaScript, and urlencode() in PHP.