Skip to main content

​
Overview

The SearchExtractor class extracts search results from streaming services. It extends ListExtractor<InfoItem> and provides methods to retrieve search results with pagination, search suggestions, and meta information. Package: org.schabi.newpipe.extractor.search Extends: ListExtractor<InfoItem>

​
Constructor

​
service
StreamingService
required
The streaming service this extractor belongs to
​
linkHandler
SearchQueryHandler
required
The search query handler containing the search query and filters

​
Base Methods (Inherited from Extractor)

​
getId()

public String getId() throws ParsingException
Returns the unique identifier for this search.
​
return
String
The search identifier

​
getName()

public String getName() throws ParsingException
Returns the search query string.
​
return
String
The search query (same as getSearchString())

​
getUrl()

public String getUrl() throws ParsingException
Returns the URL for this search.
​
return
String
The search URL

​
getOriginalUrl()

public String getOriginalUrl() throws ParsingException
Returns the original URL as provided.
​
return
String
The original URL

​
getBaseUrl()

public String getBaseUrl() throws ParsingException
Returns the base URL of the service.
​
return
String
The base URL

​
fetchPage()

public void fetchPage() throws IOException, ExtractionException
Fetches the search results page. Must be called before accessing other data methods.

​
getService()

public StreamingService getService()
Returns the streaming service this extractor belongs to.
​
return
StreamingService
The associated streaming service

​
getServiceId()

public int getServiceId()
Returns the numeric ID of the streaming service.
​
return
int
The service ID

​
List Extraction Methods (Inherited from ListExtractor)

​
getInitialPage()

public abstract InfoItemsPage<InfoItem> getInitialPage() throws IOException, ExtractionException
Returns the first page of search results.
​
return
InfoItemsPage<InfoItem>
Page object containing initial results and next page reference

​
getPage()

public abstract InfoItemsPage<InfoItem> getPage(Page page) throws IOException, ExtractionException
Returns a specific page of search results.
​
page
Page
required
The page reference obtained from a previous page’s getNextPage() method
​
return
InfoItemsPage<InfoItem>
Page object containing results and next page reference

​
Search-Specific Methods

​
getSearchString()

public String getSearchString()
Returns the search query string.
​
return
String
The search query used for this search

​
getSearchSuggestion()

public abstract String getSearchSuggestion() throws ParsingException
Returns a search suggestion or corrected query provided by the service.
​
return
String
Suggested search query, corrected query if isCorrectedSearch() is true, or empty string

​
isCorrectedSearch()

public abstract boolean isCorrectedSearch() throws ParsingException
Returns whether the search was automatically corrected by the service. For example, searching for “pewdeipie” on YouTube returns results for “pewdiepie”.
​
return
boolean
true if the search was corrected, false otherwise

​
getMetaInfo()

public abstract List<MetaInfo> getMetaInfo() throws ParsingException
Returns additional meta information about the search results. For example, searching for “Covid-19” on YouTube shows a WHO information box.
​
return
List<MetaInfo>
List of meta information objects, or empty list if unavailable

​
getLinkHandler()

public SearchQueryHandler getLinkHandler()
Returns the search query handler (type-safe override).
​
return
SearchQueryHandler
The search query handler for this extractor

​
Localization Methods

​
forceLocalization()

public void forceLocalization(Localization localization)
Forces a specific localization for this extractor.
​
localization
Localization
required
The localization to use

​
forceContentCountry()

public void forceContentCountry(ContentCountry contentCountry)
Forces a specific content country for this extractor.
​
contentCountry
ContentCountry
required
The content country to use

​
NothingFoundException

The SearchExtractor.NothingFoundException is thrown when a search returns no results. 
public static class NothingFoundException extends ExtractionException
​
message
String
required
Error message describing the exception

​
Usage Example

StreamingService service = NewPipe.getService("YouTube");
SearchQueryHandler queryHandler = service.getSearchQHFactory()
    .fromQuery("NewPipe Extractor");
SearchExtractor extractor = service.getSearchExtractor(queryHandler);

// Fetch the page first
extractor.fetchPage();

// Get search information
String searchQuery = extractor.getSearchString();
String suggestion = extractor.getSearchSuggestion();
boolean corrected = extractor.isCorrectedSearch();

// Get meta info (e.g., COVID-19 warnings)
List<MetaInfo> metaInfo = extractor.getMetaInfo();

// Get first page of results
InfoItemsPage<InfoItem> initialPage = extractor.getInitialPage();
List<InfoItem> results = initialPage.getItems();

// Process results (can be streams, channels, or playlists)
for (InfoItem item : results) {
    if (item instanceof StreamInfoItem) {
        StreamInfoItem stream = (StreamInfoItem) item;
        System.out.println("Video: " + stream.getName());
    } else if (item instanceof ChannelInfoItem) {
        ChannelInfoItem channel = (ChannelInfoItem) item;
        System.out.println("Channel: " + channel.getName());
    } else if (item instanceof PlaylistInfoItem) {
        PlaylistInfoItem playlist = (PlaylistInfoItem) item;
        System.out.println("Playlist: " + playlist.getName());
    }
}

// Get next page
Page nextPage = initialPage.getNextPage();
if (nextPage != null) {
    InfoItemsPage<InfoItem> page = extractor.getPage(nextPage);
    // Process next page results...
}

​
Search with Filters

StreamingService service = NewPipe.getService("YouTube");
SearchQueryHandler queryHandler = service.getSearchQHFactory()
    .fromQuery("NewPipe", 
               Collections.singletonList("videos"),  // Filter: videos only
               "");                                   // Sort filter
SearchExtractor extractor = service.getSearchExtractor(queryHandler);

extractor.fetchPage();
InfoItemsPage<InfoItem> results = extractor.getInitialPage();

​
InfoItemsPage Object

The InfoItemsPage returned by getInitialPage() and getPage() contains:
​
items
List<InfoItem>
The list of search result items (can be StreamInfoItem, ChannelInfoItem, or PlaylistInfoItem)
​
nextPage
Page
Reference to the next page, or null if this is the last page
​
errors
List<Throwable>
Any errors that occurred during extraction of this page

​
Notes

  • Always call fetchPage() before accessing search results
  • Search results can contain mixed types (videos, channels, playlists)
  • Use isCorrectedSearch() to detect when the service modified your query
  • The getSearchSuggestion() method provides alternative search terms or the corrected query
  • Some services may provide meta information boxes for certain search terms
  • Handle NothingFoundException when no results are found

Build docs developers (and LLMs) love

Get started for freeTalk to us