bookclerk_audible_catalog
Unauthenticated Audible catalog HTTP: keyword, author, narrator, series
and genre search, plus ratings and reviews, from the public
api.audible{tld} catalog. No Audible login is involved.
The Audible storefront guest uses it for Discover search, expand and
purchase hints; host enrichment (bookclerk-enrich) uses it to match
titles from other stores to an ASIN. It links only the plugin SDK's HTTP
client and bookclerk-storefront, so the guest does not pull in the host's
library stack.
| Item | Kind | Summary |
|---|---|---|
CatalogProduct |
struct | One Audible catalog product (public search hit). |
CatalogRating |
struct | Community ratings from a single Audible catalog product (response_groups=rating). |
CatalogReview |
struct | One customer review from Audible's public catalog reviews endpoint. |
CatalogReviewsPage |
struct | One page of helpful Audible customer reviews (public; no account). |
CatalogError |
enum | Failures talking to the public Audible catalog. |
CatalogList |
enum | Which product list of an Audible catalog answer to read. |
CatalogReviewsSort |
enum | Audible catalog reviews sort (MostHelpful or MostRecent). |
catalog_origin |
function | The public catalog's origin for a marketplace, without a trailing slash (https://api.audible.co.uk for uk). |
fetch_audible_catalog_rating |
function | Fetch Audible community ratings for one ASIN (public catalog; no account). |
fetch_audible_catalog_reviews |
function | Fetch a short list of helpful Audible customer reviews (public; no account). |
fetch_audible_catalog_reviews_page |
function | Paginated Audible catalog reviews (page is 1-based). |
fetch_products_by_asins |
function | Looks titles up by ASIN in the public catalog, with their genre ladders. |
is_audible_podcast_product |
function | True for Audible podcast shows / episodes (content_type / delivery type). |
normalize_region |
function | Normalize a marketplace string to an Audible / Audnexus region value. |
normalize_review_body |
function | Normalize review text for clients: decode HTML entities and preserve Audible guided questionnaire JSON ([{ type, question, id, answer }, …]) so the UI can render Q&A sections. Unrelated JSON arrays are left unchanged. |
parse_catalog_products |
function | Parses one Audible catalog answer into its titles, without any I/O. |
public_http_client |
function | Shared HTTP client for public metadata calls. |
region_tld |
function | Map marketplace / region code to Audible API TLD (AudioBookshelf regionMap). |
resolve_genre_category_id |
function | Map a genre display name to an Audible category_id under the Genres root. |
search_catalog_asins |
function | Search the public Audible catalog by title/author; returns ASINs (relevance order). |
search_catalog_by_genre_name |
function | Resolve an Audible Genres browse-node id for a category display name, then list products. |
search_catalog_by_narrator |
function | Narrator-focused public catalog search. |
search_catalog_by_series_asin |
function | List products in an Audible series by parent series ASIN (public catalog). |
search_catalog_by_series_name |
function | Keyword/title search, then keep products whose series name matches series. |
search_catalog_keywords |
function | Keyword catalog search (e.g. ISBN) — useful when title search misses a hit. |
search_catalog_products |
function | Public Audible catalog search returning product metadata (not just ASINs). |
search_catalog_products_ex |
function | Public catalog search with optional narrator, series ASIN, and/or category filters. |
search_catalog_products_ex2 |
function | Like search_catalog_products_ex with optional category_id and result cap. |
search_catalog_products_paged |
function | Paged public catalog search with explicit products_sort_by and optional rating. |
search_catalog_products_rich |
function | Same as search_catalog_products but requests list price / category ladders. |
search_catalog_storefront |
function | Storefront catalog search (GET /1.0/catalog/search) — the same index the Storefront catalog search (GET /1.0/catalog/search) — the same index the Audible website uses. |
search_similar_products |
function | Titles Audible lists as similar to one title (its "listeners also enjoyed" recommendations), from the public catalog. |
search_similar_products_at |
function | search_similar_products against a given catalog origin, such as a test server. |
is_valid_asin |
function | True when s (trimmed) has the shape of an Audible ASIN: ten ASCII letters or digits. |
Result |
type alias | Result alias for catalog lookups. |
pub struct CatalogProduct {
pub asin: String,
pub title: Option<String>,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_asin: Option<String>,
pub series_sequence: Option<String>,
pub cover_url: Option<String>,
pub subtitle: Option<String>,
pub description: Option<String>,
pub publisher: Option<String>,
pub length_minutes: Option<i64>,
pub published_at: Option<String>,
pub categories: Option<String>,
pub genre_roots: Vec<String>,
pub language: Option<String>,
pub isbn: Option<String>,
pub is_abridged: Option<bool>,
pub price_cents: Option<i64>,
pub currency: Option<String>,
pub price_label: Option<String>,
pub rating_overall: Option<f64>,
pub rating_count: Option<i64>,
pub is_explicit: Option<bool>,
}
One Audible catalog product (public search hit).
Fields
asin: Audible / Amazon ASIN when this edition is sold on Audible.title: Display title as shown on the storefront or library card.authors: Comma-separated author names when the storefront provides them.narrators: Comma-separated narrator names when known.series: Series name when the title belongs to a named series.series_asin: Parent series ASIN when the catalog returns series metadata.series_sequence: Series sequence / position when present (string form from Audible).cover_url: Cover URL fromproduct_imageswhen themediaresponse group is present.subtitle: Optional subtitle when the catalog distinguishes it from the title.description: Publisher summary / blurb (product_extended_attrs).publisher: Publisher imprint as reported by the catalog.length_minutes: Audiobook runtime in whole minutes when known.published_at: Publication date string from the catalog (ISO or storefront format).categories: Genre / subject labels (;-separated).genre_roots: The top-level genre of each of the title's genre ladders (Science Fiction & Fantasy,Children's Audiobooks), each once, in ladder order; empty when the catalog gave no ladders. UnlikeSelf::categories, which joins every rung, this tells an adult "Action & Adventure" from a children's one.language: BCP-47 / storefront language code (en,de, …) when known.isbn: The edition's ISBN as the catalog'sisbnattribute (inproduct_attrs) reports it, digits and a finalXonly;Nonewhen the catalog gives none or the value is not ten or thirteen of them. Audible gives one for many publisher titles, the same audio ISBN other stores list, so the host can tell their listings are one recording.is_abridged: Whether this edition is abridged, from the catalog'sformat_type(abridged/unabridged);Nonewhen it gave no format the parser knows.price_cents: List or deal price in integer cents ofSelf::currency.currency: ISO 4217 currency code for price fields (USD,EUR, …).price_label: Human-readable price string from the storefront (e.g.$14.95).rating_overall: Overall community rating when theratingresponse group is present.rating_count: Count of star ratings (rating.num_ratings) when present.is_explicit: Audible's adult flag (is_adult_product, inproduct_attrs):Some(true)for explicit content,Nonewhen the reply omits it.
Implements: Clone, Debug, PartialEq
pub struct CatalogRating {
pub overall: Option<f64>,
pub performance: Option<f64>,
pub story: Option<f64>,
pub num_ratings: Option<i64>,
pub num_reviews: Option<i64>,
}
Community ratings from a single Audible catalog product (response_groups=rating).
Kept off bulk Discover catalog calls (see CATALOG_RESPONSE_GROUPS); use from
title-detail paths only.
Fields
overall: Aggregate star rating across listeners.performance: Narration / performance sub-score.story: Story / content sub-score.num_ratings: Total number of ratings contributing to the averages.num_reviews: Total number of written reviews when distinct from ratings.
Implements: Clone, Debug, PartialEq
pub struct CatalogReview {
pub id: Option<String>,
pub title: Option<String>,
pub body: String,
pub author_name: Option<String>,
pub overall_rating: Option<i64>,
pub performance_rating: Option<i64>,
pub story_rating: Option<i64>,
pub submitted_at: Option<String>,
}
One customer review from Audible's public catalog reviews endpoint.
Fields
id: Stable identifier for this item.title: Display title as shown on the storefront or library card.body: Full review text from the storefront.author_name: Display name of the review author on the storefront.overall_rating: Overall star rating for this review when present.performance_rating: Narration sub-rating for this review when present.story_rating: Story sub-rating for this review when present.submitted_at: When the review was submitted (storefront timestamp string).
Implements: Clone, Debug, Eq, PartialEq
pub struct CatalogReviewsPage {
pub reviews: Vec<CatalogReview>,
pub page: u32,
pub page_size: usize,
pub has_more: bool,
pub sort_by: CatalogReviewsSort,
}
One page of helpful Audible customer reviews (public; no account).
Fields
reviews: Review rows on this page.page: 1-based page index for this reviews / list request.page_size: Maximum number of items returned in this page.has_more: When true, another page is available by incrementingSelf::page.sort_by: Remote sort key for reviews (most_helpful,most_recent, …).
Implements: Clone, Debug, Eq, PartialEq
pub enum CatalogError {
Http(String),
}
Failures talking to the public Audible catalog.
Variants
Http: The HTTP client could not be built, the request failed, or the response did not decode; the message says which.
Implements: Debug, Display, Error
pub enum CatalogList {
Products,
SimilarProducts,
}
Which product list of an Audible catalog answer to read.
Variants
Products:products, the list a search (/1.0/catalog/products,/1.0/catalog/search) answers with.SimilarProducts:similar_products, the list/1.0/catalog/products/{asin}/simsanswers with.
pub fn key(self) -> &'static str
The JSON key of this list in the answer's top-level object.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum CatalogReviewsSort {
MostHelpful,
MostRecent,
}
Audible catalog reviews sort (MostHelpful or MostRecent).
Variants
MostHelpful: Sort reviews by helpfulness (storefront default).MostRecent: Sort reviews by newest submission first.
pub fn as_str(self) -> &'static str
Returns the wire / FourCC string form of this value.
pub fn parse(raw: &str) -> Self
Parses this value from its wire string form.
raw- Stringrawfor this call.
Updated Self for chaining.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub fn catalog_origin(region: &str) -> String
The public catalog's origin for a marketplace, without a trailing slash
(https://api.audible.co.uk for uk).
region- Marketplace / region code (us,uk, …); an unknown code gets the US origin.
The origin to pass to fetch_products_by_asins.
pub async fn fetch_audible_catalog_rating(
http: &Client,
asin: &str,
region: &str,
) -> Result<Option<CatalogRating>>
Fetch Audible community ratings for one ASIN (public catalog; no account).
http-httpinput for this call.asin- Optional Audible / Amazon ASIN.region- Marketplace / region code (us,uk, …).
On success, the inner Option<CatalogRating> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn fetch_audible_catalog_reviews(
http: &Client,
asin: &str,
region: &str,
limit: usize,
) -> Result<Vec<CatalogReview>>
Fetch a short list of helpful Audible customer reviews (public; no account).
Convenience wrapper around fetch_audible_catalog_reviews_page (page 1).
limit is clamped to 1..=50 (Audible's reviews endpoint max).
http-httpinput for this call.asin- Optional Audible / Amazon ASIN.region- Marketplace / region code (us,uk, …).limit- Maximum number of results to return.
On success, the inner Vec<CatalogReview> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn fetch_audible_catalog_reviews_page(
http: &Client,
asin: &str,
region: &str,
page: u32,
page_size: usize,
sort_by: CatalogReviewsSort,
) -> Result<CatalogReviewsPage>
Paginated Audible catalog reviews (page is 1-based).
http-httpinput for this call.asin- Optional Audible / Amazon ASIN.region- Marketplace / region code (us,uk, …).page- Numericpagevalue for this call.page_size- Maximum items to return in this page.sort_by-sort_byinput for this call.
On success, the inner CatalogReviewsPage value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn fetch_products_by_asins(
http: &Client,
origin: &str,
asins: &[&str],
) -> Result<Vec<CatalogProduct>>
Looks titles up by ASIN in the public catalog, with their genre ladders.
http- Client frompublic_http_client.origin- Catalog origin without a trailing slash, fromcatalog_origin(or a test server).asins- ASINs to look up; values that are not ASINs are skipped.
The titles the catalog knows, in its order; none when no value is an ASIN.
Returns an error when the request fails or the answer is not JSON.
pub fn is_audible_podcast_product(p: &Value) -> bool
True for Audible podcast shows / episodes (content_type / delivery type).
p-pinput for this call.
true when the predicate holds.
pub fn normalize_region(region: &str) -> String
Normalize a marketplace string to an Audible / Audnexus region value.
region- Marketplace / region code (us,uk, …).
String result for this operation.
pub fn normalize_review_body(body: &str) -> String
Normalize review text for clients: decode HTML entities and preserve Audible
guided questionnaire JSON ([{ type, question, id, answer }, …]) so the UI
can render Q&A sections. Unrelated JSON arrays are left unchanged.
body- HTTP request body bytes.
String result for this operation.
pub fn parse_catalog_products(
body: &[u8],
list: CatalogList,
) -> Result<Vec<CatalogProduct>>
Parses one Audible catalog answer into its titles, without any I/O.
The bytes come from the store, so this is the boundary the
audible_catalog fuzz target drives. Rows that are podcasts or carry no
ASIN are dropped; an answer without the list (or whose list is not an
array) has no titles.
body- The answer body as the store sent it.list- Which product list to read.
The titles of the list, in the store's order.
Returns CatalogError::Http when the body is not JSON.
pub fn public_http_client() -> Result<Client>
Shared HTTP client for public metadata calls.
Built once per process and cloned, so every public lookup reuses one
connection pool (and its TLS connections) instead of handshaking per
call. The client holds no cookies and only a fixed User-Agent, so
sharing it carries nothing between calls; in a plugin guest it lives in
that guest's own process.
On success, the inner Client value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn region_tld(region: &str) -> &'static str
Map marketplace / region code to Audible API TLD (AudioBookshelf regionMap).
region- Marketplace / region code (us,uk, …).
&'static str result.
pub async fn resolve_genre_category_id(
http: &Client,
region: &str,
genre: &str,
) -> Result<Option<String>>
Map a genre display name to an Audible category_id under the Genres root.
Fetches GET …/catalog/categories?categories_num_levels=3&root=Genres, flattens
the tree, and picks the best case-insensitive name match (deeper nodes and
Science Fiction & Fantasy paths preferred; Children’s / Teen deprioritized).
http-httpinput for this call.region- Marketplace / region code (us,uk, …).genre- Stringgenrefor this call.
On success, the inner Option<String> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_asins(
http: &Client,
region: &str,
title: &str,
author: Option<&str>,
) -> Result<Vec<String>>
Search the public Audible catalog by title/author; returns ASINs (relevance order).
http-httpinput for this call.region- Marketplace / region code (us,uk, …).title- Display title.author- Stringauthorfor this call.
On success, the inner Vec<String> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_by_genre_name(
http: &Client,
region: &str,
genre: &str,
page: u32,
products_sort_by: &str,
limit: usize,
with_rating: bool,
) -> Result<Vec<CatalogProduct>>
Resolve an Audible Genres browse-node id for a category display name, then list products.
page is 1-based (Audible catalog convention), matching
search_catalog_products_paged.
http-httpinput for this call.region- Marketplace / region code (us,uk, …).genre- Stringgenrefor this call.page- Numericpagevalue for this call.products_sort_by- Stringproducts_sort_byfor this call.limit- Maximum number of results to return.with_rating- Boolean flagwith_rating.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_by_narrator(
http: &Client,
region: &str,
narrator: &str,
) -> Result<Vec<CatalogProduct>>
Narrator-focused public catalog search.
http-httpinput for this call.region- Marketplace / region code (us,uk, …).narrator- Stringnarratorfor this call.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_by_series_asin(
http: &Client,
region: &str,
series_asin: &str,
) -> Result<Vec<CatalogProduct>>
List products in an Audible series by parent series ASIN (public catalog).
http-httpinput for this call.region- Marketplace / region code (us,uk, …).series_asin- Stringseries_asinfor this call.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_by_series_name(
http: &Client,
region: &str,
series: &str,
limit: usize,
) -> Result<Vec<CatalogProduct>>
Keyword/title search, then keep products whose series name matches series.
http-httpinput for this call.region- Marketplace / region code (us,uk, …).series- Optional series name.limit- Maximum number of results to return.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_keywords(
http: &Client,
region: &str,
keywords: &str,
) -> Result<Vec<String>>
Keyword catalog search (e.g. ISBN) — useful when title search misses a hit.
http-httpinput for this call.region- Marketplace / region code (us,uk, …).keywords- Stringkeywordsfor this call.
On success, the inner Vec<String> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_products(
http: &Client,
region: &str,
title: &str,
author: Option<&str>,
keywords: Option<&str>,
) -> Result<Vec<CatalogProduct>>
Public Audible catalog search returning product metadata (not just ASINs).
Pass title and/or author and/or keywords. Empty title is allowed when
keywords or author alone are set.
http-httpinput for this call.region- Marketplace / region code (us,uk, …).title- Display title.author- Stringauthorfor this call.keywords- Stringkeywordsfor this call.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_products_ex(
http: &Client,
region: &str,
title: &str,
author: Option<&str>,
keywords: Option<&str>,
narrator: Option<&str>,
series_asin: Option<&str>,
rich: bool,
) -> Result<Vec<CatalogProduct>>
Public catalog search with optional narrator, series ASIN, and/or category filters.
http-httpinput for this call.region- Marketplace / region code (us,uk, …).title- Display title.author- Stringauthorfor this call.keywords- Stringkeywordsfor this call.narrator- Stringnarratorfor this call.series_asin- Stringseries_asinfor this call.rich- Boolean flagrich.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_products_ex2(
http: &Client,
region: &str,
title: &str,
author: Option<&str>,
keywords: Option<&str>,
narrator: Option<&str>,
series_asin: Option<&str>,
category_id: Option<&str>,
rich: bool,
num_results: usize,
) -> Result<Vec<CatalogProduct>>
Like search_catalog_products_ex with optional category_id and result cap.
Note: Audible's public catalog ignores language= query params; prefer
local re-rank on CatalogProduct::language after fetch.
http-httpinput for this call.region- Marketplace / region code (us,uk, …).title- Display title.author- Stringauthorfor this call.keywords- Stringkeywordsfor this call.narrator- Stringnarratorfor this call.series_asin- Stringseries_asinfor this call.category_id- Stringcategory_idfor this call.rich- Boolean flagrich.num_results- Numericnum_resultsvalue for this call.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_products_paged(
http: &Client,
region: &str,
title: &str,
author: Option<&str>,
keywords: Option<&str>,
narrator: Option<&str>,
series_asin: Option<&str>,
category_id: Option<&str>,
page: u32,
products_sort_by: &str,
rich: bool,
num_results: usize,
with_rating: bool,
) -> Result<Vec<CatalogProduct>>
Paged public catalog search with explicit products_sort_by and optional rating.
http-httpinput for this call.region- Marketplace / region code (us,uk, …).title- Display title.author- Stringauthorfor this call.keywords- Stringkeywordsfor this call.narrator- Stringnarratorfor this call.series_asin- Stringseries_asinfor this call.category_id- Stringcategory_idfor this call.page- Numericpagevalue for this call.products_sort_by- Stringproducts_sort_byfor this call.rich- Boolean flagrich.num_results- Numericnum_resultsvalue for this call.with_rating- Boolean flagwith_rating.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_products_rich(
http: &Client,
region: &str,
title: &str,
author: Option<&str>,
keywords: Option<&str>,
) -> Result<Vec<CatalogProduct>>
Same as search_catalog_products but requests list price / category ladders.
http-httpinput for this call.region- Marketplace / region code (us,uk, …).title- Display title.author- Stringauthorfor this call.keywords- Stringkeywordsfor this call.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_catalog_storefront(
http: &Client,
region: &str,
keywords: &str,
page: u32,
sort: &str,
rich: bool,
num_results: usize,
with_rating: bool,
) -> Result<Vec<CatalogProduct>>
Storefront catalog search (GET /1.0/catalog/search) — the same index the
Storefront catalog search (GET /1.0/catalog/search) — the same index the
Audible website uses.
Prefer this over search_catalog_products_paged for Discover keyword browse:
/catalog/products?keywords= frequently omits titles that still resolve via
/catalog/products/{asin} (e.g. English A Game of Thrones B002UZZ93G).
http-httpinput for this call.region- Marketplace / region code (us,uk, …).keywords- Stringkeywordsfor this call.page- Numericpagevalue for this call.sort- Sort field for the merged result set.rich- Boolean flagrich.num_results- Numericnum_resultsvalue for this call.with_rating- Boolean flagwith_rating.
On success, the inner Vec<CatalogProduct> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn search_similar_products(
http: &Client,
region: &str,
asin: &str,
num_results: usize,
) -> Result<Vec<CatalogProduct>>
Titles Audible lists as similar to one title (its "listeners also enjoyed" recommendations), from the public catalog.
Unlike a keyword search on the title, these are chosen by what listeners of the title go on to listen to, so a title shares no words with them by chance (a search for The Great Hunt returns hunting guides).
http- Client frompublic_http_client.region- Marketplace / region code (us,uk, …).asin- ASIN of the title to find neighbours of.num_results- Most titles to ask for (1 to 50).
The similar titles in Audible's order, without the title itself; none
when asin is not an ASIN.
Returns an error when the request fails or the answer is not JSON.
pub async fn search_similar_products_at(
http: &Client,
origin: &str,
asin: &str,
num_results: usize,
) -> Result<Vec<CatalogProduct>>
search_similar_products against a given catalog origin, such as a
test server.
http- Client frompublic_http_client.origin- Catalog origin without a trailing slash (https://api.audible.com).asin- ASIN of the title to find neighbours of.num_results- Most titles to ask for (1 to 50).
The similar titles in the store's order, without the title itself; none
when asin is not an ASIN.
Returns an error when the request fails or the answer is not JSON.
pub fn is_valid_asin(s: &str) -> bool
True when s (trimmed) has the shape of an Audible ASIN: ten ASCII
letters or digits.
Any ten-letter word also passes; callers that must tell a title from an
ASIN need a stricter check (see bookclerk_enrich::is_asin_title).
s- Candidate ASIN, possibly with surrounding whitespace.
pub type Result<T> = Result<T, CatalogError>;
Result alias for catalog lookups.
Generated from crates/bookclerk-audible-catalog at main · View as Markdown