Name: QR Code and Barcode API: Generate and Read PNG or SVG
Brand: compasslab-1
SKU: api-compasslab-1-qr-barcode
Availability: InStock
Author: API Market

WPTOOLS

# QR Code and Barcode Generator and Reader API

## Overview

The QR Code and Barcode Generator and Reader API creates and decodes QR codes and the four common linear barcodes: EAN-13, UPC-A, Code 128 and Code 39. It has 4 endpoints. `/v1/qr` returns a QR code image for any text or URL, with control over size, quiet zone, colours and error correction level. `/v1/barcode` returns an EAN-13, UPC-A, Code 128 or Code 39 barcode, with the human-readable value printed under the bars if you want it. Both return the image file itself, as PNG or SVG. `/v1/codes/batch` generates up to 10 QR codes and barcodes in one call and returns each one base64-encoded in JSON, with its own `ok` flag so one bad item does not fail the batch. `/v1/codes/read` goes the other way: upload an image or pass a public image URL and it returns every code it finds, with the format, the decoded value, the four corner points and the rotation.

It is built for developers who print labels, tickets, invoices and packaging, teams that put links, payment or Wi-Fi QR codes on printed material, and product catalogue and inventory tools that need to read GTINs from supplier photos. For EAN-13 and UPC-A you can send the digits without the check digit and the API adds it, or send the full code and the API verifies it; a wrong check digit is a `400` error instead of a wrong barcode. Reads of EAN-13 and UPC-A codes also return `gtin13`, the 13-digit GTIN, so both formats map to the same catalogue key. Errors come back as JSON with a stable `error` code and a readable `detail`.

## Features

*   **4 endpoints**: Generate a QR code, generate a barcode, generate up to 10 codes in one batch, and read codes from an image.
*   **Formats supported**: QR, EAN-13, UPC-A, Code 128 and Code 39, for both generating and reading.
*   **PNG or SVG output**: SVG for print and scaling, PNG for screens. The single endpoints return the image file; the batch endpoint returns base64 in JSON.
*   **Styling controls**: QR scale (pixels per module), quiet zone, error correction level L, M, Q or H, and dark and light colours, including a transparent background. Barcodes take bar width and height in millimetres and an option to hide the printed text.
*   **Check digits handled**: Send 12 digits for EAN-13 or 11 for UPC-A and the check digit is added; send the full code and it is verified.
*   **Reading from images**: Upload a PNG, JPEG, WebP, GIF or BMP file up to 5 MB and 25 megapixels, or pass a public image URL. Several codes per image are returned, each with its corner positions and rotation in degrees.
*   **GTIN output**: EAN-13 and UPC-A reads include `gtin13`, the 13-digit GTIN.
*   **Rate limit**: 1 request per second on FREE, 5 on PRO, 10 on ULTRA and 20 on MEGA.

## Use Cases

*   **Labels and packaging**: Generate EAN-13 or UPC-A barcodes as SVG for product labels and print runs.
*   **Tickets and invoices**: Put a QR code with a booking reference or payment link on each ticket or invoice.
*   **Label sheets**: Generate up to 10 codes per call with the batch endpoint and lay them out on a sheet.
*   **Inventory and catalogues**: Read barcodes from supplier photos and match them to products by `gtin13`.
*   **Marketing material**: Create branded QR codes in your own colours that link to a landing page.
*   **Scan verification**: Read back a generated code to check that it decodes to the value you expect.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/compasslab-1/qr-barcode
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Generate a QR code

Returns a QR code image for any text or URL, as PNG or SVG. You control the size, the quiet zone, the colours and the error correction level. The response body is the image file (`image/png` or `image/svg+xml`), and the encoded value is echoed in the `X-Code-Value` response header.

**Method:** `GET`

