Booko API v3

Get current user information and OAuth application details.

Search for books, works, and series with pagination and filtering. Returns mixed results with relevance scoring.

curl -H "Authorization: Bearer your-token" \
  "https://api.booko.info/api/v3/search?q=ruby+programming&ptype=book&per_page=10"

{
  "data": [
    {
      "type": "product",
      "id": 123,
      "gtin": "9781234567890",
      "title": "The Ruby Programming Language",
      "subtitle": "Everything You Need to Know",
      "author": "Matz Yukihiro",
      "publisher": "O'Reilly Media",
      "ptype": "book",
      "cover_url": "https://covers.booko.info/...",
      "search_score": 0.95,
      "path": "/products/9781234567890",
      "work": {
        "id": 456,
        "name": "The Ruby Programming Language",
        "gtins": ["9781234567890", "9780987654321"]
      }
    },
    {
      "type": "work",
      "id": 789,
      "name": "Programming Ruby",
      "author": "Dave Thomas",
      "search_score": 0.87,
      "path": "/works/789",
      "products": [
        {
          "id": 321,
          "gtin": "9785432109876",
          "title": "Programming Ruby",
          "ptype": "book",
          "region": "US"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total_hits": 156,
      "total_pages": 16,
      "has_next_page": true,
      "has_previous_page": false
    },
    "search": {
      "query": "ruby programming",
      "ptype": "book",
      "search_time": 0.045,
      "processing_time": 12
    }
  }
}

Get detailed information about a specific product. ID can be GTIN, ISBN, or internal ID.

{
  "type": "product",
  "id": 123,
  "gtin": "9781234567890",
  "title": "The Great Book",
  "subtitle": "A Wonderful Story",
  "author": "Jane Smith",
  "publisher": "Great Publisher",
  "published_on": "2023-01-01",
  "package": "Paperback",
  "cover_url": "https://covers.booko.info/...",
  "description": "An amazing book about...",
  "path": "/products/9781234567890",
  "work": {
    "id": 456,
    "name": "The Great Book",
    "gtins": ["9781234567890", "9780987654321"]
  }
}

Get user's lists or public discoverable lists.

Create a new reading list.

{
  "name": "My Reading List",
  "visibility": "hidden",
  "region": 1,
  "gtins": ["9781234567890", "9780987654321"]
}

Get all items in a list with pagination.

Add items to a list. Supports single items or bulk operations.

{
  "type": "Product",
  "id": "9781234567890",
  "quantity": 1
}

{
  "items": [
    {
      "type": "Product",
      "id": "9781234567890",
      "quantity": 1
    },
    {
      "type": "Work", 
      "id": "123",
      "quantity": 1
    }
  ]
}

Get user's alerts with filtering and sorting options.

{
  "data": [
    {
      "id": 123,
      "product_id": 456,
      "product_title": "The Great Book",
      "product_gtin": "9781234567890",
      "new_price": "25.99",
      "used_price": "15.99",
      "include_used": true,
      "active": true,
      "region_id": 1,
      "region_name": "Australia",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-02T00:00:00Z",
      "deactivated_at": null,
      "sent_date": null,
      "sent_price": null
    }
  ],
  "meta": {
    "total_count": 5,
    "active_count": 3,
    "inactive_count": 2
  }
}

Create a new price alert or update an existing one for the same product.

{
  "alert": {
    "gtin": "9781234567890",
    "new_price": "25.99",
    "used_price": "15.99",
    "include_used": true,
    "active": true
  }
}

curl -X POST https://api.booko.info/api/v3/alerts \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "alert": {
      "gtin": "9781234567890",
      "new_price": "25.99",
      "used_price": "15.99",
      "include_used": true,
      "active": true
    }
  }'

• v3 DVDs are searchable. ptype=video 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 and could not be found however you asked.
• v1 v2 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. It now accepts query_type, ptype and product_type alike, as either the type name (video) or its id (2).
• v1 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. Fetching a product also queues the detail lookup, so polling gets somewhere.
• v1 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.
• v3 A request may name its own region. A signed API request asking for prices in a given region gets that region, instead of having it second-guessed by the caller's geolocation.