bitly API Best Practices
Please follow these guidelines when using the bitly API
bitly currently institutes 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.
Since bitly links 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).
API Key / OAuth Token Security
To ensure the security of your API key and/or OAuth access token, we strongly suggest that you make requests to the bitly API server-side whenever possible.
If you have any specific questions about API key and access token security, please don't hesitate to contact us at email@example.com.
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, please contact firstname.lastname@example.org.
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_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
http://bit.ly/undefined -- if you are seeing such links, please check the
status_txt values for errors.
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
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 rate limited batch requests can be resumed at the top of the hour. To inquire about a high-volume Bitly Enterprise license, please contact email@example.com.
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 http://www.w3schools.com/tags/ref_urlencode.asp.
For example, the link
http://betaworks.com/page?parameter=value#anchor should be fully escaped to
http%3A%2F%2Fbetaworks.com%2Fpage%3Fparameter%3Dvalue%23anchor. The link
http://betaworks.com/page%3Fparameter%3Dvalue%23anchor should be fully escaped to
A valid API call to shorten the link
http://betaworks.com/page?parameter=value#anchor would be:
Most languages include a function for URL encoding, including
urlib.quote() in Python,
urlencode() in PHP.