Decode Barcode

GET /v1/barcode/decode and POST /v1/barcode/decode take an image and return every barcode or QR symbol the decoder can find in it. Both routes fan out to the same decoder, so a 1D endpoint will happily return QR codes and vice versa — the split is organisational, not functional.

Method Endpoint Input Typical use
GET /v1/barcode/decode Image URL (query param) Server-side fetch of an already-hosted scan/photo
POST /v1/barcode/decode Base64 image or url Uploads from a camera, mobile app, or browser <input type="file">
GET /v1/qr/decode Image URL Same decoder, QR-tagged route
POST /v1/qr/decode Base64 image or url Same decoder, QR-tagged route

Base URL

https://barcode.toolkitapi.io

Authentication is via the X-API-Key header (or Authorization: Bearer).


GET /v1/barcode/decode

Parameters

Field Type Required Constraints Description
url string yes ≤ 2048 chars Publicly reachable URL of an image containing barcode(s)

The URL is fetched with a 15-second timeout and a 10 MB response cap, and is validated against SSRF rules before any request is made — private ranges, loopback, and link-local addresses are rejected.

Example — decode from a hosted image

curl -G "https://barcode.toolkitapi.io/v1/barcode/decode" \
  --data-urlencode "url=https://example.com/labels/shelf-42.png" \
  -H "X-API-Key: YOUR_KEY"
import requests

resp = requests.get(
    "https://barcode.toolkitapi.io/v1/barcode/decode",
    headers={"X-API-Key": "YOUR_KEY"},
    params={"url": "https://example.com/labels/shelf-42.png"},
    timeout=60,
)
resp.raise_for_status()

for symbol in resp.json()["results"]:
    print(symbol["type"], "→", symbol["data"], f"({symbol['quality']})")
const url = new URL("https://barcode.toolkitapi.io/v1/barcode/decode");
url.search = new URLSearchParams({ url: "https://example.com/labels/shelf-42.png" });

const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
const { found, results } = await resp.json();

for (const s of results) {
  console.log(`${s.type} → ${s.data} (${s.quality})`);
}

POST /v1/barcode/decode

Request body

Provide exactly one of image or url — supplying both, or neither, is a validation error.

Field Type Required Constraints Description
image string one-of ≤ 10 MB decoded Base64-encoded image (raw base64, no data: prefix)
url string one-of ≤ 2048 chars URL of an image to fetch server-side

Example — decode an uploaded photo

# Encode a local file, then decode it
B64=$(base64 -w0 receipt.png)
curl -X POST "https://barcode.toolkitapi.io/v1/barcode/decode" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"image\": \"$B64\"}"
import base64
import requests

with open("receipt.png", "rb") as fh:
    b64 = base64.b64encode(fh.read()).decode()

resp = requests.post(
    "https://barcode.toolkitapi.io/v1/barcode/decode",
    headers={"X-API-Key": "YOUR_KEY", "Content-Type": "application/json"},
    json={"image": b64},
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["found"], "symbol(s)")
// Browser: read a <input type="file"> and decode in one call
async function decodeFile(file) {
  const b64 = await new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(String(reader.result).split(",")[1]);
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });

  const resp = await fetch("https://barcode.toolkitapi.io/v1/barcode/decode", {
    method: "POST",
    headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ image: b64 }),
  });
  return resp.json(); // { found, results: [...] }
}

Never expose your API key in browser code

The fetch above is illustrative. In production, post the file to your own backend and let it call the API — the site's demo blueprint implements exactly that proxy pattern.


Response

Field Type Description
found integer Number of symbols decoded (may be 0)
results array One entry per symbol, in decoder order

Each entry in results:

Field Type Description
data string Decoded payload as UTF-8; falls back to a hex string when the bytes aren't valid UTF-8
type string Symbol type reported by the decoder, e.g. QRCODE, EAN13, CODE128 (uppercase pyzbar names)
quality string good (confidence ≥ 1) or partial — treat partial as "verify before trusting"
position.polygon array of {x, y} Corner points of the symbol in pixel coordinates; empty array if the decoder reports no polygon
{
  "found": 2,
  "results": [
    {
      "data": "5901234123457",
      "type": "EAN13",
      "quality": "good",
      "position": {
        "polygon": [
          { "x": 42, "y": 310 },
          { "x": 288, "y": 308 },
          { "x": 290, "y": 372 },
          { "x": 41, "y": 374 }
        ]
      }
    },
    {
      "data": "https://toolkitapi.io/docs",
      "type": "QRCODE",
      "quality": "good",
      "position": {
        "polygon": [
          { "x": 600, "y": 100 },
          { "x": 780, "y": 100 },
          { "x": 780, "y": 280 },
          { "x": 600, "y": 280 }
        ]
      }
    }
  ]
}

found: 0 is a success, not an error

A clean 200 with an empty results array means the image was fetched and processed but contained no decodable symbol. Only transport problems, oversized images, blocked URLs, and decode failures produce non-2xx statuses.

How the decoder works (and where it struggles)

The service converts the image to grayscale and runs pyzbar over the whole frame:

  1. Image.open on the bytes — format is sniffed, so PNG/JPEG/GIF/BMP/TIFF all work.
  2. Grayscale conversion (convert("L")) — removes colour noise before detection.
  3. pyzbar.decode returns every symbol plus its polygon and quality score.

Practical consequences:

  • Contrast is everything. A dark barcode on a dark label will decode to nothing. Coloured barcodes often fail; the grayscale conversion assumes luminance separation.
  • Resolution floor. 1D symbols need several pixels per narrow bar. A 200 px-wide photo of a shelf-strip EAN rarely resolves; crop and upscale first.
  • Rotation. Small tilts are tolerated; 90° rotation is usually fine for QR, unreliable for 1D.
  • Multiple symbols in one image all come back — which is why the response is a list and includes polygons.
  • partial quality means the decoder guessed through damage or blur. Log it separately and re-scan rather than persisting the value.

Errors

Status When Example body
400 URL fails SSRF validation, image too large (> 10 MB), unreadable image, both/neither of image/url {"detail": "Image too large: 12582912 bytes (limit 10 MB)"}
401 Missing or invalid API key {"detail": "Unauthorized"}
422 Malformed body (e.g. url longer than 2048 chars) Standard FastAPI validation payload
429 Rate limit exceeded {"detail": "Rate limit exceeded"}
500 Unexpected decoder failure {"detail": "Decode failed: ..."}