UnixTime Utilities

UnixTime Utilities

The UnixTime class helps you work with Unix timestamps (seconds, UTC). Useful for endpoints like track.scrobble and user.getWeeklyAlbumChart that need timestamps.

Basic Usage

import io.github.rubeneekhof.lastfm.util.UnixTime;

// Get current timestamp
long now = UnixTime.now();

// Convert ISO-8601 date string (yyyy-MM-dd) to timestamp
long timestamp = UnixTime.at("2024-01-15");

// Convert LocalDate to timestamp
long timestamp = UnixTime.of(LocalDate.of(2024, 1, 15));

// Get timestamp for N days ago
long oneWeekAgo = UnixTime.daysAgo(7);

// Create a date range (useful for weekly charts)
UnixTime.Range lastWeek = UnixTime.lastDays(7);

Using with Scrobbling

// Scrobble a track from 5 minutes ago
Scrobble scrobble = Scrobble.builder()
    .artist("Radiohead")
    .track("Creep")
    .timestamp(UnixTime.now() - 300) // 5 minutes ago
    .build();

// Or scrobble from a specific date
Scrobble scrobble = Scrobble.builder()
    .artist("The Beatles")
    .track("Hey Jude")
    .timestamp(UnixTime.at("2024-01-15"))
    .build();

Using with Weekly Charts

// Get last 7 days chart
var range = UnixTime.lastDays(7);
WeeklyAlbumChart chart = client.users().getWeeklyAlbumChart("RubenJ01", range.from(), range.to());

// Or with specific dates
long from = UnixTime.at("2024-01-15");
long to = UnixTime.at("2024-01-22");
WeeklyAlbumChart chart = client.users().getWeeklyAlbumChart("RubenJ01", from, to);

API Reference

Static Methods

• UnixTime.now() - Returns current Unix timestamp in seconds (UTC)
• UnixTime.at(String isoDate) - Converts ISO-8601 date string (yyyy-MM-dd) to timestamp
• UnixTime.of(LocalDate date) - Converts LocalDate to timestamp at start of day (UTC)
• UnixTime.of(LocalDateTime dateTime) - Converts LocalDateTime to timestamp (UTC)
• UnixTime.daysAgo(int days) - Returns timestamp for N days ago
• UnixTime.lastDays(int days) - Returns a Range for the last N days

Range Type

UnixTime.Range is a record for timestamp ranges:

UnixTime.Range range = UnixTime.lastDays(7);
long start = range.from();  // Start timestamp
long end = range.to();      // End timestamp