grscraper/lib.rs
1//! # Goodreads Metadata Scraper
2//!
3//! This library provides a convenient way to fetch and scrape book metadata from Goodreads by providing either
4//! an ISBN, a Goodreads book ID, or a combination of title and author. It is designed to be used in applications
5//! where access to Goodreads book data is needed, but no official Goodreads API access is available.
6//!
7//! ## Features
8//!
9//! - Retrieve metadata by ISBN
10//! - Retrieve metadata by Goodreads ID
11//! - Retrieve metadata by title (optionally with author for more accurate results)
12//! - Structured, typed metadata output for easy access to common book fields (title, author, publication year, etc.)
13//! - Query builder pattern for customizable requests
14//!
15//! ## Usage
16//!
17//! Add this crate to your dependencies in `Cargo.toml`:
18//!
19//! ```toml
20//! [dependencies]
21//! goodreads-metadata-scraper = "0.1.0"
22//! ```
23//!
24//! ## Examples
25//!
26//! To use this library, create a `MetadataRequestBuilder` to specify the search criteria. Then, use
27//! the `execute` method to retrieve the metadata.
28//!
29//! ### Fetching Metadata by ISBN
30//!
31//! ```rust
32//! use grscraper::MetadataRequestBuilder;
33//!
34//! # #[tokio::main]
35//! # async fn main() -> Result<(), grscraper::ScraperError> {
36//! let isbn = "9780141381473";
37//! let metadata = MetadataRequestBuilder::default()
38//! .with_isbn(isbn)
39//! .execute()
40//! .await?
41//! .expect("Book not found");
42//!
43//! assert_eq!(metadata.title, "The Lightning Thief");
44//! println!("{:?}", metadata);
45//! # Ok::<(), grscraper::ScraperError>(())
46//! # }
47//! ```
48//!
49//! ### Fetching Metadata by Goodreads ID
50//!
51//! ```rust
52//! use grscraper::MetadataRequestBuilder;
53//!
54//! # #[tokio::main]
55//! # async fn main() -> Result<(), grscraper::ScraperError> {
56//! let goodreads_id = "175254";
57//! let metadata = MetadataRequestBuilder::default()
58//! .with_id(goodreads_id)
59//! .execute()
60//! .await?
61//! .expect("Book not found");
62//!
63//! assert_eq!(metadata.title, "Pride and Prejudice");
64//! println!("{:?}", metadata);
65//! # Ok::<(), grscraper::ScraperError>(())
66//! # }
67//! ```
68//!
69//! ### Fetching Metadata by Title and Author
70//!
71//! Providing an author along with the title helps improve the accuracy of the search:
72//!
73//! ```rust
74//! use grscraper::MetadataRequestBuilder;
75//!
76//! # #[tokio::main]
77//! # async fn main() -> Result<(), grscraper::ScraperError> {
78//! let title = "The Last Magician";
79//! let author = "Lisa Maxwell";
80//! let metadata = MetadataRequestBuilder::default()
81//! .with_title(title)
82//! .with_author(author)
83//! .execute()
84//! .await?
85//! .expect("Book not found");
86//!
87//! assert_eq!(metadata.title, title);
88//! println!("{:?}", metadata);
89//! # Ok::<(), grscraper::ScraperError>(())
90//! # }
91//! ```
92//!
93//! ## Limitations
94//!
95//! - Since this library relies on web scraping, it may be sensitive to changes in Goodreads' website structure.
96//! - This library is intended for personal or small-scale use, as frequent requests to Goodreads may be rate-limited.
97//!
98//! **Note:** When running tests, it is highly recommended to run them with the `--test-threads=1` flag to avoid rate-limiting issues with Goodreads.
99//!
100//! ## License
101//!
102//! This project is licensed under the GNU General Public License (GPL).
103//!
104
105mod errors;
106mod goodreads_id_fetcher;
107mod metadata_fetcher;
108mod request_builder;
109
110pub use errors::ScraperError;
111pub use metadata_fetcher::BookContributor;
112pub use metadata_fetcher::BookMetadata;
113pub use metadata_fetcher::BookSeries;
114pub use request_builder::MetadataRequestBuilder;