**Endpoint:** `/v1/qr`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `data` | query | Text or URL to encode. | string | Yes | - | 2000 characters |
| `format` | query | Output format: `png` or `svg`. | string | No | `png` | - |
| `scale` | query | Pixels per module (minimum 1). | integer | No | `8` | 50 |
| `border` | query | Quiet zone around the code, in modules (minimum 0). | integer | No | `4` | 16 |
| `error` | query | Error correction level: `L` (7%), `M` (15%), `Q` (25%) or `H` (30%). | string | No | `M` | - |
| `dark` | query | Colour of the modules, as a hex colour. | string | No | `#000000` | - |
| `light` | query | Background colour, as a hex colour or `transparent`. | string | No | `#ffffff` | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/compasslab-1/qr-barcode/v1/qr?data=https%3A%2F%2Fapi.market&format=png" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -o qr.png
```

**Example Response (200 OK):** a PNG image (284 bytes in our test)

#### 2. Generate a barcode

Returns an EAN-13, UPC-A, Code 128 or Code 39 barcode as PNG or SVG. For EAN-13 send 12 digits and the check digit is added, or 13 digits and it is verified; UPC-A works the same way with 11 or 12 digits. A wrong check digit returns `400`. The response body is the image file.

**Method:** `GET`

**Endpoint:** `/v1/barcode`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `type` | query | Barcode type: `ean13`, `upca`, `code128` or `code39`. | string | Yes | - | - |
| `data` | query | Value to encode. EAN-13: 12 digits (check digit added) or 13 (verified). UPC-A: 11 digits (check digit added) or 12 (verified). | string | Yes | - | 80 characters |
| `format` | query | Output format: `png` or `svg`. | string | No | `png` | - |
| `module_width` | query | Width of the narrowest bar in millimetres (minimum 0.1). | number | No | `0.3` | 1 |
| `height` | query | Bar height in millimetres (minimum 5). | number | No | `15` | 50 |
| `show_text` | query | Print the human-readable value under the bars. | boolean | No | `true` | - |
| `dark` | query | Bar colour, as a hex colour. | string | No | `#000000` | - |
| `light` | query | Background colour, as a hex colour. | string | No | `#ffffff` | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/compasslab-1/qr-barcode/v1/barcode?type=ean13&data=5901234123457&format=png" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -o barcode.png
```

**Example Response (200 OK):** a PNG image (5377 bytes in our test)

#### 3. Generate codes in a batch

Generates 1 to 10 QR codes and barcodes in one call and returns each one base64-encoded in JSON. Each item is a QR item (`kind: "qr"`) or a barcode item (`kind: "barcode"`) and takes the same options as the single endpoints. Each result has its own `ok` flag, plus `error` and `detail` when it failed, so one invalid item never fails the batch. `value` is the encoded value, for example an EAN-13 with its check digit added.

**Method:** `POST`

**Endpoint:** `/v1/codes/batch`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `items` | body | List of codes to generate (minimum 1). | array | Yes | - | 10 items |
| `items[].kind` | body | `qr` or `barcode`. | string | Yes | - | - |
| `items[].data` | body | Value to encode. Up to 2000 characters for QR, 80 for barcodes. | string | Yes | - | 2000 characters |
| `items[].type` | body | Barcode type: `ean13`, `upca`, `code128` or `code39`. Required when `kind` is `barcode`. | string | No | - | - |
| `items[].format` | body | `png` or `svg`. | string | No | `png` | - |
| `items[].scale` | body | QR only: pixels per module. | integer | No | `8` | 50 |
| `items[].border` | body | QR only: quiet zone in modules. | integer | No | `4` | 16 |
| `items[].error` | body | QR only: error correction level `L`, `M`, `Q` or `H`. | string | No | `M` | - |
| `items[].module_width` | body | Barcode only: narrowest bar width in millimetres. | number | No | `0.3` | 1 |
| `items[].height` | body | Barcode only: bar height in millimetres. | number | No | `15` | 50 |
| `items[].show_text` | body | Barcode only: print the value under the bars. | boolean | No | `true` | - |
| `items[].dark` | body | Dark colour, as a hex colour. | string | No | `#000000` | 11 characters |
| `items[].light` | body | Light colour, as a hex colour (QR also accepts `transparent`). | string | No | `#ffffff` | 11 characters |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/compasslab-1/qr-barcode/v1/codes/batch" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"kind": "qr", "data": "https://api.market"}, {"kind": "barcode", "type": "code128", "data": "API-123"}]}'
```

**Example Response (200 OK) (abridged, second result omitted):**

```json
{
  "count": 2,
  "ok": 2,
  "results": [
    {
      "index": 0,
      "ok": true,
      "media_type": "image/png",
      "value": "https://api.market",
      "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAQgAAAEIAQAAAACLjVdSAAAA40lEQVR42u1ZywqEMBAL+///HKWdV4VF9rpJRZSaU5hJ0hF8WzDCCCOM+I7AXlz3vmLnXh+8rX9CoGnDeqLeYl+Sj10Zo2J6R5iPLhfzgaCBgxt1/SBQ/SKtH+kvtL88zHe57uHIovoxZSO1RFg/0GrKICRERLJf0l9QgQzK/RL1UM/JiGZ9REovb+l0JsoHylz6gywfSCryKIduGNm8HgeXLBHl+tgR9ZlOnU+POQh8fsl2oba/dF0c2gHPx8h2XO3z3DDb3IHnhUg1Ec8fc2zamkr7y8wj8vnD/+eMMMKIHxAXwQsuvsfd19gAAAAASUVORK5CYII=",
      "error": null,
      "detail": null
    }
  ]
}
```

#### 4. Read codes from an image

Finds and decodes every QR code and barcode in an image. Send the image as a multipart upload in `file`, or pass a public `image_url` instead. Each code comes back with its `type`, decoded `value`, the four corner points in `position`, its `orientation` (rotation in degrees) and, for EAN-13 and UPC-A, the 13-digit `gtin13`. In our test we uploaded the QR PNG returned by `/v1/qr` and it decoded back to `https://api.market`.

