QR code API: command “read-qr-code” (read / scan QR code, QR code reader)

Table of contents

1.0 General notes

On this page, you can find the instructions of the read-qr-code command which belongs to our QR code API ("Application Programming Interface"). You can use it to read out the content provided by QR code images / symbols.

You may also start to embed in into your application, e.g. an QR code scanner.

1.1 Terms of Service

See Terms of Service: QR code API

Additional notes: There is no request limit, but we reserve the right to reject API requests. This applies especially to requests we consider abusive or inappropriate (i.e. if it seems to be a DoS attack). We therefore record the origin of all requests (referrer and IP address), but not the contents of the QR codes (see the notes on our privacy policy for more information). To make our work easier, please let us know, if your service will regularly cause more than 10 000 requests a day or if your service is blocked wrongly.

2.0 Quick start guide

Send a GET request of following form to our system to decode a QR code graphic (=to read a QR code from the web):
http(s)://api.qrserver.com/v1/read-qr-code/?fileurl=[URL-encoded-webaddress-url-to-qrcode-image-file]

Test it directly within your browser by requesting the following URL to read the QR code at http://api.qrserver.com/v1/create-qr-code/?data=HelloWorld auszulesen:

http://api.qrserver.com/v1/read-qr-code/?fileurl=http%3A%2F%2Fapi.qrserver.com%2Fv1%2Fcreate-qr-code%2F%3Fdata%3DHelloWorld

3.0 Parameters

The command supports a wide range of parameters to configure the QR code decoding / the reading process. Simply use extra parameters by adding &[parameter-name]=[parameter-wert] to your request.

All parameters can be submitted by HTTP-GET or HTTP-POST (with the exception of the POST-only parameter file). You can mix both methods, too. If a parameter was submitted with POST and GET at the same time, the GET value will be used and the POST value will be ignored.

3.1 fileurl parameter

Address (URL) of a image file accessible via Internet, containing the QR code to read (e.g. a photo).

  • Format:
    [URL]. The adress has to be URL encoded, PHP programmers may use urlencode(). Additionally, the file has to be reachable for our servers via Internet and it has to be a PNG, GIF or JP(E)G image which is smaller than 1 MiB. Use HTTP instead of HTTPS URLs as long as this is suitable from a security perspective. This accelerates the whole process and prevents download errors in consequence of sever-side certificate errors.
  • Valid examples:
    http%3A%2F%2Fapi.qrserver.com%2Fv1%2Fcreate-qr-code%2F%3Fdata%3DHelloWorld
    (URL encoded, equates to http://api.qrserver.com/v1/create-qr-code/?data=HelloWorld in clear text)
  • Invalid examples:
    www.example.com/qrcode.png (invalid QR code URL, protocol declaration like http:// is missing)

3.2 file parameter

An image file (e.g. a photo), which contains the QR code to read, as direct upload for the API (only possible by using a HTTP POST request). Please note that the file parameter will be ignored if fileurl is given. So you cannot decode an external fileby by using fileurl and upload an image with file to our servers at the same time.

  • Format:
    The image file data to read (Content-Type: multipart/form-data). The file has to be a PNG, GIF or JP(E)G image which is smaller than 1 MiB..
  • Example of a QR code upload form:
    <html>
    <form enctype="multipart/form-data" action="http://api.qrserver.com/v1/read-qr-code/" method="POST">
    <!-- MAX_FILE_SIZE (maximum file size in bytes) must precede the file input field used to upload the QR code image -->
    <input type="hidden" name="MAX_FILE_SIZE" value="1048576" />
    <!-- The "name" of the input field has to be "file" as it is the name of the POST parameter -->
    Choose QR code image to read/scan: <input name="file" type="file" />
    <input type="submit" value="Read QR code" />
    </form>
    </html>

3.3 outputformat parameter

The format to use to present the read-out QR code data or error message. Please note that only the first found QR code will be scanned if an image file provided more than one QR code at the same time. This is also the case if they are belong together by using the “Structured Append” feature. Coming QR code API version may support scanning multiple QR codes in one image (incl. “Structured Append”). The JSON and XML response is already prepared for this.

  • Possible values:
    json
    xml
  • Invalid examples:
    JSON (wrong notation, everything uppercase instead of lowercase)
    Xml (wrong notation, first char is uppercase instead of lowercase)
  • Default (will be used if no or invalid value is set):
    json
  • Answer if the QR code was read successfully:
    • XML format:
      <?xml version="1.0" encoding="UTF-8"?>
      <barcodes>
      <barcode type="qrcode">
         <symbol seq="0">
             <data><![CDATA[Content of the read QR code]]></data>
             <error />
         </symbol>
      </barcode>
      </barcodes>
    • JSON format:
      [
      {
         "type": "qrcode",
         "symbol": [
             {
                 "seq": 0,
                 "data": "Content of the read QR code",
                 "error": null
             }
         ]
      }
      ]
  • Answer if the QR code reading attempt failed:
    • XML format:
      <?xml version="1.0" encoding="UTF-8"?>
      <barcodes>
      <barcode type="qrcode">
         <symbol seq="0">
             <data />
             <error>error description, e.g. "download error (could not establish connection)"</symbol>
         </symbol>
      </barcode>
      </barcodes>
    • JSON format:
      [
      {
         "type": "qrcode",
         "symbol": [
             {
                 "seq": 0,
                 "data": null,
                 "error": "error description, e.g. \"download error (could not establish connection)\""
             }
         ]
      }
      ]