CORS or Cross Origin Resource Sharing

The Blockchain API supports CORS, or Cross Origin Resource Sharing.

Historically, Javascript AJAX requests were restricted to a same domain origin policy. This meant that your website at could not make AJAX requests to, since they were not the same domain.

With the introduction of HTML5 and advancements in modern browsers, CORS allows website owners to control who can access data via Javascript AJAX requests. In this way, CORS functions like Flash's Cross Domain Origin Policy. The latest version of the Bitly API (V3) supports CORS requests from any domain.

Here is some basic example Javascript to get you started:

var xhr = new XMLHttpRequest();"GET", "");
xhr.onreadystatechange = function() { 
    if(xhr.readyState == 4) { 
        if(xhr.status==200) {
            console.log("CORS works!", xhr.responseText);         
        } else {
            console.log("Oops", xhr);

You can also read more about CORS here.

Request / Response Formats

All Blockchain APIs support an optional return format parameter format=json. Note that json is the default response format. but xml is also available. Some endpoints also support a simple txt format.

All Blockchain APIs support jsonp which is the json format with a callback specified, such as:

  • All API requests should be against the domain (see examples).

  • HTTP Response Status Code is 200 on all valid response in json and xml formats. 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 are used to indicate a problem with the request, rate limiting, or other errors. The response body will be equivalent to status_txt in json and xml calls for all non 200 response codes.

  • The status_code is 200 for a successful request, 403 when rate limited, 503 for temporary unavailability, 404 to indicate not-found responses, and 400 for all other invalid requests or responses.

  • status_txt will be a value that describes the nature of any error encountered. Common values are RATE_LIMIT_EXCEEDED, MISSING_ARG_%s to denote a missing URL parameter, and INVALID_%s to denote an invalid value in a request parameter (where %s is substituted with the name of the request parameter).

  • If the status_code is not 200, only status_code and status_txt are guaranteed to be present and valid.

Example Outputs:

  • json { "status_code": 200, "status_txt": "OK", "data" : ... }
  • json { "status_code": 400, "status_txt": "MISSING_ARG_LOGIN", "data" : null }
  • json { "status_code": 403, "status_txt": "RATE_LIMIT_EXCEEDED", "data" : null }
  • json { "status_code": 500, "status_txt": "UNKNOWN ERROR", "data" : null }
  • json { "status_code": 503, "status_txt": "TEMPORARILY_UNAVAILABLE", "data" : null }
  • jsonp callback_method({ "status_code": 200, "status_txt": "OK", "data" : ... })
  • xml

    <?xml version="1.0" encoding="UTF-8"?>