Skip to main content
The ArchiveApi class provides methods to query the Archive.org API for LibriVox audiobooks with support for language filtering, genre categorization, and search functionality.

​
Overview

This service handles:
  • Fetching latest, most viewed, and most downloaded audiobooks
  • Genre-based filtering with multi-language support
  • Search functionality with language preferences
  • HTTP caching with ETags and conditional requests
  • Multi-language subject indexing for improved categorization
Source: lib/resources/archive_api.dart

​
Public Methods

​
getLatestAudiobook

Fetches the most recently added audiobooks from the LibriVox collection.
​
page
int
required
Page number for pagination (1-based)
​
rows
int
required
Number of results per page
Returns: Future<Either<String, List<Audiobook>>> Example: 
final archiveApi = ArchiveApi();
final result = await archiveApi.getLatestAudiobook(1, 20);

result.fold(
  (error) => print('Error: $error'),
  (audiobooks) => print('Found ${audiobooks.length} audiobooks'),
);

​
getMostViewedWeeklyAudiobook

Retrieves audiobooks sorted by weekly view count.
​
page
int
required
Page number for pagination
​
rows
int
required
Number of results per page
Returns: Future<Either<String, List<Audiobook>>> Example: 
final result = await archiveApi.getMostViewedWeeklyAudiobook(1, 20);

​
getMostDownloadedEverAudiobook

Fetches audiobooks sorted by total download count.
​
page
int
required
Page number for pagination
​
rows
int
required
Number of results per page
Returns: Future<Either<String, List<Audiobook>>> Example: 
final result = await archiveApi.getMostDownloadedEverAudiobook(1, 20);

​
getAudiobooksByGenre

Fetches audiobooks filtered by genre with support for multi-language subjects.
​
genre
String
required
Genre identifier (e.g., ‘mystery’, ‘scifi’, ‘romance’). Supports OR queries.
​
page
int
required
Page number for pagination
​
rows
int
required
Number of results per page
​
sortBy
String
required
Sort field (e.g., ‘downloads’, ‘week’, ‘addeddate’)
Returns: Future<Either<String, List<Audiobook>>> Example: 
final result = await archiveApi.getAudiobooksByGenre(
  'mystery OR crime',
  1,
  20,
  'downloads',
);

​
getAudiobookFiles

Retrieves the audio files and metadata for a specific audiobook.
​
identifier
String
required
Archive.org identifier for the audiobook
Returns: Future<Either<String, List<AudiobookFile>>> The method extracts:
  • Audio track files with original source
  • High-quality cover images (JPEG format)
  • Track numbers and metadata
Example: 
final result = await archiveApi.getAudiobookFiles('pride_prejudice_librivox');

result.fold(
  (error) => print('Error: $error'),
  (files) {
    for (final file in files) {
      print('Track ${file.track}: ${file.title}');
    }
  },
);

​
searchAudiobook

Searches for audiobooks using a free-form query string with language filtering.
​
searchQuery
String
required
Search terms (will be URI encoded)
​
page
int
required
Page number for pagination
​
rows
int
required
Number of results per page
Returns: Future<Either<String, List<Audiobook>>> Example: 
final result = await archiveApi.searchAudiobook('Jane Austen', 1, 20);

​
Language Support

The ArchiveApi automatically applies language filters based on user preferences stored in Hive (language_prefs_box). Supported languages include:
  • English (en), German (de), Spanish (es), French (fr)
  • Dutch (nl), Portuguese (pt), Italian (it), Russian (ru)
  • Greek (el), Japanese (ja), Polish (pl), Chinese (zh)
  • Hebrew (he), Latin (la), Finnish (fi), Swedish (sv)
  • Catalan (ca), Danish (da), Esperanto (eo)
  • And more (see _langAliases mapping in source)

​
HTTP Caching

The service implements HTTP caching with:
  • ETag-based conditional requests
  • Last-Modified headers
  • 15-minute staleness window
  • LRU cache eviction (max 100 entries)

​
Genre Filtering

Genre filtering uses comprehensive regex-based category filters across multiple languages. Available genres include:
  • war, adventure, biography, children, comedy
  • crime, fantasy, horror, love, mystery
  • philosophy, poem, religion, romance, scifi
Each genre is mapped to subject keywords in 20+ languages for accurate cross-lingual discovery.

​
Static Methods

​
dispose

Closes the HTTP client connection. Should be called when the app shuts down. 
ArchiveApi.dispose();

Build docs developers (and LLMs) love

Get started for freeTalk to us