lastfm-client

A modern, async Rust library for fetching and analyzing Last.fm user data with ease.

Version 2.0 introduces a brand new builder-pattern API with retry logic, rate limiting, and improved ergonomics, while maintaining 100% backward compatibility with the 1.x API.

🚀 New in v2.0

• 🎯 Specialized API Clients: RecentTracksClient, LovedTracksClient, TopTracksClient
• 🔧 Builder Pattern: Fluent, discoverable API design
• 📊 Built-in Analytics: Track analysis and statistics methods
• 💾 File Operations: Built-in save and export functionality
• 🎵 Currently Playing: Real-time track detection
• ⚡ Performance: Optimized HTTP client with retry logic
• 🔄 Backward Compatible: V1.x API still works (with deprecation warnings)

Installation

Add this to your Cargo.toml:

[dependencies]
lastfm-client = "2.0"

Features

V2.0 API (New!)

• Builder Pattern: Fluent, discoverable API design
• Automatic Retries: Configurable retry logic with exponential or linear backoff
• Rate Limiting: Prevent API abuse with built-in rate limiting
• Enhanced Error Handling: Rich error types with retry hints and context
• Testable: HTTP abstraction layer for easy mocking
• Type Safe: Leverages Rust's type system for compile-time guarantees

Data Fetching

• Async API Integration: Modern asynchronous Last.fm API communication
• Flexible Track Fetching: Get recent tracks, loved tracks, and top tracks with configurable limits
• Advanced Filtering: Time-based filtering (from/to timestamps) and period-based filtering for top tracks
• Extended Data Support: Fetch extended track information with additional artist details
• Efficient Pagination: Smart handling of Last.fm's pagination system with chunked concurrent requests

Analytics

• Comprehensive Statistics:
  • Total play counts
  • Artist-level analytics
  • Track-level analytics
  • Most played artists/tracks
  • Play count thresholds
• Custom Analysis: Extensible analysis framework with the TrackAnalyzable trait

Data Export

• Multiple Formats: Export data in JSON and CSV formats
• Timestamp-based Filenames: Automatic file naming with timestamps
• Organized Storage: Structured data directory management

Error Handling

• Robust Error Types: Custom error handling for API and file operations
• Graceful Failure Recovery: Proper handling of API and parsing errors

Configuration

Create a .env file in your project root:

LAST_FM_API_KEY=your_api_key_here

Usage

Choose between the v2.0 API (recommended for new projects) or the v1.x API (fully supported for existing projects).

---

V2.0 API (Recommended)

Quick Start

use lastfm_client::LastFmClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client with defaults (loads API key from LAST_FM_API_KEY env var)
    let client = LastFmClient::new()?;

    // Fetch recent tracks with builder pattern
    let tracks = client
        .recent_tracks("username")
        .limit(50)
        .fetch()
        .await?;

    println!("Fetched {} tracks", tracks.len());
    Ok(())
}

Alternative: Using Builder Pattern

use lastfm_client::LastFmClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client with custom configuration
    let client = LastFmClient::builder()
        .api_key("your_api_key")  // Optional: defaults to LAST_FM_API_KEY env var
        .timeout(Duration::from_secs(60))
        .retry_attempts(5)
        .build_client()?;

    // Use the client...
    Ok(())
}

Advanced Configuration

use lastfm_client::LastFmClient;
use std::time::Duration;

let client = LastFmClient::builder()
    .api_key("your_api_key")
    .user_agent("MyApp/1.0")
    .timeout(Duration::from_secs(60))
    .max_concurrent_requests(10)
    .retry_attempts(5)
    .rate_limit(10, Duration::from_secs(1))  // 10 requests per second
    .build_client()?;

Fetching Recent Tracks

// Limited tracks
let tracks = client
    .recent_tracks("username")
    .limit(100)
    .fetch()
    .await?;

// All available tracks
let all_tracks = client
    .recent_tracks("username")
    .unlimited()
    .fetch()
    .await?;

// Tracks from specific date
let since_timestamp = 1704067200; // Jan 1, 2024
let recent = client
    .recent_tracks("username")
    .since(since_timestamp)
    .fetch()
    .await?;

// Tracks between two dates
let from = 1704067200; // Jan 1, 2024
let to = 1706745600;   // Feb 1, 2024
let tracks = client
    .recent_tracks("username")
    .between(from, to)
    .fetch()
    .await?;

// Extended track information (includes full artist details)
let extended_tracks = client
    .recent_tracks("username")
    .limit(50)
    .extended()
    .fetch_extended()
    .await?;

