grscraper/
lib.rs

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

grscraper/
lib.rs
