Add search parameters with JSON

You can use Rules to apply search parameters when a condition matches. Both the Visual Editor and Manual Editor accept JSON for search parameters. The Visual Editor provides separate controls for filters, optional filters, and query edits.

Using the dashboard

You can add search parameters from the Algolia dashboard using either the Visual Editor or the Manual Editor.

Visual Editor
Manual Editor

In the Algolia dashboard, select your application and index, open Rules, and select New rule > Visual Editor.
Select Set query condition(s) and define when the rule applies. Click Apply.
In Consequences, expand More consequences and select Apply search parameters. In Value, enter { "aroundRadius": 1000 } to limit the search radius to 1,000 meters when your search uses geolocation. Click Apply.
Review the results, click Review and Publish, and click Publish.

In the Algolia dashboard, select your application and index, open Rules, and select New rule > Manual Editor.
In Condition(s), define when the rule applies.
In Consequence(s), click Add consequence and select Add Query Parameter. Enter { "aroundRadius": 1000 } to limit the search radius to 1,000 meters when your search uses geolocation.
Save your changes.

The editor validates the JSON and rejects unsupported parameters. Use dedicated consequences for the following parameters: filters, optionalFilters, redirect, query, automaticFacetFilters, automaticOptionalFacetFilters, and renderingContent. Use Filter results, Boost categories, Bury categories, or the corresponding consequence instead of entering these parameters in Apply search parameters.

Use JSON templates

You can use the following templates in the Manual Editor’s Add Query Parameter consequence or in a rule’s consequence.params with the API. The filter templates below aren’t accepted by the Visual Editor’s Apply search parameters consequence. In this guide, FACET:VALUE refers to a facet-value pair, such as, author:shakespeare.

Filters

Filters excludes that don’t match the filter.

Scenario	JSON template
Select a category	`{ "filters":"FACET:VALUE" }`
Remove a category	`{ "filters":"NOT FACET:VALUE" }`
Remove several categories	`{ "filters":"NOT FACET:VALUE AND NOT FACET:VALUE" }`

If you have a multi-word VALUE (such as William Shakespeare), wrap it in single quotes. For example:

JSON

{
  "filters": "NOT author:'William Shakespeare' AND NOT author:Plato"
}

If your VALUE contains an apostrophe (such as Tony d’Arbon), escape the apostrophe with double backslashes and wrap the whole string in single quotes. For example:

JSON

{
  "filters": "NOT author:'William Shakespeare' AND NOT author:'Tony d\\'Arbon'"
}

Optional filters

Optional filters don’t remove records from the results, but they promote or demote matching records. You can fine-tune the behavior of optional filters with filter scores.

Any attribute you want to use as an optional filter must be declared as a facet.

Examples for optional filters

The following examples show different use cases for optional filters, their JSON representation, and the effect on filter scoring.

Promote a category

Filter scoring: +1 for all matching records

JSON

{
  "optionalFilters": ["FACET:VALUE"]
}

Promote several categories with equal weight

Filter scoring: +1 for all records matching one or more filter

JSON

{
  "optionalFilters": ["FACET1:VALUE1", "FACET2:VALUE2"]
}

Promote several categories with different weights per category

Filter scoring: +X or +Y, whichever matches and has the highest value

JSON

{
  "optionalFilters": ["FACET1:VALUE1<score=X>", "FACET2:VALUE2<score=Y>"]
}

Promote several categories with a combined score

Filter scoring: +1 or +2, depending on the number of matching filters

JSON

{
  "optionalFilters": ["FACET1:VALUE1", "FACET2:VALUE2"],
  "sumOrFiltersScores": true
}

Promote several categories with combined weighting

Filter scoring: +X, +Y, or +X+Y, depending on the matching filters

JSON

{
  "optionalFilters": ["FACET1:VALUE1<score=X>", "FACET2:VALUE2<score=Y>"],
  "sumOrFiltersScores": true
}

Demote a category

Filter scoring: +1 for all records that don’t match the filter

JSON

{
  "optionalFilters": ["FACET:-VALUE"]
}

Demote several categories equally

Filter scoring: +1 for all records that don’t match any of the filters

JSON

{
  "optionalFilters": ["FACET1:-VALUE1", "FACET2:-VALUE2"]
}

Optional filters with multiple words

Unlike filters, you don’t need to wrap a multi-word VALUE with single quotes if it contains spaces. For example:

JSON

{
  "optionalFilters": [
    ["author:William Shakespeare<score=3>", "author:John Doe<score=2>"]
  ],
  "sumOrFiltersScores": true
}

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Add search parameters with JSON

Using the dashboard

Use JSON templates

Filters

Optional filters

Examples for optional filters

Promote a category

Promote several categories with equal weight

Promote several categories with different weights per category

Promote several categories with a combined score

Promote several categories with combined weighting

Demote a category

Demote several categories equally

Optional filters with multiple words

See also

​Using the dashboard

​Use JSON templates

​Filters

​Optional filters

​Examples for optional filters

​Promote a category

​Promote several categories with equal weight

​Promote several categories with different weights per category

​Promote several categories with a combined score

​Promote several categories with combined weighting

​Demote a category

​Demote several categories equally

​Optional filters with multiple words

​See also

Using the dashboard

Use JSON templates

Filters

Optional filters

Examples for optional filters

Promote a category

Promote several categories with equal weight

Promote several categories with different weights per category

Promote several categories with a combined score

Promote several categories with combined weighting

Demote a category

Demote several categories equally

Optional filters with multiple words

See also