// Check if user is currently playing
let currently_playing = client
    .recent_tracks("username")
    .check_currently_playing()
    .await?;

// Analyze tracks and get statistics
let stats = client
    .recent_tracks("username")
    .limit(100)
    .analyze(5)
    .await?;

// Fetch and save to file
let filename = client
    .recent_tracks("username")
    .limit(50)
    .fetch_and_save(FileFormat::Json, "my_tracks")
    .await?;

Fetching Loved Tracks

// Limited loved tracks
let loved_tracks = client
    .loved_tracks("username")
    .limit(50)
    .fetch()
    .await?;

// All loved tracks
let all_loved = client
    .loved_tracks("username")
    .unlimited()
    .fetch()
    .await?;

// Analyze loved tracks
let stats = client
    .loved_tracks("username")
    .analyze(1)
    .await?;

// Fetch and save loved tracks
let filename = client
    .loved_tracks("username")
    .fetch_and_save(FileFormat::Json, "loved_tracks")
    .await?;

Fetching Top Tracks

use lastfm_client::api::Period;

// Top tracks with period filter
let top_tracks = client
    .top_tracks("username")
    .limit(50)
    .period(Period::ThreeMonth)
    .fetch()
    .await?;

// All-time top tracks
let all_time_top = client
    .top_tracks("username")
    .unlimited()
    .period(Period::Overall)
    .fetch()
    .await?;

// Fetch and save top tracks
let filename = client
    .top_tracks("username")
    .limit(100)
    .period(Period::Month)
    .fetch_and_save(FileFormat::Json, "monthly_top")
    .await?;

Error Handling with Retry Hints

use lastfm_client::error::LastFmError;

match client.recent_tracks("username").limit(50).fetch().await {
    Ok(tracks) => println!("Success: {} tracks", tracks.len()),
    Err(e) => {
        if e.is_retryable() {
            if let Some(retry_after) = e.retry_after() {
                println!("Rate limited. Retry after {:?}", retry_after);
                tokio::time::sleep(retry_after).await;
                // Retry the request...
            }
        } else {
            eprintln!("Non-retryable error: {}", e);
        }
    }
}

---

Friendly error messages (Display vs Debug)

If you see output like MissingEnvVar("LAST_FM_API_KEY"), the error is being printed with Debug formatting ({:?}) somewhere. This library implements friendly Display messages (via #[error("...")]), so prefer Display ({}) when printing errors.

Use an explicit main error handler to guarantee Display formatting:

use dotenvy::dotenv;
use lastfm_client::LastFmClient;

#[tokio::main]
async fn main() {
    if let Err(err) = run().await {
        eprintln!("Error: {err}"); // Display, not Debug
        std::process::exit(1);
    }
}

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    dotenv().ok();

    let client = LastFmClient::builder()
        .from_env()? // Missing LAST_FM_API_KEY → friendly message via Display
        .build_client()?;

    let tracks = client.recent_tracks("username").limit(50).fetch().await?;
    println!("Fetched {} tracks", tracks.len());
    Ok(())
}

Tips:

