QR code API: command “create-qr-code” (generate QR code, QR code generator)

Table of contents

1.0 General notes

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

You may also start to embed in into your own web application, e.g. an QR code generator. Our page goQR.me is also using this API.

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 get a QR code graphic as PNG image (=to generate a QR code):
http(s)://api.qrserver.com/v1/create-qr-code/?data=[URL-encoded-text]&size=[pixels]x[pixels]

Test it directly within your browser by requesting the following URL:
http://api.qrserver.com/v1/create-qr-code/?data=HelloWorld!&size=100x100

As you can see, it's easy to embed a QR code in your (X)HTML documents by using the <img> tag. The <img> tag
<img src="https://api.qrserver.com/v1/create-qr-code/?data=HelloWorld&amp;size=100x100" alt="" title="" />
produces / shows the following QR code image:

To avoid problems with special characters, it is advisable to submitted the charset your data is encoded with via the charset-source parameter.

3.0 Parameters

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

All parameters can be submitted by HTTP-GET or HTTP-POST. 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 data parameter (mandatory)

The text to store within the QR code (URL encoded, PHP programmers may use urlencode()).

  • Minimal charcount:
    1
  • Maximal charcount:
    Depends on the ecc parameter (the more data redundancy is used, the less characters fit in your QR code) and from other factors, which are too complicated to describe here in a short way. Nevertheless up to 900 characters should work in general.
  • Best practice:
    The shorter the better. Since many older cell phones have problems with QR codes >Version 4 (that means a matrix with 33×33 modules), you should use as little data as possible. We suggest using URL shorteners like bitly for very long URLs. However, industrial scanners should have no problems regarding complex QR codes.

3.2 size parameter (optional)

Specifies the size of the QR code image you want to generate (in px for raster graphic formats like png, gif or jpeg); as logical unit for vector graphics (svg, eps).

  • Format:
    [integer]x[integer]
  • Minimum value:
    10x10
  • Maximal value:
    1000x1000 (if format=png|gif|jpeg|jpg),
    1000000x1000000 (if format=svg|eps)
  • Valid examples:
    50x50
    750x750
  • Invalid examples:
    50x60 (unequal edge length)
    90000x90000 (greater than maximal scale)
    9x9 (smaller than minimal scale)
  • Default (will be used if no or invalid value is set):
    200x200

3.3 charset-source parameter (optional)

Specifies the charset the text submitted via data parameter is encoded in. Note: you don't have to care about converting your data if charset-source and charset-target got different values, the API does all the needed work automatically.

  • Possible values:
    ISO-8859-1
    UTF-8
  • Invalid examples:
    utf-8 (wrong notation, everything lowercase instead of uppercase)
    iso-8859-1 (wrong notation, everything lowercase instead of uppercase)
  • Default (will be used if no or invalid value is set):
    UTF-8

3.4 charset-target parameter (optional)

