Access to the Booko API requires authentication. The API Endpoint currently in production is:

https://api.booko.info/api/v1/

Authentication

There are two methods to authenticate. Unless there's a specific reason, you should use the JWT Authentication Header method.

Bearer Authenticaion Header

Generate a Javascript Web Token, encoding the user_id with an iat (Issued At) claim, an exp( Expiry ) claim 5 minutes from, using the API key as the key, using encryption algorithm HS256

Note: exp is currently required. Please include iat as the API will switch to requiring iat, rather than exp.

Add an Authentiation header with your request,

Authorization: Bearer <token>

Ruby Example

def token(user_id, key)
  in_5_minutes = Time.now + 60 * 5
  exp = (in_5_minutes).to_i
  JWT.encode({user_id: user_id, exp: exp}, key: key, 'HS256')
end

URL Signature

This method is deprecated.

api_user
Booko User ID with permission to access resource
ts
Unix Time stamp
signature
SHA1 HMAC of the request path.

The Time stamp is used to ensure API calls aren't replayed. Use the current time for the time stamp.

Example

      api_user = 44
      api_key  = 'hSe7Km6D'
      gtin     = '9780748109999'

      path     = "/api/v1/products/#{gtin}?api_user=#{api_user}&ts=#{Time.now.to_i}"
      => "/api/v1/products/9780748109999?api_user=44&ts=1374894665"

      digest   = OpenSSL::Digest.new('sha1')
      res      = OpenSSL::HMAC.digest(digest, api_key, path)
      sig      = [res].pack('m').chomp

      url      = "https://api.booko.info#{path}&signature=#{sig}"
      => "https://api.booko.info/api/v1/products/9780748109999?api_user=44&ts=1374894665&signature=9O6VKp0rau4ODJYKPubYctHaQ6A="

Using the above path and api_key variables, you should be able to generate the example signature.

Caching

The Booko API should return one of, or both, the headers "Last Modified and "ETag" with responses. Using these values in your requests ( ie, headers 'If-None-Match: ""' and/or 'If-Modified-Since: some date' ) means you get 304 - Not Modified when appropriate, cutting down on traffic and speeding response times.

Product Search

https://api.booko.info/api/v1/products/search?q=Cryptonomicon

Optionally restrict results to one product type with query_type (ptype and product_type are accepted as aliases). Pass either the name or the id:

https://api.booko.info/api/v1/products/search?q=Amadeus&query_type=video

1 book
2 video
3 ebook
4 audiobook
5 toy
6 lego
7 pop
8 graphic_novel
9 box_set
10 music
11 ereader
12 table_top_game
13 food_stuff
99 other

Books, ebooks, audiobooks, graphic novels, box sets and videos each have a search index behind them. The remaining types are sourced from the shops we search live, so they return fewer results and take longer.

Product Data

https://api.booko.info/api/v1/products/9780748109999

Collection Data

https://api.booko.info/api/v1/series/1

https://api.booko.info/api/v1/works/4

https://api.booko.info/api/v1/parts/1

To queue prices for works, include a region id.

https://api.booko.info/api/v1/works/4?region=1

Product Prices

https://api.booko.info/api/v1/products/9780748109999/prices?region=1

Region is an optional parameter. It will default to region 1

Regions

Booko will respond to regional queries

Region 1 Australia
Region 2 United Kingdom
Region 3 United States
Region 4 New Zealand
Region 5 Canada
Region 6 Finland
Region 7 Spain
Region 8 Ireland
Region 9 France
Region 10 Italy
Region 11 Norway
Region 12 Sweden
Region 13 Japan
Region 14 Germany
Region 15 Singapore
Region 16 China
Region 17 Taiwan
Region 18 Philippines
Region 19 Malaysia
Region 20 Argentina
Region 21 Chile
Region 22 Israel
Region 23 Hong Kong

Price States

Price / Shop links should be in the form

http://booko.com.au/prices/#{price.UID}?api_user=api_user.id

The response keys at the top level correspond to price state:

Price states are as below

