cli + tui to publish to leaflet (wip) & manage tasks, notes & watch/read lists 馃崈
desertthunder.dev
charm
leaflet
readability
golang
1---
2title: Open Library API
3sidebar_label: Open Library
4sidebar_position: 1
5description: Book metadata via Open Library API integration.
6---
7
8# Open Library API
9
10Noteleaf integrates with [Open Library](https://openlibrary.org) to fetch book metadata, search for books, and enrich your reading list.
11
12## Overview
13
14Open Library provides:
15
16- Book search by title, author, ISBN
17- Work and edition metadata
18- Author information
19- Cover images
20- Subject classifications
21- Publication details
22
23## Configuration
24
25No API key required. Open Library is a free, open API service.
26
27Optional user agent configuration is handled automatically:
28
29```toml
30# .noteleaf.conf.toml
31# No configuration needed for Open Library
32```
33
34## Rate Limiting
35
36Open Library enforces rate limits:
37
38- 180 requests per minute
39- 3 requests per second
40- Burst limit: 5 requests
41
42Noteleaf automatically manages rate limiting to stay within these boundaries.
43
44## Book Search
45
46Search for books from the command line:
47
48```sh
49noteleaf book search "Design Patterns"
50noteleaf book search "Neal Stephenson"
51```
52
53Interactive selection shows:
54
55- Title
56- Author(s)
57- First publication year
58- Edition count
59- Publisher information
60
61## Book Metadata
62
63When adding a book, Noteleaf fetches:
64
65- Title
66- Author names
67- Publication year
68- Edition information
69- Subjects/genres
70- Description (when available)
71- Cover ID
72
73## API Endpoints
74
75### Search Endpoint
76
77```
78GET https://openlibrary.org/search.json
79```
80
81Parameters:
82
83- `q`: Search query
84- `offset`: Pagination offset
85- `limit`: Results per page
86- `fields`: Requested fields
87
88### Work Endpoint
89
90```
91GET https://openlibrary.org/works/{work_key}.json
92```
93
94Returns detailed work information including authors, description, subjects, and covers.
95
96## Data Mapping
97
98Open Library data maps to Noteleaf book fields:
99
100| Open Library | Noteleaf Field |
101|--------------|----------------|
102| title | Title |
103| author_name | Author |
104| first_publish_year | Notes (included) |
105| edition_count | Notes (included) |
106| publisher | Notes (included) |
107| subject | Notes (included) |
108| cover_i | Notes (cover ID) |
109
110## Example API Response
111
112Search result document:
113
114```json
115{
116 "key": "/works/OL45804W",
117 "title": "Design Patterns",
118 "author_name": ["Erich Gamma", "Richard Helm"],
119 "first_publish_year": 1994,
120 "edition_count": 23,
121 "isbn": ["0201633612", "9780201633610"],
122 "publisher": ["Addison-Wesley"],
123 "subject": ["Software design", "Object-oriented programming"],
124 "cover_i": 8644882
125}
126```
127
128## Limitations
129
130### No Direct Page Count
131
132Open Library doesn't consistently provide page counts in search results. Use the interactive editor to add page counts manually if needed.
133
134### Author Keys vs Names
135
136Work endpoints return author keys (`/authors/OL123A`) rather than full names. Noteleaf displays available author names from search results.
137
138### Cover Images
139
140Cover IDs are stored but not automatically downloaded. Future versions may support local cover image caching.
141
142## Error Handling
143
144### Network Issues
145
146```sh
147noteleaf book search "query"
148# Error: failed to connect to Open Library
149```
150
151Check internet connection and Open Library status.
152
153### Rate Limit Exceeded
154
155Noteleaf automatically waits when approaching rate limits. If you see delays, this is normal behavior.
156
157### No Results
158
159```sh
160noteleaf book search "very obscure title"
161# No results found
162```
163
164Try:
165
166- Different search terms
167- Author names instead of titles
168- ISBNs for specific editions
169
170## API Service Architecture
171
172Implementation in `internal/services/services.go`:
173
174```go
175type BookService struct {
176 client *http.Client
177 limiter *rate.Limiter
178 baseURL string
179}
180```
181
182Features:
183
184- Automatic rate limiting
185- Context-aware requests
186- Proper error handling
187- Timeout management (30s)
188
189## Custom User Agent
190
191Noteleaf identifies itself to Open Library:
192
193```
194User-Agent: Noteleaf/v{version} (contact: info@stormlightlabs.org)
195```
196
197This helps Open Library track API usage and contact developers if needed.
198
199## Resources
200
201- [Open Library API Documentation](https://openlibrary.org/dev/docs/api/books)
202- [Open Library Search](https://openlibrary.org/dev/docs/api/search)
203- [Open Library Covers](https://openlibrary.org/dev/docs/api/covers)
204- [Rate Limiting Policy](https://openlibrary.org/developers/api)