Specifies the charset to encode the text submitted via data parameter with, before storing it within the QR code. Note: you don't have to care about converting your data if charset-source and charset-target got different values, the API does all the needed work automatically.

  • Possible values:
    ISO-8859-1
    UTF-8
  • Invalid examples:
    utf-8 (wrong notation, everything lowercase instead of uppercase)
    iso-8859-1 (wrong notation, everything lowercase instead of uppercase)
  • Default (will be used if no or invalid value is set):
    UTF-8
  • Best practice:
    Unfortunately, the QR code specification does not provide a place to store the used charset within a QR code. This means that QR code readers have to take a guess, or always assume a certain charset. Some older software even just ignores non ASCII characters, but we usually had no problems with ISO-8859-1 regarding legacy readers. In common (=if support for very old devices is not needed or you want to store special characters), you should use UTF-8 here. If you want to be on the safe side in every case, you should use only the following characters (=ASCII):
    !"#$%&'()*+,-./0123456789:;<=>?
    @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
    `abcdefghijklmnopqrstuvwxyz{|}~

3.5 ecc parameter (optional)

Defines the error correction code (ECC) which determines the degree of data redundancy. The more data redundancy exists, the more data can be restored if a QR code is damaged (i.e. scratches on a QR code sticker or something like that).

  • Possible values:
    L (low, ~7% destroyed data may be corrected)
    M (middle, ~15% destroyed data may be corrected)
    Q (quality, ~25% destroyed data may be corrected)
    H (high, ~30% destroyed data may be corrected)
  • Default (will be used if no or invalid value is set):
    L
  • Best practice:
    L. A higher ECC results in more data to save and thus leads to a QR code with more data pixels and a larger data matrix. Because many cell phone readers have problems with QR codes >Version 4 (that means a matrix of 33×33 modules), the lowest ECC is the best choice for common purpose – legacy QR code readers are a more common problem than destroyed QR codes.

3.6 color parameter (optional)

Color of the data modules as RGB value.

  • Format:
    Decimal ([0-255]-[0-255]-[0-255]) or hex value in short format ([a-fA-F] three chars, e.g. fff for white) or long format ([a-fA-F] six chars, e.g. ff0000 for red).
  • Valid examples:
    255-0-0 (red),
    f00 (red),
    FF0000 (red),
    0-255-0 (green),
    0f0 (green),
    00ff00 (green),
    0-0-255 (blue),
    00f (blue),
    0000ff (blue),
    556B2F (DarkOliveGreen)
  • Invalid examples:
    300-100-0 (RGB decimal value >255),
    GG00AA (“G” is no valid char),
    ffaab (hex value neither in short nor long format (3 respectively 6 letters)),
    255-0 (decimal B value is missing, only R and G value given)
  • Default (will be used if no or invalid value is set):
    0-0-0 (=black)
  • Best practice:
    0-0-0 (black). Otherwise a much darker color than the color of the background to get a good contrast. A helpful color may be found by looking for the so called web colors.

3.7 bgcolor parameter (optional)

Color of the background as RGB value.

  • Format:
    Decimal ([0-255]-[0-255]-[0-255]) or hex value in short format ([a-fA-F] three chars, e.g. fff for white) or long format ([a-fA-F] six chars, e.g. ff0000 for red).
  • Valid examples:
    255-0-0 (red),
    f00 (red),
    FF0000 (red),
    0-255-0 (green),
    0f0 (green),
    00ff00 (green),
    0-0-255 (blue),
    00f (blue),
    0000ff (blue),
    556B2F (DarkOliveGreen)
  • Invalid examples:
    300-100-0 (RGB decimal value >255),
    GG00AA (“G” is no valid char),
    ffaab (hex value neither in short nor long format (3 respectively 6 letters)),
    255-0 (decimal B value is missing, only R and G value given)
  • Default (will be used if no or invalid value is set):
    0-0-0 (=schwarz)
  • Best practice:
    255-255-255 (white). Otherwise a much brighter color than the color of the data modules to get a good contrast. A helpful color may be found by looking for the so called web colors.

3.8 margin parameter (optional)

Thickness of a margin in pixels. The margin will always have the same color as the background (you can configure this via bgcolor). It will not be added to the width of the image set by size, therefore it has to be smaller than at least one third of the size value. The margin will be drawn in addition to an eventually set qzone value. The margin parameter will be ignored if svg or eps is used as QR code format (=if the QR code output is a vector graphic).

  • Format:
    [integer]
  • Minimum value:
    0 (=no pixel based margin)
  • Maximum value:
    50
  • Valid examples:
    1
    19
  • Invalid examples:
    -1 (less than minimum value)
    1200 (more than maximum value)
    a (not a numer)
  • Default (will be used if no or invalid value is set):
    1

3.9 qzone parameter (optional)

Thickness of a margin (=“quiet zone”, an area without disturbing elements to help readers locating the QR code), in modules as measuring unit. This means a value of 1 leads to a drawn margin around the QR code which is as thick as a data pixel/module of the QR code. The quiet zone will always have the same color as the background (you can configure this via bgcolor). The quiet zone will be drawn in addition to an eventually set margin value.

  • Format:
    [integer]
  • Minimum value:
    0 (=no “quiet zone”)
  • Maximum value:
    100
  • Valid examples:
    1
    19
  • Invalid examples:
    -1 (less than minimum value)
    1200 (more than maximum value)
    a (not a numer)
  • Default (will be used if no or invalid value is set):
    0 (=no “quiet zone”)
  • Best practice:
    An at least 1 module wide quiet zone is required for optimal scanning results. The QR code standard recommendes a “quiet zone” of 4.

3.10 format parameter (optional)

It is possible to create the QR code picture using different file formats, available are PNG, GIF, JPEG and the vector graphic formats SVG and EPS (=you can create QR code vector graphics / QR code EPS / QR code SVG as needed for professional printing).

  • Possible values:
    png
    gif
    jpeg
    jpg
    svg
    eps
  • Invalid examples:
    GIF (wrong notation, everything uppercase instead of lowercase)
    Png (wrong notation, first char is uppercase instead of lowercase)
  • Default (will be used if no or invalid value is set):
    png
  • Best practice:
    For websites: png oder gif. JPEG was developed for natural pictures, its results are worse than GIF/PNG for line drawings and comparable contents.
    For professional print usage: svg oder eps because vector-based graphics can be scaled by any amount without degrading quality.