**Method:** `POST`

**Endpoint:** `/v1/codes/read`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `file` | form | Image file: PNG, JPEG, WebP, GIF or BMP. Send this or `image_url`. | file | No | - | 5 MB, 25 megapixels |
| `image_url` | form | Public image URL, instead of `file`. | string | No | - | 2048 characters |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/compasslab-1/qr-barcode/v1/codes/read" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -F "file=@qr.png"
```

**Example Response (200 OK):**

```json
{
  "count": 1,
  "codes": [
    {
      "type": "qr",
      "value": "https://api.market",
      "position": {
        "top_left": {
          "x": 32,
          "y": 32
        },
        "top_right": {
          "x": 232,
          "y": 32
        },
        "bottom_right": {
          "x": 232,
          "y": 232
        },
        "bottom_left": {
          "x": 32,
          "y": 232
        }
      },
      "orientation": 0,
      "gtin13": null
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded. The QR and barcode endpoints return the image file; batch and read return JSON. |
| 400 | Bad Request | The input is invalid, for example a wrong EAN-13 or UPC-A check digit. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path does not exist. Check the path against the list above. |
| 422 | Unprocessable Entity | A parameter is missing or out of range, for example `scale` above 50 or more than 10 batch items. The response says which one. |
| 429 | Too Many Requests | You went over your plan's requests-per-second limit, or the FREE plan's calls are used up. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Each plan has its own per-second limit: FREE allows 1 request per second, PRO 5, ULTRA 10 and MEGA 20. FREE includes 500 calls and is a hard limit, so requests after the 500th return `429 Too Many Requests`. PRO (10,000 calls), ULTRA (50,000 calls) and MEGA (200,000 calls) are soft limits, so calls above the included amount are billed as overage instead of being blocked. A batch call generates up to 10 codes in one request. Requests above the per-second limit also return `429`. Back off before retrying and honour any `Retry-After` header.

## FAQ

**Do I need to calculate the check digit?**

No. Send 12 digits for EAN-13 or 11 for UPC-A and the API adds the check digit. If you send the full 13 or 12 digits, it verifies the check digit and returns `400` when it is wrong, so you never get a barcode with a bad check digit.

**Why does my EAN-13 read back as UPC-A?**

An EAN-13 that starts with 0 is the same symbol as a UPC-A code. The `gtin13` field gives the same 13-digit value either way, so use it as your catalogue key.

**Should I use PNG or SVG?**

Use SVG for print and anything that is scaled, and PNG for screens. Set `format` on the request, or per item in a batch.

**How do I get the image when I use the batch endpoint?**

Each result has `data_base64` with the image and `media_type` (`image/png` or `image/svg+xml`). Decode the base64 string and save it with the matching extension.

**Which images can the reader handle?**

PNG, JPEG, WebP, GIF and BMP files up to 5 MB and 25 megapixels, uploaded as `file` or fetched from a public `image_url`. It reads QR, EAN-13, UPC-A, Code 128 and Code 39, several codes per image, and reports each code's rotation in `orientation`.

**How reliable is reading?**

The seller reports that in its own tests 50 of 50 generated codes (QR, EAN-13, UPC-A, Code 128 and Code 39) read back exactly, 10 of 10 photo-like test images were read, and reading took about 70 ms. In our test a QR code generated by `/v1/qr` decoded back to the original URL.

**What error correction level should I choose for QR codes?**

`M` (15%) is the default and suits most uses. Choose `Q` or `H` if the code may be damaged, printed small or printed on a rough surface; higher levels make the code denser.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


QR code and barcode API: generate QR, EAN-13, UPC-A, Code 128 and Code 39 as PNG or SVG, batch up to 10, and read codes from images with their positions.

QR Code and Barcode API: Generate and Read PNG or SVG

FREE