Ebook Glue

This add-on is operated by Ebook Glue

Create .epub and .mobi ebooks for Kindle, Nook, iBooks, and popular readers.

Ebook Glue

Last Updated: 09 November 2013

The Ebook Glue add-on is currently in beta.

Table of Contents

Ebook Glue is an add-on for converting your documents and content into ePub (.epub) and Mobipocket (.mobi) ebooks for the iBooks, Kindle, Nook, and Google Play reading platforms.

Ebook Glue is accessible via a simple HTTP API.

Provisioning the add-on

Ebook Glue can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add ebookglue
-----> Adding ebookglue to sharp-mountain-4005... done, v18 (free)

Once Ebook Glue has been added a EBOOKGLUE_TOKEN setting will be available in the app configuration and will contain the API key that you can use to authenticate your requests. This can be confirmed using the heroku config:get command.

$ heroku config:get EBOOKGLUE_TOKEN
http://user:pass@instance.ip/resourceid

After installing Ebook Glue the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export EBOOKGLUE_TOKEN=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the EBOOKGLUE_TOKEN values retrieved from heroku config to .env.

$ heroku config -s | grep EBOOKGLUE_TOKEN >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Dashboard

For more information on the features available within the Ebook Glue dashboard please see the docs at https://ebookglue.com/docs.

The Ebook Glue dashboard allows you to monitor usage on your account.

The dashboard can be accessed via the CLI:

$ heroku addons:open ebookglue
Opening ebookglue for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Ebook Glue from the Add-ons menu.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade ebookglue:max
-----> Upgrading ebookglue:max to sharp-mountain-4005... done, v18 ($149/mo)
       Your plan has been updated to: ebookglue:max

Removing the add-on

Ebook Glue can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove ebookglue
-----> Removing ebookglue from sharp-mountain-4005... done, v20 (free)

Authentication

Make sure to keep your API Key secret. Although it is possible to reset the key, it allows access to your Ebook Glue account.

To authenticate, set the token parameter on every request with your full API key. Every request must have your API key to be processed.

Convert a web page

Converting a web page involves a GET request to https://ebookglue.com/convert including the URL of the web page you’d like to convert (CSS and images will be included) and the format of the output (epub or mobi).

HTTP GET parameters

  • token - your API key (required)
  • url - the URL of the web page (required)
  • format - ebook output: epub or mobi
  • cover - the URL of an image to use as a cover
  • device - optimize for a device (see below)
  • stylesheet - the URL of a CSS file to include
  • chapters - an XPath expression for chapter headings

Convert a file

Converting a file involves a POST request to https://ebookglue.com/convert that is multipart/form-data including the file you would like to convert (you can convert HTML, ePub, and Mobipocket files) and the format of the output (epub or mobi).

HTTP POST parameters

  • token - your API key (required)
  • file - the file for conversion (required)

    • .html - markup and web pages
    • .mobi - Mobipocket ebooks
    • .epub - ePub ebooks
    • .docx - Microsoft Word files
    • .doc - Microsoft Word (older versions)
    • .odt - LibreOffice or OpenOffice
    • .txt - plain text
  • format - ebook output: epub or mobi

  • cover - the image file to use as a cover

  • device - optimize for a device (see below)

  • stylesheet - the CSS file to include

  • chapters - an XPath expression for chapter headings

HTTP parameters

URLs in HTTP GET requests