0 Loading: Price grabber is actively looking for the price
1 Found: Price was successfully found
2 Not Found: Shop does not sell this book
3 No Response: Shop error / Timeout
4 Error: Booko Error
5 Not Available: Product is not available
6 Out of Stock: Product is for sale, but not in stock
7 Out of Region: Shop doesn't support client region

Within each state, an array of the prices is returned. Empty price states are not returned. IE, if there are no "Out Of Stock" books, there'll be no result set "6".

There is a price result per shop. If a shop sells both new and used products, there will be two prices.

Offer Condition

Offers for books may be New or Used

0 New Price
1 Used Price

Product Images

Within the Product response, image_url holds the URL for cover art and image_url_jxl holds the same cover in JPEG XL. Prefer the JXL if you can decode it — it is roughly 30% smaller for the same picture — and fall back to image_url.

"image_url":     "https://cdn.booko.info/variants-production/73f95226ad27ec3d/600.jpeg"
"image_url_jxl": "https://cdn.booko.info/variants-production/73f95226ad27ec3d/1024.jxl"

Both URLs are public, unsigned and safe to cache. Please use the URL as we send it rather than assembling your own: renditions are generated on demand, so a size we have not produced for a given cover returns 404. The sizes that exist are 600, 800 and 1024 on the longest edge with the aspect ratio kept, plus 120x120, 160x160, 240x240, 500x750 and 666x1000 which are cropped to fit — each in .jpeg and .jxl.

Cover art is not regional: one CDN serves every region. If you are still holding per-region cover hosts such as covers.booko.com.au, they are retired and can be dropped.

Shops

Collection

https://api.booko.info/api/v1/shops

Single

https://api.booko.info/api/v1/shops/1

Popular Products

https://api.booko.info/api/v1/widgets/popular

List View

User lists can be retreived with

GET https://api.booko.info/api/v1/lists

Public lists can be created with the end point

POST https://api.booko.info/api/v1/lists

Parameter	Description
gtins	Required. Comma separated lists of GTINS. No spaces or hypens allowed.
region	Optional. For this list, prices will be calculated in the specificed region. Defaults to 1.
name	Optional. Name of the list to create. Defaults to "Anonymous Public List".
email	Optional. Email address of the account to attach the list to.
password	Optional. Password associated with the account.

User Login

Actions requiring authenticated users, such as viewing and modifiying lists, require the auth_token. The request requires user's email and password. These values should not be stored by the App once the auth_token has been retreived.

GET https://api.booko.info/api/v1/users/auth_token

Parameter	Description
User	Required. Email address of the account to retrieve auth_token for.
Password	Required.

Response will be 401, Unauthenticated when credentials are incorrect.

Changelog

Notable changes to the v1 API. Changes affecting v3 are listed on the v3 page.

10 August 2026

Search honours the product type again. /products/search read only query_type, so a request filtering on any other spelling was silently unfiltered and came back with books whatever you asked for. It now accepts query_type, ptype and product_type alike, as either the type name (video) or its id (2).
DVDs are searchable. query_type=2 now has a search index behind it. Previously the only discs search could reach were ones attached to a work; standalone editions were in no index at all.
stale_details? can now go false. The field answers "is it worth asking for this product again", rather than reporting staleness no client could ever clear. If you have been seeing it true on every product on every request, that is why: from August 2022 to August 2026 nothing wrote the timestamp behind it, so it was a constant. No change is needed at your end — the field keeps its name, and now means what you already assumed it meant.
When stale_details? goes false. Either we have something worth showing you — a title and cover art — or we have looked and there is nothing more coming. A product whose publisher never sent us data will settle as false rather than asking to be fetched forever. Fetching a product also queues the detail lookup now, so polling gets somewhere.
New field image_url_jxl on product responses — the same cover in JPEG XL at the largest rendition we hold. Prefer it if you can decode it, and fall back to image_url.
The cover art documented here was wrong. This page gave the host as c.booko.info and the path as /covers/<hash>/v/800.jpeg; neither has existed for some time. Covers are served from cdn.booko.info, and the Product Images section above now lists the renditions that actually exist. Nothing changed at our end — the documentation was stale.
Regions 18 to 23 were missing from this page. Philippines, Malaysia, Argentina, Chile, Israel and Hong Kong have been valid region values for a while and were simply never listed.