The Ebook Glue API

Ebook Glue has a really simple HTTP API at https://ebookglue.com/convert that can help you convert your content to ePub and Mobipocket files. A GET request will allow you to convert a web page, while a POST request will allow you to create a Mobipocket, ePub, or HTML file from many popular document formats.

Ebook Glue also allows you to customize your ebooks with book covers, device-specific optimizations, custom stylesheets, content parsing, and automatic chapter detection.

If you get stuck, email support@ebookglue.com

For updates on the system status of the API, visit our API status dashboard hosted on Google App Engine.

Jump to a Section

Authentication

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

Security Tip

Keep your API key secret - all requests to the API should be proxied if you wish to make requests from a client device.

Code Examples

curl -o converted.epub \
    https://ebookglue.com/convert?token=your-api-key
import requests # http://python-requests.org/

payload = {
    'token': 'your-api-key',
}

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

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

params = {
    :token => 'your-api-key'
}

RestClient.get 'https://ebookglue.com/convert', params
                    
var sys = require('util'),
    rest = require('./restler'); // https://npmjs.org/package/restler

var api_key = 'your-api-key';

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

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

func main() {
    v := url.Values{}
    apiKey := "your-api-key"
    v.Set("token", apiKey)
    apiUrl := "https://ebookglue.com/convert" + v.Encode()
    resp, _ := http.Get(apiUrl)
    fmt.Println(resp.Status)
}
                    
This example will fail with a 401 error if you didn't provide a valid API key. If you provide an API key, it will fail with a 400 error because none of the required parameters are included.

HTTP Error Codes

The code example above will result in a HTTP 401 error if you have not entered a valid API key as the token. Since there are no parameters being passed, it will result in a HTTP 400 error if you're properly authenticated (see below for required parameters on API requests). Here is a list of the HTTP error codes used by the Ebook Glue API:

  • HTTP 400 - check the response for one of the following messages:
    • "Your API request is missing a required parameter."
    • "A parameter in your API request was not properly formatted."
    • "Please provide a file extension or content type for your input document."
  • HTTP 401 - the token was incorrect or not provided
  • HTTP 415 - the input document was malformed or unsupported
  • HTTP 500 - there was a temporary server error

Convert a Web Page or Feed

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

HTTP GET Parameters

  • token - your API key (required)
  • url - the URL of the web page or feed (required)
  • format - ebook output: epub or mobi
  • metadata - JSON-encoded metadata for the book
  • 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

Code Examples

curl -o converted.epub \
    https://ebookglue.com/convert?token=your-api-key&url=http://www.newyorker.com/online/blogs/books/2013/09/oyster-iphone-app-ereader-what-does-it-mean-to-own-a-book.html?printable=true&currentPage=all
import requests # http://python-requests.org/

payload = {
    'token': 'your-api-key',
    'url': 'http://www.newyorker.com/online/blogs/books/2013/09/oyster-iphone-app-ereader-what-does-it-mean-to-own-a-book.html?printable=true&currentPage=all',
}

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

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

params = {
    :token => 'your-api-key',
    :url => 'http://www.newyorker.com/online/blogs/books/2013/09/oyster-iphone-app-ereader-what-does-it-mean-to-own-a-book.html?printable=true&currentPage=all'
}

RestClient.get 'https://ebookglue.com/convert', params
                    
var sys = require('util'),
    rest = require('./restler'); // https://npmjs.org/package/restler

var api_key = 'your-api-key',
    article = 'http://www.newyorker.com/online/blogs/books/2013/09/oyster-iphone-app-ereader-what-does-it-mean-to-own-a-book.html?printable=true&currentPage=all';

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

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

func main() {
    v := url.Values{}
    apiKey := "your-api-key"
    v.Set("token", apiKey)
    apiUrl := "https://ebookglue.com/convert" + v.Encode()
    resp, _ := http.Get(apiUrl)
    fmt.Println(resp.Status)
}
                    
This example will convert a Wikipedia article into an ePub file and download the resulting file.

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 multiple document formats into 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
  • metadata - JSON-encoded metadata for the book
  • 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
  • includes - a ZIP file with images for inclusion

Code Examples

curl -o converted.epub \
    -F "token=your-api-key" \
    -F "file=@index.html" \
    https://ebookglue.com/convert
import requests # http://python-requests.org/

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

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

params = {
    :file => File.new('/path/to/file/index.html'),
    :token => 'your-api-key'
}

RestClient.post 'https://ebookglue.com/convert', params
                    
var sys = require('util'),
    fs = require('fs'),
    rest = require('./restler'); // https://npmjs.org/package/restler

var api_key = 'your-api-key',
    article = 'http://www.newyorker.com/online/blogs/books/2013/09/oyster-iphone-app-ereader-what-does-it-mean-to-own-a-book.html?printable=true&currentPage=all';

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);
    });
});
                    
package main

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

func main() {
    apiKey := "your-api-key"
    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)
}
                    
This example will convert an HTML file into an ePub file and download the resulting file.

HTTP Parameter Details

URL's 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.

Ebook Metadata

By default, ebooks will not have any specific metadata associated with the files. You can set the metadata parameter with a JSON-encoded string containing all of the metadata you would like to include. If an item is not included in your JSON string or you don't supply the metadata property in your request, the metadata fields will be left blank. Here is an example of the properties that can be included:

{
    "authors": ["Carl Sagan"],
    "title": "Pale Blue Dot",
    "tags": ["space exploration", "astronomy"],
    "isbn": "978-0345376596",
    "language": "English",
    "pubdate": "1997-9-8",
    "publisher": "Ballantine Books",
    "producer": "Shantanu Bala",
    "series": "Works by Carl Sagan",
    "series_index": "12",
    "sort": {
        "author": "Sagan, Carl",
        "title": "Pale Blue Dot"
    }
}

A few notes on book metadata: The pubdate parameter accepts an ISO-encoded date string. The sort parameter accepts an object with an extra title and author that will be used to sort the book when displayed in a list. The producer of the book is the person who is preparing the digital copy, while the publisher is generally the person or organization in charge of the publication of the book.

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."

Need help?

If you need help with the Ebook Glue conversion API, send an email to support@ebookglue.com