Main Concepts

InstantSearch Android is a library providing widgets and helpers to help you build the best instant-search experience on Android with Algolia. It is built on top of Algolia’s Android API Client to provide you a high-level solution to quickly build various search interfaces.

In this guide, you will learn the key concepts of InstantSearch Android.


The main component of InstantSearch Android is the Searcher, which will wrap an Algolia API Client and provide a level of abstraction over it.

The Searcher is responsible of all search requests: when Searcher#search() is called, the Searcher will fire a request with the current query, and will forward the search results to its listeners.


A listener is an object implementing one or more of the following interfaces, that will be called after each search request:

You can add a listener to a Searcher by calling Searcher#register{Results,Error}Listener.

To avoid leaking memory, you should call Searcher#destroy() in your Activity/Fragment’s onDestroy method to release existing listeners.


The Searcher is UI-agnostic, and only communicates with its listeners. On top of it, we provide you a component which will link it to your user interface: InstantSearch.

InstantSearch will use the Searcher to react to changes in your application’s interface, like when your user types a new query or interacts with Widgets.

Linked to a SearchView, it will watch its content to send any new query to the Searcher. When the query’s results arrive, InstantSearch will forward them to its widgets.


Widgets are the UI building blocks of InstantSearch Android, linked together by an InstantSearch to help you build instant-search interfaces. We provide some universal widgets such as the SearchBox, the Hits or the RefinementList, and you can easily create new ones by implementing one or several of the widget interfaces:


InstantSearch comes with an event system that lets you react during the lifecycle of a search query:

  • when a query is fired via a SearchEvent(Query query, int requestSeqNumber)
  • when its results arrive via a ResultEvent(JSONObject content, Query query, int requestSeqNumber)
  • when a query is cancelled via a CancelEvent(Request request, Integer requestSeqNumber)
  • when a request errors via a ErrorEvent(AlgoliaException error, Query query, int requestSeqNumber)
  • when a new facet refinement is applied via a FacetRefinementEvent(Operation operation, NumericRefinement refinement)
  • when a new numeric refinement is applied via a NumericRefinementEvent(Operation operation, String attribute, String value)

We use EventBus to dispatch events. You can register an object to the event bus using EventBus.getDefault().register(this); after which it will receive events on methods annotated by @Subscribe:

public class Logger {
    Logger() {

    onSearchEvent(SearchEvent e) {
        Log.d("Logger", "Search:" + e.query);

    onResultEvent(ResultEvent e) {
        Log.d("Logger", "Result:" + e.query);