API docs

Product API — response codes and objects

In this reference we will explore the structure of successful and error responses of product API as well as possible causes for various errors. For information about account API see Account API — response codes and objects

Product API is available at https://ean-db.com/api/v1/product/{barcode} endpoint where {barcode} is a placeholder for an actual EAN / UPC / ISBN barcode.

200 — Everything’s OK
404 — Product not found
403 — Access denied
400 — Barcode is invalid

200 — Everything’s OK

A successful request like this:

curl -X GET -H 'Authorization: Bearer HERE_GOES_YOUR_JWT_TOKEN' -H 'Accept: application/json' \
    https://ean-db.com/api/v1/product/1234567890123

returns a response with 200 response code and a ProductResponse object.

Note that we use Accept: application/json header to specify response content type (in this case JSON). But our API also supports application/xml content type, therefore all following response examples also include XML representation.

If Accept header is omitted then application/json is assumed by default.

{
    "balance": 100,                       // Your current balance (remaining requests), integer
    "product": {
        "barcode": "1234567890123",       // Product barcode normalized to canonical GTIN-8/12/13/14 form, string
        "titles": {
            "en": "Product title",        // Product titles, language → title mapping
            "de": "Produktname"
        },
        "categories": [                   // Product categories, array of objects (or an empty array)
            {
                "id": "3911",             // Category id from Google product taxonomy, string
                "titles": {               // Category titles, "lang" → "title" mapping
                    "en": "Bath Toys"
                }
            },
            {
                "id": "543543",
                "titles": {
                    "en": "Print Books"
                }
            }
        ],
        "manufacturer": {             // Product manufacturer or brand (if available, may be null)
            "id": "manufacturer-id",  // Manufacturer / brand id (for identified manufacturers, may be null), string
            "titles": {               // Manufacturer / brand titles, "lang" → "title" mapping
                "en": "Manufacturer"
            },
            "wikidataId": "Q12345"    // Manufacturer / brand id from https://wikidata.org (if exists, may be null), string
        },
        "relatedBrands": [{           // Other brands that may be related to a product (distributors, collaborations, etc), array of objects (or an empty array)
            "id": "related-manufacturer-id",
            "titles": {
                "en": "Related manufacturer"
            },
            "wikidataId": "Q12346"
        }],
        "images": [                   // Product images, array of objects (or an empty array)
            {
                "url": "https://ean-db.com/image.jpg",  // Image URL, string
                "isCatalog": true                       // True if an image can be used in a catalog (professionally captured)
            }
        ],
        "metadata": {                 // Product metadata (if available, may be null), see [Products metadata](/docs/productMetadata) for more details
            "printBook": {
                "numPages": 123,
                "publishedYear": 2010
            }
        }
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <balance>100</balance>
    <product>
        <barcode>1234567890123</barcode>
        <titles>
            <title lang="en">Product title</title>
            <title lang="de">Produktname</title>
        </titles>
        <categories>
            <category>
                <id>1239</id>
                <titles>
                    <title lang="en">Toys & Games</title>
                </titles>
            </category>
            <category>
                <id>2847</id>
                <titles>
                    <title lang="en">Baby Toys & Activity Equipment</title>
                </titles>
            </category>
        </categories>
        <manufacturer>
            <id>manufacturer-id</id>
            <titles>
                <title lang="en">Product manufacturer</title>
            </titles>
            <wikidataId>Q12345</wikidataId>
        </manufacturer>
        <images>
            <image>
                <url>https://ean-db.com/image.jpg</url>
            </image>
        </images>
        <metadata>
            <printBook>
                <numPages>123</numPages>
                <publishedYear>2010</publishedYear>
            </printBook>
        </metadata>
    </product>
</response>

For a formal description of the response object please refer to ProductResponse JSON schema and XML schema.

categories field is an array of objects containing id and title of each product category (or an empty array if the product is not yet categorized). Products are categorized using Google’s product taxonomy, please refer to this article for more information about taxonomy.

manufacturer field contains information about product manufacturer or brand. It may be null if the information is not yet available. Otherwise, at least manufacturer.titles is present.

Some companies and brands are identidied within our database. In this case manufacturer.id field is present. This is a permanent identifier that can be used to resolve ambiguity between manufacturers with similar names.

relatedBrands contains information about other brands that may be related to a product or appear on the packaging (for example, distributors or collaborations). This is an array of objects of the same structure as in manufacturer field. All companies or brands in relatedBrands field are identified (contain id field).

images field is an array of objects containing URLs of product images (or an empty array if the product has no images yet).

For many products metadata field may be available (non-null). It aggregates product metadata like weight, nutritional value for a food product or number of pages for a pringt book. The set of available metadata may vary depending on the product type. For detailed information please see Product metadata.

404 — Product not found

You’ll get this kind of response if there is no product with the requested barcode in our database. 404 responses do not reduce your account balance.

{
    "error": {
        "code": 404,                                       // Error code, integer
        "description": "Product not found: 9785811264209"  // Short error description, string
    },
    "balance": 100                                         // Your current balance (remaining requests), integer
}

<response>
    <error>
        <code>404</code>
        <description>Product not found: 9785811264209</description>
    </error>
    <balance>100</balance>
</response>

403 — Access denied

You can get 403 response for a couple of reasons:

Authorization header containing your JWT is missing, malformed or invalid.
In this case you’ll see a message JWT is missing or invalid, check Authorization header in the description field of the error response. You could check the tutorial for more information on how get JWT and pass it correctly.
Your account email is not confirmed.
We require that you confirm your email address by visiting a confirmation link in a welcome email sent to you after registration.
In case of this error description field contains a message Your account is not confirmed, please check your email for confirmation link.
Your JWT was revoked (look for JWT revoked message in the description field).
You can revoke your current JWT (and effectively deny access to anyone who tries to use it) in your account area. This error is what you’ll see if you make an API request using one of the revoked JWTs.
Your JWT is expired (look for JWT expired message in the description field).
JWT expires after one year since it was generated. If you get this error, you need to generate new JWT in your account area and replace the old one with freshly generated JWT.
Your account balance is empty.
In this case description field contains a message Your account balance is empty.

{
    "error": {
        "code": 403,
        "description": "Your account balance is empty"  // Or one of the other error messages
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <error>
        <code>403</code>
        <description>Your account balance is empty</description>
    </error>
</response>

400 — Barcode is invalid

400 response code indicates that the barcode you passed in your API request is invalid for some reason (contains invalid charachters, too short or too long, etc). Detailed information is given in the description field of an error response.

{
    "error": {
        "code": 400,
        "description": "Invalid barcode: 978581126barcode"  // Or one of the other error messages
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
    <error>
        <code>400</code>
        <description>Invalid barcode: 978581126barcode</description>
    </error>
</response>

Related topics: ProductResponse JSON schema · ProductResponse XML schema · Billing