Add search parameters with JSON

The Visual Editor lets you apply filters with Rules. If you want to apply optional filters or other API parameters, you need to add them in the Manual Editor as JSON.

In this guide, FACET:VALUE refers to a facet-value pair, such as, author:shakespeare.

Filters

Filters excludes records that don’t match the filter.

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

1
2
3
{
  "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:

1
2
3
{
  "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

1
2
3
{
    "optionalFilters": ["FACET:VALUE"]
}

Promote several categories with equal weight

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

1
2
3
{
    "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

1
2
3
4
5
6
{
    "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

1
2
3
4
{
    "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

1
2
3
4
5
6
7
{
    "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

1
2
3
{
    "optionalFilters": ["FACET:-VALUE"]
}

Demote several categories equally

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

1
2
3
{
    "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:

1
2
3
4
5
6
7
8
9
{
  "optionalFilters":[
    [
      "author:William Shakespeare<score=3>",
      "author:John Doe<score=2>"
    ]
  ],
  "sumOrFiltersScores":true
}