# Replace the goQR.me QR code API (Developers)

URL: https://qrdx.dev/docs/developers/goqr-api
Source: https://github.com/qrdxinc/qrdx/blob/main/apps/docs/content/docs/developers/goqr-api.mdx

Map the size, ecc, color and qzone parameters of api.qrserver.com to the free QRdx image API, and rewrite every old URL in your files with one command.

By the end of this page, every QR code your pages, emails or templates load from goQR.me's `api.qrserver.com/v1/create-qr-code/` loads from the QRdx [image API](https://qrdx.dev/docs/developers/image-api) instead, at the same size and error correction level, with no account or key.

Both APIs work the same way: a `GET` URL that returns the image. `data` keeps its name, so the change is a new host, four renamed parameters and three defaults. The goQR.me parameters on this page come from its [create-qr-code documentation](https://goqr.me/api/doc/create-qr-code/), checked on November 17, 2026.

## Before you start [#before-you-start]

- Find the files that use the old API:

```bash title="Terminal"
grep -rl "api\.qrserver\.com/v1/create-qr-code" .
```

- Work in a git checkout or another place where you can review the change before it goes live.

## 1. Compare one URL [#1-compare-one-url]

The two URLs below ask for the same code: a 200 × 200 PNG of `https://example.com` at error correction `M` with a 2-module quiet zone.

```txt title="Before and after"
https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=https%3A%2F%2Fexample.com&ecc=M&qzone=2
https://api.qrdx.dev/v1/qr?format=png&size=200&data=https%3A%2F%2Fexample.com&level=M&margin=2
```

```bash title="Terminal"
curl -o after.png "https://api.qrdx.dev/v1/qr?format=png&size=200&data=https%3A%2F%2Fexample.com&level=M&margin=2"
file after.png
# after.png: PNG image data, 200 x 200, 8-bit/color RGBA, non-interlaced
```

## 2. Map the parameters [#2-map-the-parameters]

| goQR.me | QRdx | Notes |
| --- | --- | --- |
| `data=<data>` | `data=<data>` | The same name, URL-encoded the same way, up to 2,048 characters. QRdx reads it as UTF-8 |
| `size=<width>x<height>` | `size=<width>` | One number, because QR codes are square: `64` to `2048` pixels |
| `ecc=<level>` | `level=<level>` | The same letters, `L`, `M`, `Q` and `H` |
| `color=<color>` | `fg=<hex>` | Hex only, such as `ff0000` or `f00`. Write a decimal color such as `255-0-0` as `ff0000` |
| `bgcolor=<color>` | `bg=<hex>` | Hex only, as for `fg`. `00000000` gives a transparent background |
| `qzone=<modules>` | `margin=<modules>` | Both count modules. QRdx takes `0` to `16` |
| `margin=<pixels>` | none | QRdx has no margin in pixels: its `margin` is the quiet zone, in modules. Leave goQR.me's out |
| `format=png`, `svg` or `eps` | the same | QRdx has no `gif`, `jpeg` or `jpg`: use `png`, or `webp` for a smaller file |
| `charset-source`, `charset-target` | not needed | QRdx always encodes text as UTF-8, which is goQR.me's default too. Left in, they're ignored. If you sent ISO-8859-1 data, send it as UTF-8 instead |
| `GET` or `POST` | `GET` only | A `POST` to the image API returns `405` |

Three defaults differ, and the rewrite below sets each one so the codes look as they did:

- **Format:** goQR.me returns PNG. QRdx returns SVG unless you ask for `png`, `webp` or `eps`. Keep PNG for email, since many email clients don't show SVG.
- **Size:** goQR.me draws `200x200`, QRdx `512`.
- **Error correction:** goQR.me uses `L`. QRdx uses `Q`, which survives more damage but makes a denser code. Drop the added `level=L` if you'd rather have QRdx's default.

The quiet zone differs too, and the rewrite leaves it to you. Without `qzone`, goQR.me draws no quiet zone, only a 1-pixel margin. QRdx draws a 4-module quiet zone, the size the QR standard recommends, so the code itself is smaller inside the same image. To make it fill more of the image, add `margin=1`, the smallest quiet zone goQR.me's documentation recommends.

## 3. Rewrite the URLs in your files [#3-rewrite-the-urls-in-your-files]

This rewrites every goQR.me URL in the files you name. It changes the host and path, renames `size`, `ecc`, `color`, `bgcolor` and `qzone`, turns decimal colors into hex, drops the pixel `margin`, swaps GIF and JPEG for PNG, and adds `format=png`, `size=200` and `level=L` where a URL relied on goQR.me's defaults. Perl comes with macOS and most Linux distributions.

```bash title="Terminal"
perl -pi -e 's{https?://api\.qrserver\.com/v1/create-qr-code/?\?([^\s"\x27<>)]*)}{my $q = $1; $q =~ s/(^|&amp;|[&;])margin=\d*(?=[&;]|$)//; $q =~ s/^(?:&amp;|&)//; $q =~ s/(^|[&;])qzone=/${1}margin=/; $q =~ s/(^|[&;])size=(\d+)x\d+/${1}size=$2/; $q =~ s/(^|[&;])ecc=/${1}level=/; $q =~ s/(^|[&;])((?:bg)?color)=(\d+)-(\d+)-(\d+)/sprintf("%s%s=%02x%02x%02x", $1, $2, $3, $4, $5)/ge; $q =~ s/(^|[&;])color=/${1}fg=/; $q =~ s/(^|[&;])bgcolor=/${1}bg=/; $q =~ s/(^|[&;])format=(?:gif|jpe?g)/${1}format=png/; my $p = ""; $p .= "format=png&" unless $q =~ /(^|[&;])format=/; $p .= "size=200&" unless $q =~ /(^|[&;])size=/; $p .= "level=L&" unless $q =~ /(^|[&;])level=/; "https://api.qrdx.dev/v1/qr?$p$q"}ge' index.html
```

Run on a file with four old tags:

```html title="index.html (before)"
<img src="https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=https%3A%2F%2Fexample.com" alt="QR">
<img src="https://api.qrserver.com/v1/create-qr-code/?data=HelloWorld&amp;size=100x100" alt="QR 2">
<img src="http://api.qrserver.com/v1/create-qr-code/?data=https%3A%2F%2Fexample.com%2Fmenu&size=300x300&ecc=M&color=255-0-0&bgcolor=fff&qzone=2&margin=10&format=gif" alt="QR 3">
<img src="https://api.qrserver.com/v1/create-qr-code/?margin=5&data=hello&charset-source=UTF-8&format=svg" alt="QR 4">
```

it produces:

```html title="index.html (after)"
<img src="https://api.qrdx.dev/v1/qr?format=png&level=L&size=150&data=https%3A%2F%2Fexample.com" alt="QR">
<img src="https://api.qrdx.dev/v1/qr?format=png&level=L&data=HelloWorld&amp;size=100" alt="QR 2">
<img src="https://api.qrdx.dev/v1/qr?data=https%3A%2F%2Fexample.com%2Fmenu&size=300&level=M&fg=ff0000&bg=fff&margin=2&format=png" alt="QR 3">
<img src="https://api.qrdx.dev/v1/qr?size=200&level=L&data=hello&charset-source=UTF-8&format=svg" alt="QR 4">
```

QRdx ignores the leftover `charset-source`; remove it by hand if you want tidy URLs.

The command changes URLs written out in one piece. Where code adds parameters after a variable, as in `'?data=' . $text . '&size=120x120'`, the part after the variable keeps its old names. This lists what may be left, along with any other URL that uses those names; fix the QR ones by hand, then run it again:

```bash title="Terminal"
grep -rnE "api\.qrserver\.com|[?&;](size=[0-9]+x[0-9]+|ecc=|bgcolor=|color=|qzone=)" .
```

## 4. Change the code that builds URLs [#4-change-the-code-that-builds-urls]

```php title="qr.php"
// Before
$src = 'https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=' . rawurlencode($link);

// After
$src = 'https://api.qrdx.dev/v1/qr?format=png&size=200&level=L&data=' . rawurlencode($link);
```

```js title="qr.js"
// Before
const src = `https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=${encodeURIComponent(link)}`;

// After
const src = `https://api.qrdx.dev/v1/qr?format=png&size=200&level=L&data=${encodeURIComponent(link)}`;
```

In Google Sheets:

```txt title="Sheets formula"
=IMAGE("https://api.qrdx.dev/v1/qr?format=png&size=150&level=L&data="&ENCODEURL(A2))
```

Sheets loads images through Google's own servers, so a sheet with hundreds of codes can run into the per-IP limit below. For a long list, make the files once with the [bulk generator](https://qrdx.dev/tools/bulk) or the [CLI](https://qrdx.dev/docs/developers/cli)'s `qrdx batch`.

## If something goes wrong [#if-something-goes-wrong]

### `400` with `"param": "size"` [#400-with-param-size]

A size under 64 pixels (such as `50x50`) or over 2048 is refused. Change those sizes by hand; `64` is the smallest the image API draws.

```json title="400 Bad Request"
{"code":"VALIDATION_ERROR","message":"Invalid query parameters","data":{"details":[{"param":"size","message":"Too small: expected number to be >=64"}]},"status":400}
```

### `400` with `"param": "fg"` or `"bg"` [#400-with-param-fg-or-bg]

A color the rewrite didn't reach, such as one built in code, is still in decimal. Write it as hex: `255-0-0` is `ff0000`.

```json title="400 Bad Request"
{"code":"VALIDATION_ERROR","message":"Invalid query parameters","data":{"details":[{"param":"fg","message":"Must be a hex color such as 155dfc (in URLs leave out the # or encode it as %23)"}]},"status":400}
```

### `400` with `"param": "format"` or `"param": "margin"` [#400-with-param-format-or-param-margin]

A `gif`, `jpeg` or `jpg` format, or a `qzone` over 16, came from code the rewrite didn't reach. Use `png`, and a `margin` of `16` or less.

### `429` after a bulk reload [#429-after-a-bulk-reload]

The image API allows 300 requests a minute per IP address. Wait the seconds in the `Retry-After` header, or generate the files once instead of loading them live.

## What else to know [#what-else-to-know]

- **Caching:** the same URL always returns the same bytes, so responses are cached for a year (`Cache-Control: public, max-age=31536000, immutable`).
- **More options:** module and eye shapes, eye colors, a logo icon (`logoIcon`) and frames. Try them in the [URL builder](https://qrdx.dev/qr-code-api), or read the [parameters](https://qrdx.dev/docs/developers/image-api#parameters).
- **Self-hosting:** a [self-hosted](https://qrdx.dev/docs/self-hosting) QRdx serves the same API at `/api/v1/qr` on your own domain.

## Related [#related]

- [QR code image API](https://qrdx.dev/docs/developers/image-api): every parameter, styles, logos and limits
- [Replace the Google Chart QR code API](https://qrdx.dev/docs/developers/google-chart-api): the same move from `chart.googleapis.com`
- [CLI](https://qrdx.dev/docs/developers/cli): make the files once, including a whole CSV
- [Render a QR code image](https://qrdx.dev/docs/developers/api/get-qr-image): the reference page with a Try it panel
