Pagination

Pagination

Many Last.fm API endpoints return paginated results. The client provides convenient pagination helpers to make working with these results easier.

Quick Start

The pagination helpers are available on endpoints that support pagination. For example, artist search:

for (Artist artist : client.artists().searchPaged("Low").iterateAll()) {
    System.out.println(artist.name());
}

List<Artist> artists = client.artists().searchPaged("Low").toList(100);

client.artists().searchPaged("Low").stream()
    .filter(artist -> artist.stats() != null && artist.stats().listeners() > 1000000)
    .forEach(System.out::println);

Manual Pagination

You can still manually request specific pages if you need more control:

Page<Artist> page = client.artists().searchPaged("Low").page(2);
System.out.println("Page " + page.page() + " of " + page.totalPages().orElse(0));
System.out.println("Items: " + page.size());

if (page.hasNext()) {
    System.out.println("More pages available");
}

Page Object

The Page<T> object provides:

• items() - The items on this page
• page() - Current page number (1-based)
• pageSize() - Number of items per page
• totalPages() - Total number of pages (Optional, if available)
• totalItems() - Total number of items (Optional, if available)
• hasNext() - Whether there's a next page
• hasPrevious() - Whether there's a previous page
• nextPage() - Next page number (Optional)
• previousPage() - Previous page number (Optional)
• isEmpty() - Whether the page is empty
• size() - Number of items on this page

Pagination Methods

Iterate All Pages

Iterate over all items across all pages:

for (Artist artist : client.artists().searchPaged("Low").iterateAll()) {
    // process artist
}

Limit Results

Get up to a maximum number of items:

for (Artist artist : client.artists().searchPaged("Low").limit(50)) {
    // process up to 50 artists
}

Stream Results

Stream all results (useful for functional-style processing):

client.artists().searchPaged("Low").stream()
    .map(Artist::name)
    .filter(name -> name.startsWith("A"))
    .forEach(System.out::println);

Collect to List

Collect all results into a list:

List<Artist> allArtists = client.artists().searchPaged("Low").toList();

List<Artist> first100 = client.artists().searchPaged("Low").toList(100);

Custom Page Size

You can specify a custom page size:

ArtistSearchPagination pagination = client.artists().searchPaged("Low", 30);
List<Artist> artists = pagination.toList(100);

Advanced Usage

For more advanced scenarios, you can use the PaginationHelper utility class directly:

import io.github.rubeneekhof.lastfm.util.pagination.PaginationHelper;
import io.github.rubeneekhof.lastfm.util.pagination.PageFetcher;
import io.github.rubeneekhof.lastfm.util.pagination.Page;
import java.util.Optional;

PageFetcher<Artist> fetcher = pageNum -> {
    ArtistSearchResult result = client.artists().search("Low", 30, pageNum);
    int totalPages = result.itemsPerPage() > 0
        ? (int) Math.ceil((double) result.totalResults() / result.itemsPerPage())
        : 0;
    return new Page<>(
        result.artists(),
        pageNum,
        result.itemsPerPage(),
        Optional.of(totalPages),
        Optional.of(result.totalResults())
    );
};

List<Artist> artists = PaginationHelper.collectItems(fetcher, 200);

Notes

• Pagination helpers automatically handle fetching subsequent pages
• Results are fetched lazily (only when needed)
• The iterator will stop when it reaches the last page or hits a limit
• Manual pagination is still available for advanced use cases
• Not all endpoints support pagination metadata (totalPages, totalItems may be empty)