When issuing a GET request to Ebook Glue, you need to pass URL’s for some of the parameters. Make sure your URL is the full URL (including the http://) and publicly accessible.

Files in HTTP POST requests

When issuing a POST request to Ebook Glue, you need to provide file uploads for some of the parameters as a regular file upload similar to a <input type="file">.

Ebook formats

The format parameter controls the output format. By default, ePub files are generated, but you can explicitly set the value of the format parameter to epub or mobi for ePub or Mobipocket books respectively. Although ePub is the standard format for ebooks, Amazon Kindle devices only support Mobipocket books.

Book covers

By default, ebooks will not have any book covers unless you specify one. When fetching a web page, you set the cover parameter to the URL of the cover you would like to use (for GET requests to the API) or the image file itself (for POST requests). The best height:width ratio is 4:3, and higher resolution images are recommended, but Ebook Glue will ensure that your book cover will not be stretched or cropped. Instead, blank space will be added to either increase the height or width appropriately.

Device optimization

Ebook Glue allows you to optimize your ebooks to display well on different devices. Since each device has a unique form factor, Ebook Glue gives you pre-defined CSS rules that help ensure your ebook looks good. Set the device parameter to:

  • kindle-eink - Kindle readers with a standard e-ink or e-ink pearl display
  • kindle-paper - Kindle readers with a high resolution paperwhite display
  • kindle-fire - Kindle Fire tablets
  • kindle-dx - Kindle DX readers with a large e-ink display
  • nook-eink - Nook models with a standard e-ink or e-ink pearl display
  • nook-color - Nook Color tablets
  • nook-hd - Nook Color HD Plus tablets
  • kobo-eink - Kobo readers with a standard e-ink or e-ink pearl display
  • generic-eink - Generic devices with a standard e-ink or e-ink pearl display
  • generic-eink-large - Generic devices with a large e-ink or e-ink pearl display

Extra stylesheet

Ebook Glue allows you to specify an extra stylesheet that can be used to modify the appearance of your ebook. Note that not all devices are capable of renderring all CSS rules. The stylesheet parameter allows you to specify the URL of a stylesheet to include (for GET requests to the API) or the CSS file itself (for POST requests).

Chapter detection

Unless you specify an XPath expression in the chapters parameter, Ebook Glue will use elements with the class chapter as well as h1 and h2 elements containing the words, “chapter,” “book,” “prologue,” “epilogue,” “part,” or “section.”

Using with Curl

You can use Ebook Glue using curl from a terminal.

Example: Convert a web page

$ curl -o converted.epub \
    https://ebookglue.com/convert?token=YOUR-API-KEY&url=https://en.wikipedia.org/w/index.php?title=E-book&printable=yes

Example: Convert a file

$ curl -o converted.epub \
    -F "token=YOUR-API-KEY" \
    -F "file=@index.html" \
    https://ebookglue.com/convert

Using with Ruby

Integrating with Ebook Glue in Ruby is very simple. Here is an example using the rest_client gem.

$ gem install rest_client

Example: Convert a web page

require 'rest_client' # https://github.com/rest-client/rest-client

params = {
    :token => ENV['EBOOKGLUE_TOKEN'],
    :url => 'https://en.wikipedia.org/w/index.php?title=E-book&printable=yes'
}

RestClient.get 'https://ebookglue.com/convert', params

Example: Convert a file

require 'rest_client' # https://github.com/rest-client/rest-client

params = {
    :file => File.new('/path/to/file/index.html'),
    :token => ENV['EBOOKGLUE_TOKEN']
}

RestClient.post 'https://ebookglue.com/convert', params

Using with Python

Integrating with Ebook Glue in Python is very simple as well. Here is an example using the requests package.

$ pip install requests

Example: Convert a web page

import requests # http://python-requests.org/
import os

API_TOKEN = os.environ.get("EBOOKGLUE_TOKEN")

payload = {
    'token': API_TOKEN,
    'url': 'https://en.wikipedia.org/w/index.php?title=E-book&printable=yes',
}

r = requests.get('https://ebookglue.com/convert', params=payload)

print r.status_code

Example: Convert a file

import requests # http://python-requests.org/
import os

API_TOKEN = os.environ.get("EBOOKGLUE_TOKEN")

data = {
    'token': API_TOKEN,
}
files = {
    'file': file_object,
}
r = requests.post("https://ebookglue.com/convert", data=data, files=files)

print r.status_code

Using with Node.js

Integrating with Ebook Glue in Node is also not very complicated. Here is an example using the restler package.

$ npm install restler

Example: Convert a web page

var sys = require('util'),
    rest = require('./restler'); // https://npmjs.org/package/restler

var api_key = process.env.EBOOKGLUE_TOKEN,
    article = 'https://en.wikipedia.org/w/index.php?title=E-book&printable=yes';

rest.get("https://ebookglue.com/convert", {
    'data': {
        'token': api_key,
        'url': article
    }
}).on('complete', function (data, response) {
   sys.puts(response.statusCode);
});

Example: Convert a file

var sys = require('util'),
    fs = require('fs'),
    rest = require('./restler'); // https://npmjs.org/package/restler

var api_key = process.env.EBOOKGLUE_TOKEN,
    article = 'https://en.wikipedia.org/w/index.php?title=E-book&printable=yes';

fs.stat("index.html", function(err, stats) {
    rest.get("https://ebookglue.com/convert", {
        'multipart': true,
        'data': {
            'token': api_key,
            'file': rest.file('index.html', null, stats.size, null, "text/html")
        }
    }).on('complete', function (data, response) {
       sys.puts(response.statusCode);
    });
});

Using with Go

Integrating with Ebook Glue in Go is also not very complicated. Here is an example using the net package in the Go standard library.

Example: Convert a web page

package main

import (
    "fmt"
    "net/url"
    "net/http"
    "os"
)

func main() {
    v := url.Values{}
    apiKey := os.Getenv("EBOOKGLUE_TOKEN")
    v.Set("token", apiKey)
    apiUrl := "https://ebookglue.com/convert" + v.Encode()
    resp, _ := http.Get(apiUrl)
    fmt.Println(resp.Status)
}

Example: Convert a file

package main

import (
    "fmt"
    "mime/multipart"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("EBOOKGLUE_TOKEN")
    client := &Client{}
    apiUrl := "https://ebookglue.com/convert"

    buf := new(bytes.Buffer)
    w := multipart.NewWriter(buf)
    label, _ := w.CreateFormField("token")
    label.Write([]byte(apiKey))

    fw, _ := w.CreateFormFile("file", "index.html")
    fd, _ := os.Open("index.html")
    io.Copy(fw, fd)
    defer fd.Close()
    w.Close()

    req, _ := http.NewRequest("POST", apiUrl, buf)

    req.Header.Set("Content-Type", w.FormDataContentType())
    resp, _ := client.Do(req)

    fmt.Println(resp.Status)
}

Need help?

All Ebook Glue support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at contact@ebookglue.com