Unlocking the Freebooks API: A Developer's Guide to Ebooks and Downloads

21 Apr 2025
Unlocking the Freebooks API: A Developer's Guide to Ebooks and Downloads

The Freebooks API provides an efficient way for developers to access a vast collection of eBooks, enabling them to retrieve detailed information about titles, authors, and genres. With pre-built Cognitive Actions, developers can easily integrate functionalities into their applications, enhancing user experience by providing rich content related to eBooks. In this article, we will explore two essential Cognitive Actions that will help you get started with the Freebooks API.

Prerequisites

Before you begin using the Freebooks API and its Cognitive Actions, ensure that you have:

  • An API key for the Freebooks API platform.
  • A basic understanding of JSON and how to make HTTP requests.

Authentication for the API is typically handled by passing your API key in the request headers.

Cognitive Actions Overview

Fetch Ebooks Information

The Fetch Ebooks Information action allows you to retrieve detailed information about eBooks based on a specific title, author, or genre. The response includes essential details such as image URL, number of pages, size, year of publication, publisher, language, title, type, authors, and a unique book ID, which can be used to fetch a book summary.

Input

The input schema for this action requires the following:

  • title (string, required): The title or category of the request. The default value is "horror".

Example input JSON:

{
  "title": "horror"
}

Output

The output will return an array of eBook objects, each containing:

  • size (number): The size of the eBook file.
  • type (string): The file format of the eBook (e.g., pdf).
  • year (number): The year of publication.
  • pages (number): The number of pages in the eBook.
  • title (string): The title of the eBook.
  • bookId (string): A unique identifier for the eBook.
  • imgUrl (string): A URL to the cover image of the eBook.
  • authors (string): The author(s) of the eBook.
  • language (string): The language of the eBook.
  • publisher (string): The publisher of the eBook.

Example output:

[
  {
    "size": 32509267,
    "type": "pdf",
    "year": 1997,
    "pages": 52,
    "title": "Fieseler Fi 156 Storch: ",
    "bookId": "6bdd995c4e36f00879396088d1a079a3",
    "imgUrl": "http://libgen.is/covers/188000/6bdd995c4e36f00879396088d1a079a3-d.jpg",
    "authors": "Heinz J. Nowarra",
    "language": "English",
    "publisher": "Schiffer Publishing, Ltd."
  },
  ...
]

Conceptual Usage Example (Python)

Here's how you might call this action using a conceptual Python snippet:

import requests
import json

# Replace with your Cognitive Actions API key and endpoint
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute" # Hypothetical endpoint

action_id = "26cd742b-4be9-43b8-9da4-96eb59e7c1b4"  # Action ID for Fetch Ebooks Information

# Construct the input payload based on the action's requirements
payload = {
    "title": "horror"
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json"
}

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json={"action_id": action_id, "inputs": payload}  # Hypothetical structure
    )
    response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body: {e.response.text}")

Retrieve Book Download URLs

The Retrieve Book Download URLs action enables users to get download URLs for a specified book using its unique book ID. This action returns URLs from three different mirrors, allowing users to access downloadable content from multiple sources.

Input

The input schema requires the following:

  • bookId (string, required): A unique identifier for the book.

Example input JSON:

{
  "bookId": "f9c34bd70adadf9c8fb5d3ea42d73791"
}

Output

The output will return an object containing:

  • bookId (string): The ID of the book.
  • mirror1 (string): Download URL from mirror 1.
  • mirror2 (string): Download URL from mirror 2.
  • mirror3 (string): Download URL from mirror 3.

Example output:

{
  "bookId": "f9c34bd70adadf9c8fb5d3ea42d73791",
  "mirror1": "http://mirror1.example.com/download?id=f9c34bd70adadf9c8fb5d3ea42d73791",
  "mirror2": "http://mirror2.example.com/download?id=f9c34bd70adadf9c8fb5d3ea42d73791",
  "mirror3": "http://mirror3.example.com/download?id=f9c34bd70adadf9c8fb5d3ea42d73791"
}

Conceptual Usage Example (Python)

Here’s how you might call this action using a conceptual Python snippet:

import requests
import json

# Replace with your Cognitive Actions API key and endpoint
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute" # Hypothetical endpoint

action_id = "33cc5379-b505-47e7-b1d9-e13c285f44f9"  # Action ID for Retrieve Book Download URLs

# Construct the input payload based on the action's requirements
payload = {
    "bookId": "f9c34bd70adadf9c8fb5d3ea42d73791"
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json"
}

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json={"action_id": action_id, "inputs": payload}  # Hypothetical structure
    )
    response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body: {e.response.text}")

Conclusion

The Freebooks API offers developers powerful tools to enhance their applications with rich eBook content and download capabilities. By utilizing the Fetch Ebooks Information and Retrieve Book Download URLs actions, you can provide users with valuable resources and seamless access to content. As you continue to explore the Freebooks API, consider how these actions can be integrated into your projects for improved user engagement and functionality. Happy coding!

← Back to All Articles