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:
Image.openon the bytes — format is sniffed, so PNG/JPEG/GIF/BMP/TIFF all work.- Grayscale conversion (
convert("L")) — removes colour noise before detection. pyzbar.decodereturns 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.
partialquality 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: ..."} |
Related¶
- Generate Barcode — produce the symbols this endpoint reads
- Bulk Generate & Decode — combined workflow notes
- Decode Pipeline & Symbol Types — deeper dive into pyzbar behaviour
- QR Codes — the 2D endpoints