🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
API Reference / API Parameters / customRanking
Type: list of strings
Engine default: [] (no custom ranking)
Parameter syntax
'customRanking' => [

Can be used in these methods:

About this parameter

Specifies which attributes to assign to Algolia’s custom ranking criterion.

Custom ranking is used to:

  • Define a ranking of results using metrics that are important to you, such as popularity and date.
  • Only show the most relevant results rather than all results: this is called relevant sorting.

Before adding a custom ranking, test the impact in the dashboard. You should also consider planning and implementing A/B testing to ensure that it will positively affect your results.

Usage notes

Specify your custom ranking attributes as a list of strings. Each string must use the syntax: asc(<ATTRIBUTE>) or desc(<ATTRIBUTE>) to determine the ascending or descending sort order. The tie-breaking algorithm applies all custom ranking attributes in the specified sequence.



Sort by increasing value of the attribute.


Sort by decreasing value of the attribute.


Set a custom ranking

This example uses the setSettings method to apply a custom ranking. It sorts by the decreasing value of the popularity attribute, then if popularity is equal, by the increasing value of the price attribute.

  'customRanking' => [
Did you find this page helpful?