• Use eprintln!("{}", err) or eprintln!("Error: {err}") (Display), avoid {:?}/{:#?} (Debug).
• If you keep fn main() -> Result<…>, your runtime may show Debug output on failure. The explicit handler above guarantees Display.
• This applies to all errors from this library, including configuration errors like missing LAST_FM_API_KEY.

---

V1.x API (Legacy, Deprecated but Fully Supported)

⚠️ Deprecation Notice: The V1.x API methods are now deprecated and will show deprecation warnings when used. We recommend migrating to the new V2.0 API clients for better performance, features, and maintainability. The V1.x API will continue to work indefinitely for backward compatibility.

Basic Example

use lastfm_client::{LastFMHandler, TrackLimit, Url};

#[tokio::main]
async fn main() {
    // Create a new handler
    let base_url = Url::new("https://ws.audioscrobbler.com/2.0/");
    let handler = LastFMHandler::new(base_url, "username");

    // Fetch recent tracks
    let recent_tracks = handler
        .get_user_recent_tracks(TrackLimit::Limited(50))
        .await
        .unwrap();

    // Analyze the tracks
    let stats = AnalysisHandler::analyze_tracks(&recent_tracks, 10);
    AnalysisHandler::print_analysis(&stats);
}

Fetching & Saving Example

use lastfm_client::file_handler::FileFormat;
use lastfm_client::lastfm_handler::{LastFMHandler, TrackLimit};
use dotenv::dotenv;

#[tokio::main]
async fn main() {
    // Load environment variables
    dotenv().ok();

    // Create a new handler for user "tom_planche"
    let handler = LastFMHandler::new("tom_planche");

    // Fetch all tracks and save them to a JSON file named "all_scrobbles"
    let filename = handler
        .get_and_save_recent_tracks(TrackLimit::Unlimited, FileFormat::Json, "all_scrobbles")
        .await;

    match filename {
        Ok(filename) => println!("File saved as: {}", filename),
        Err(e) => eprintln!("Error: {}", e),
    }
}

This example shows how to:

• Load environment variables (including your Last.fm API key)
• Create a handler for a specific Last.fm user
• Fetch all scrobbled tracks (using TrackLimit::Unlimited)
• Save them to a JSON file with a custom name prefix
• Handle potential errors during the process

Analytics Example

use lastfm_client::{AnalysisHandler, FileHandler, FileFormat};

// Save and analyze tracks
let filename = handler
    .get_and_save_recent_tracks(TrackLimit::Limited(100), FileFormat::JSON)
    .await?;

let stats = AnalysisHandler::analyze_file::<RecentTrack>(Path::new(&filename), 10)?;
AnalysisHandler::print_analysis(&stats);

Advanced Fetching with Options

The library provides comprehensive *_with_options methods that expose all available Last.fm API parameters:

Recent Tracks with Options

use lastfm_client::{LastFMHandler, TrackLimit};

let handler = LastFMHandler::new("username").unwrap();

// Get last 50 tracks (basic usage)
let tracks = handler
    .get_user_recent_tracks_with_options(Some(50), None, None, false)
    .await?;

// Get tracks from the last week
let one_week_ago = (Utc::now() - Duration::days(7)).timestamp();
let tracks = handler
    .get_user_recent_tracks_with_options(None, Some(one_week_ago), None, false)
    .await?;

// Get tracks between two dates with extended info
let tracks = handler
    .get_user_recent_tracks_with_options(None, Some(start), Some(end), true)
    .await?;

// Get extended track information (alternative method)
let extended_tracks = handler
    .get_user_recent_tracks_extended(Some(100), None, None)
    .await?;

Recent Tracks Between Dates

Convenience methods for fetching all tracks within a specific time range:

use lastfm_client::LastFMHandler;
use chrono::{Utc, Duration, TimeZone};

let handler = LastFMHandler::new("username").unwrap();

// Get all tracks from January 2024
let start = Utc.with_ymd_and_hms(2024, 1, 1, 0, 0, 0).unwrap().timestamp();
let end = Utc.with_ymd_and_hms(2024, 2, 1, 0, 0, 0).unwrap().timestamp();
let tracks = handler
    .get_user_recent_tracks_between(start, end, false)
    .await?;

// Get all tracks from last week with extended info
let one_week_ago = (Utc::now() - Duration::days(7)).timestamp();
let now = Utc::now().timestamp();
let tracks = handler
    .get_user_recent_tracks_between(one_week_ago, now, true)
    .await?;

// Get all tracks between dates with extended information
let tracks = handler
    .get_user_recent_tracks_between_extended(start, end)
    .await?;

Top Tracks with Options

use lastfm_client::{LastFMHandler, Period, TrackLimit};

let handler = LastFMHandler::new("username").unwrap();

// Get all-time top 50 tracks
let tracks = handler
    .get_user_top_tracks_with_options(Some(50), None)
    .await?;

// Get top tracks from the last week
let tracks = handler
    .get_user_top_tracks_with_options(None, Some(Period::Week))
    .await?;

// Get top 100 tracks from the last 3 months
let tracks = handler
    .get_user_top_tracks_with_options(Some(100), Some(Period::ThreeMonth))
    .await?;

Loved Tracks with Options

use lastfm_client::{LastFMHandler, TrackLimit};

let handler = LastFMHandler::new("username").unwrap();

// Get all loved tracks
let tracks = handler
    .get_user_loved_tracks_with_options(None)
    .await?;

// Get first 100 loved tracks
let tracks = handler
    .get_user_loved_tracks_with_options(Some(100))
    .await?;

Available Period Options

When using get_user_top_tracks_with_options, you can filter by these time periods:

• Period::Overall - All time (default if None)
• Period::Week - Last 7 days
• Period::Month - Last month
• Period::ThreeMonth - Last 3 months
• Period::SixMonth - Last 6 months
• Period::TwelveMonth - Last 12 months

Migration Guide (v1.x → v2.0)

The v2.0 API is completely optional and backward compatible. You can migrate gradually or continue using the v1.x API indefinitely (though it will show deprecation warnings).

Before (v1.x)

// Multiple methods for different use cases
let handler = LastFMHandler::new("username")?;

// Limited tracks
handler.get_user_recent_tracks(Some(100))?;

// With date filtering
handler.get_user_recent_tracks_with_options(Some(50), Some(from), Some(to), true)?;

// Extended information
handler.get_user_recent_tracks_extended(Some(100), None, None)?;

// Between dates
handler.get_user_recent_tracks_between(from, to, false)?;

// Top tracks
handler.get_user_top_tracks(Some(50), Some(Period::ThreeMonth))?;

// Loved tracks
handler.get_user_loved_tracks(Some(100))?;

After (v2.0)

use lastfm_client::LastFmClient;

// Create client with defaults (loads API key from environment)
let client = LastFmClient::new()?;

// Limited tracks
client.recent_tracks("username").limit(100).fetch().await?;

// With date filtering
client.recent_tracks("username").limit(50).between(from, to).fetch().await?;

// Extended information
client.recent_tracks("username").limit(100).fetch_extended().await?;

// Between dates
client.recent_tracks("username").between(from, to).fetch().await?;

// Top tracks
client.top_tracks("username").limit(50).period(Period::ThreeMonth).fetch().await?;

// Loved tracks
client.loved_tracks("username").limit(100).fetch().await?;

Key Benefits of v2.0

1. Simpler API: One method instead of 6+ variants
2. Discoverable: Builder pattern makes options obvious
3. Automatic Retries: Built-in exponential backoff
4. Rate Limiting: Prevent API throttling
5. Better Errors: Rich error types with retry hints
6. Testable: Mock HTTP client for testing

---

API Methods Reference

V2.0 API

Client Creation

use lastfm_client::LastFmClient;

// Simple: with defaults (loads API key from LAST_FM_API_KEY env var)
let client = LastFmClient::new()?;

// With custom configuration
let client = LastFmClient::builder()
    .api_key("your_key")
    .retry_attempts(5)
    .rate_limit(10, Duration::from_secs(1))
    .build_client()?;

Recent Tracks

client.recent_tracks("username")
    .limit(u32)              // Limit number of tracks
    .unlimited()             // Fetch all available tracks
    .since(i64)              // Tracks since timestamp
    .between(i64, i64)       // Tracks between two timestamps
    .extended()              // Include extended info
    .fetch()                 // Execute and get Vec<RecentTrack>
    .fetch_extended()        // Execute and get Vec<RecentTrackExtended>
    .check_currently_playing() // Check if currently playing
    .analyze(usize)          // Analyze tracks and get statistics
    .analyze_and_print(usize) // Analyze and print statistics
    .fetch_and_save(format, prefix) // Fetch and save to file
    .fetch_extended_and_save(format, prefix) // Fetch extended and save

Loved Tracks

client.loved_tracks("username")
    .limit(u32)              // Limit number of tracks
    .unlimited()             // Fetch all available tracks
    .fetch()                 // Execute and get Vec<LovedTrack>
    .analyze(usize)          // Analyze tracks and get statistics
    .analyze_and_print(usize) // Analyze and print statistics
    .fetch_and_save(format, prefix) // Fetch and save to file

Top Tracks

client.top_tracks("username")
    .limit(u32)              // Limit number of tracks
    .unlimited()             // Fetch all available tracks
    .period(Period)          // Time period filter
    .fetch()                 // Execute and get Vec<TopTrack>
    .fetch_and_save(format, prefix) // Fetch and save to file

V1.x API (Deprecated)

⚠️ All V1.x methods are deprecated and will show deprecation warnings. Use the V2.0 API clients instead.

Recent Tracks Methods

Method	Parameters	Returns	Description	Status
get_user_recent_tracks	limit	Vec<RecentTrack>	Simple method to fetch recent tracks	⚠️ Deprecated
get_user_recent_tracks_with_options	limit, from, to, extended	Vec<RecentTrack>	Full control over all API parameters	⚠️ Deprecated
get_user_recent_tracks_extended	limit, from, to	Vec<RecentTrackExtended>	Fetch recent tracks with extended info	⚠️ Deprecated
get_user_recent_tracks_since	from, to, limit	Vec<RecentTrack>	Fetch tracks since a timestamp	⚠️ Deprecated
get_user_recent_tracks_between	from, to, extended	Vec<RecentTrack>	Fetch all tracks between two dates	⚠️ Deprecated
get_user_recent_tracks_between_extended	from, to	Vec<RecentTrackExtended>	Fetch all tracks between dates with extended info	⚠️ Deprecated

Top Tracks Methods

Method	Parameters	Returns	Description	Status
get_user_top_tracks	limit, period	Vec<TopTrack>	Simple method to fetch top tracks	⚠️ Deprecated
get_user_top_tracks_with_options	limit, period	Vec<TopTrack>	Full control over all API parameters	⚠️ Deprecated

Loved Tracks Methods

Method	Parameters	Returns	Description	Status
get_user_loved_tracks	limit	Vec<LovedTrack>	Simple method to fetch loved tracks	⚠️ Deprecated
get_user_loved_tracks_with_options	limit	Vec<LovedTrack>	Full control over all API parameters	⚠️ Deprecated
get_user_loved_tracks_since	timestamp, limit	Vec<LovedTrack>	Fetch loved tracks since a timestamp	⚠️ Deprecated

Helper Methods

Method	Parameters	Returns	Description
get_and_save_recent_tracks	limit, format, filename_prefix	Result<String>	Fetch and save recent tracks to file
get_and_save_loved_tracks	limit, format	Result<String>	Fetch and save loved tracks to file
export_recent_play_counts	limit	Result<String>	Export play counts for recent tracks
update_recent_play_counts	limit, file_path	Result<String>	Update play counts in existing file
is_currently_playing	-	Result<Option<RecentTrack>>	Check if user is currently playing
update_currently_listening	file_path	Result<Option<RecentTrack>>	Update currently listening file

Parameter Types

• limit: impl Into<TrackLimit> - Use Some(n) for limited tracks, None or TrackLimit::Unlimited for all
• from/to: Option<i64> - Unix timestamps in seconds
• extended: bool - Whether to fetch extended track information
• period: Option<Period> - Time period filter (Week, Month, ThreeMonth, etc.)
• format: FileFormat - FileFormat::Json or FileFormat::Csv

Testing

Run the test suite:

cargo test

The v2.0 API includes extensive test coverage with mock HTTP clients for reliable testing.

Advanced Features (v2.0)

Retry Logic

Configure automatic retries with exponential or linear backoff:

use lastfm_client::{LastFmClient, client::retry::RetryPolicy};
use std::time::Duration;

// Exponential backoff: 100ms → 200ms → 400ms → 800ms
let client = LastFmClient::builder()
    .api_key("your_key")
    .retry_attempts(5)
    .build_client()?;

// Custom retry policy
let policy = RetryPolicy::exponential(3)
    .with_base_delay(Duration::from_millis(200))
    .with_max_delay(Duration::from_secs(10));

Rate Limiting

Prevent API throttling with sliding window rate limiting:

use std::time::Duration;

let client = LastFmClient::builder()
    .api_key("your_key")
    .rate_limit(10, Duration::from_secs(1))  // 10 requests per second
    .build_client()?;

Testing with Mocks

Use mock HTTP clients for testing:

use lastfm_client::client::http::MockClient;
use std::collections::HashMap;

let mut responses = HashMap::new();
responses.insert(
    "test_url".to_string(),
    serde_json::json!({"recenttracks": {"track": []}}),
);

let mock_client = MockClient::new(responses);
// Use mock_client in your tests

Architecture (v2.0)

The v2.0 API is built with a modular, testable architecture:

src/
├── client/
│   ├── client.rs           # Main LastFmClient entry point
│   ├── http.rs             # HTTP abstraction (trait + implementations)
│   ├── retry.rs            # Retry logic with backoff strategies
│   └── rate_limiter.rs     # Rate limiting with sliding window
├── api/
│   └── recent_tracks.rs    # RecentTracksClient with builder pattern
├── types/
│   ├── tracks.rs           # Track type definitions
│   └── period.rs           # Period and TrackLimit enums
├── config.rs               # Configuration with builder
└── error.rs                # Rich error types with retry hints

Key Design Principles

• Trait-based HTTP abstraction: Easy to test with mocks
• Builder patterns: Fluent, discoverable APIs
• Type safety: Leverages Rust's type system
• Zero-cost abstractions: No runtime overhead
• Backward compatibility: v1.x API remains fully functional

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with Rust and powered by the Last.fm API.