go-openlibrary

A Go client library for the Open Library API. This library provides a simple interface to search for books and retrieve detailed book information.

Features

• Search for books by title, author, or any query string
• Get detailed book information by ISBN (ISBN-10 or ISBN-13)
• Generate cover image URLs in multiple sizes
• Zero external dependencies (uses only Go standard library)
• Customizable User-Agent for API requests

Installation

go get git.devvul.com/asara/go-openlibrary

Usage

Initialize the Client

import "git.devvul.com/asara/go-openlibrary"

// Initialize with your application details
client := openlibrary.Init("MyApp", "1.0", "contact@example.com")

The Init() function requires three parameters:

• name - Your application name
• version - Your application version
• email - Your contact email address

These are formatted into a User-Agent header as: {name}/{version} ({email})

These are required by openlibrary.org

Get Book by ISBN

book, err := client.BookByISBN("9780140328721")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Title: %s\n", book.Title)
fmt.Printf("Authors: %s\n", book.Authors)
fmt.Printf("Published: %s\n", book.PublishDate)
fmt.Printf("Pages: %d\n", book.Pages)

ISBNs can include hyphens and spaces - they will be automatically cleaned.

Search for Books

// Search with a limit of 10 results
results, err := client.SearchBooks("The Lord of the Rings", 10)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Found %d results\n", results.NumFound)
for _, doc := range results.Docs {
    fmt.Printf("%s by %v\n", doc.Title, doc.AuthorName)
}

Get Cover Image URL

// Get cover URL (this is a standalone function, doesn't require a client)
coverURL := openlibrary.GetCoverURL("9780140328721", "L")
fmt.Println(coverURL)
// Output: https://covers.openlibrary.org/b/isbn/9780140328721-L.jpg

Cover sizes:

• "S" - Small
• "M" - Medium
• "L" - Large

API Reference

Types

BookResult

Simplified book information returned by BookByISBN():

type BookResult struct {
    Title       string
    Subtitle    string
    Authors     string   // Comma-separated author names
    Publishers  string   // Comma-separated publishers
    PublishDate string
    Pages       int
    ISBN10      string
    ISBN13      string
    CoverSmall  string
    CoverMedium string
    CoverLarge  string
    Subjects    string   // Comma-separated subjects
    Description string
    OLID        string   // Open Library ID
}

SearchResponse

Search results returned by SearchBooks():

type SearchResponse struct {
    NumFound int
    Docs     []SearchDoc
}

type SearchDoc struct {
    Title            string
    AuthorName       []string
    FirstPublishYear int
    ISBN             []string
    CoverI           int
    EditionCount     int
    Key              string
}

Methods

Init(name, version, email string) *OpenLibraryApi

Creates and returns a new API client instance.

BookByISBN(isbn string) (*BookResult, error)

Fetches detailed book information for the given ISBN-10 or ISBN-13.

SearchBooks(query string, limit int) (*SearchResponse, error)

Searches for books matching the query string. If limit is 0, defaults to 10 results.

GetCoverURL(isbn string, size string) string

Generates a cover image URL for the given ISBN and size. Size must be "S", "M", or "L" (defaults to "M" if invalid).

Complete Example

package main

import (
    "fmt"
    "log"

    "git.devvul.com/asara/go-openlibrary"
)

func main() {
    // Initialize the client
    client := openlibrary.Init("BookFinder", "1.0", "dev@example.com")

    // Search for books
    results, err := client.SearchBooks("1984 George Orwell", 5)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d results\n\n", results.NumFound)

    // Get details for the first result if it has an ISBN
    if len(results.Docs) > 0 && len(results.Docs[0].ISBN) > 0 {
        isbn := results.Docs[0].ISBN[0]
        book, err := client.BookByISBN(isbn)
        if err != nil {
            log.Fatal(err)
        }

        fmt.Printf("Title: %s\n", book.Title)
        fmt.Printf("Authors: %s\n", book.Authors)
        fmt.Printf("Published: %s\n", book.PublishDate)
        fmt.Printf("Pages: %d\n", book.Pages)
        fmt.Printf("ISBN-13: %s\n", book.ISBN13)

        // Get cover image URL
        coverURL := openlibrary.GetCoverURL(isbn, "L")
        fmt.Printf("Cover: %s\n", coverURL)
    }
}

API Endpoints Used

This library interacts with the following Open Library API endpoints:

• Books API: https://openlibrary.org/api/books?bibkeys=ISBN:{isbn}&jscmd=data&format=json
• Search API: https://openlibrary.org/search.json?q={query}&limit={limit}
• Covers API: https://covers.openlibrary.org/b/isbn/{isbn}-{size}.jpg

License

This library is provided as-is for interacting with the Open Library API. Please review Open Library's terms of use when using this library.

Contributing

Issues and pull requests are welcome.