Getting started with the Barcodes.gg API

What the API does

The Barcodes.gg API turns a barcode into structured product data. You send a GTIN, and the response is a record with name, brand, category, style code, colorway, release date, retail price, sizing and an image. It comes from the same catalog as the public lookup pages. The difference is that the API gives you every field as JSON, so an application can act on it.

It is the version of the free public barcode lookup made for software. The public page is for a person checking a single code. The API is for software that needs to resolve many codes into product records without a person involved.

Everything below uses the version 2 endpoints. The API documentation is the full reference for parameters and fields. This article is a guided first pass.

Create a token

Every request is authenticated with a bearer token. Create one from the tokens section of your dashboard, then send it in an Authorization header on each call.

Tokens carry abilities. An ability is permission to call one family of endpoints. The barcode lookup, for example, requires the lookup-barcode ability. Grant a token only the abilities it needs, and keep it server-side. A token embedded in a mobile binary or a front-end bundle can be extracted and drained, so proxy your calls through a backend you control.

Your first request

A lookup is a single GET request. You pass the barcode in the path and a fields parameter that selects which columns you want back. Use fields=* to receive everything, or a comma-separated list to receive only what you need and keep the payload small.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://barcodes.gg/api/v2/barcode/lookup/0198963114985?fields=*"

That is the whole call. The path segment is the GTIN you are resolving, and the header carries the token you created. If you are unsure about a code, run it through the barcode validation tool first. A mistyped digit then does not cost you a lookup.

Reading the response

A successful response is JSON split into three parts. Knowing the shape up front makes it easy to map into your own models.

• Product - the descriptive fields: product_name, product_brand, product_category, product_style_code, product_colorway, product_release_date, product_retail_price, product_image and sizing arrays such as product_sizes and us_sizes.
• Barcode - facts about the code itself: barcode_type, barcode_value and, where a code maps to one size, a product_size block with US, UK and EU mappings.
• Metadata - error, response_time, request_fulfilled and request_debited, which tells you whether the call counted against your quota.

A code that is not in the catalog returns HTTP 200 with "error": true and a message, not an empty product. Check the error field, not only the status code. Branch on the status and the error flag, and do not assume every call succeeds. We break the response down field by field in what data a barcode lookup API returns.

Beyond the lookup

The lookup is the entry point, but version 2 has endpoints for a full product-data workflow. These are the ones you use next:

For the exact parameters, abilities and response schema of each, the API documentation is the source of truth. When you are ready to design the integration around these calls, the barcode API guide covers the architecture.