openlibrary-go

A fluent and type-safe Go client library for the OpenLibrary API. Search for books, authors, covers, editions, works, and subjects with an elegant builder pattern interface.

Table of Contents

• Features
• Installation
• Quick Start
• Usage Examples
  • Creating a Client
  • Searching Books
  • Searching Authors
  • Fetching Author Works
  • Getting Book Covers
  • Finding Books by ISBN
  • Exploring Book Subjects
  • Getting Work Details
• API Reference
• Contributing
• License

Features

✨ Complete OpenLibrary API Coverage - Access authors, works, editions, search, covers, ISBN lookups, and subjects

🔗 Fluent Builder Pattern - Chainable methods for intuitive API usage

📚 Type-Safe Responses - Strongly typed Go structs for all API responses

🚀 Lightweight - Minimal dependencies (only resty for HTTP client)

🎯 Practical Examples - Comprehensive examples for all major use cases

Installation

go get github.com/raitucarp/openlibrary-go

Requirements: Go 1.25.3 or higher

Quick Start

package main

import (
	"fmt"
	"github.com/raitucarp/openlibrary-go"
)

func main() {
	// Create a client
	client := openlibrary.NewClient()

	// Search for a book
	response, _ := client.Search().Query("Mistborn").Do()
	
	if len(response.Docs) > 0 {
		fmt.Println("Found:", response.Docs[0].Title)
	}
}

Usage Examples

Creating a Client

client := openlibrary.NewClient()

Searching Books

Search for books using various fields and filters:

response, err := client.Search().
	Query("Mistborn").
	Fields(openlibrary.TitleField, openlibrary.KeyField).
	Do()

if err != nil {
	log.Fatal(err)
}

for _, book := range response.Docs {
	fmt.Println(book.Title)
}

Available Search Fields: TitleField, AuthorNameField, ISBNField, PublisherField, PublishDateField, and many more.

Searching Authors

Find authors and explore their information:

client := openlibrary.NewClient()

search, err := client.Authors().Query("Tolkien").Search()
if err != nil {
	log.Fatal(err)
}

if len(search.Docs) > 0 {
	author := search.Docs[0]
	fmt.Println(author.Name)        // J.R.R. Tolkien
	fmt.Println(author.BirthDate)   // Birth date if available
	fmt.Println(author.WorkCount)   // Number of works
}

Fetching Author Works

Retrieve all works by a specific author:

search, _ := client.Authors().Query("Brandon Sanderson").Search()
firstAuthor := search.Docs[0]

worksResp, err := firstAuthor.Works().Fetch()
if err != nil {
	log.Fatal(err)
}

fmt.Println("Author has", worksResp.Size, "works")

Getting Book Covers

Retrieve book cover images using various identifiers:

// By ISBN
coverImg, _, err := client.Cover().ISBN("0312850093").Small().Get()

// By OLID (OpenLibrary ID)
coverImg, _, err := client.Cover().OLID("OL2682450W").Medium().Get()

// By ID
coverImg, _, err := client.Cover().ID("123456").Large().Get()

// Supported sizes: Small (S), Medium (M), Large (L)

Practical Example: Get a cover for a specific book:

// First search for a book
resp, _ := client.Search().Query("Mistborn").
	Fields(openlibrary.TitleField, openlibrary.KeyField).
	Do()

// Get the work and find its editions
workClient := resp.ToClient()
workAPI := workClient.Works(resp.Docs[0].Key)
editions, _ := workAPI.Editions()

// Get edition details
edition := editions.Entries[0]
book, _ := client.Edition(edition.Key).Get()

// Fetch the cover
if len(book.ISBN10) > 0 {
	cover, _, _ := client.Cover().ISBN(book.ISBN10[0]).Small().Get()
	fmt.Println("Cover retrieved:", len(cover), "bytes")
}

Finding Books by ISBN

Look up book information using an ISBN:

edition, err := client.ISBN("0312850093").Get()
if err != nil {
	log.Fatal(err)
}

fmt.Println(edition.Title)        // Book title
fmt.Println(edition.Publishers)   // List of publishers
fmt.Println(edition.PublishDate)  // Publication date

Exploring Book Subjects

Discover works related to a specific subject:

subjects, err := client.Subjects("love").Limit(5).Get()
if err != nil {
	log.Fatal(err)
}

fmt.Println("Subject:", subjects.Name)
fmt.Println("Works found:", len(subjects.Works))

for i, work := range subjects.Works {
	fmt.Printf("%d. %s by %s\n", i+1, work.Title, work.Authors[0].Name)
}

Getting Work Details

Fetch comprehensive information about a specific work:

// Get work details
work, err := client.Works("/works/OL45883W").Get()
if err != nil {
	log.Fatal(err)
}

fmt.Println(work.Title)           // Work title
fmt.Println(work.FirstPublishDate) // First publication date
fmt.Println(len(work.Covers))     // Number of covers available

// Get work editions
editions, err := client.Works("/works/OL45883W").Editions()

// Get ratings and bookshelves
ratings, _ := client.Works("/works/OL45883W").Ratings()
bookshelves, _ := client.Works("/works/OL45883W").Bookshelves()

API Reference

Full API documentation available at pkg.go.dev

Available APIs

Method	Purpose
client.Search()	Search books by title, author, ISBN, etc.
client.Authors()	Search and manage author information
client.Works(key)	Get work details, editions, ratings, and bookshelves
client.Edition(key)	Fetch specific edition information
client.ISBN(isbn)	Look up books by ISBN
client.Cover()	Retrieve book cover images
client.Subjects(name)	Explore books by subject

Contributing

Contributions are welcome! Please refer to CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE.md for details