Filtering

To be able to search with ILSA, you first need to define which fields you want to be able to search on. This is configured in the Backoffice. You could define a “searchable field” for general.category and now you can call /searchresults?general.category=van.

You can search on multiple values by repeating the URL parameters: /searchresults?general.category=car&general.category=van. A vehicle can’t be both a car and a van, so we search for vehicles that are either.

When searching with ILSA, usually your filters are AND-filters: The visitor wants vehicles that have both warranty and air condition. Not vehicles that have just one of those. You can do simple OR-queries if you accept either value in a field (like the car and van example above). But if you want to do OR-queries that span multiple fields, you’ll need Or Groups. For example searching for Audi A3 or BMW 1-series.

Searchable field types

In the backoffice you need to configure the “Field type” for each Searchable field you define. Those types relate to the type of the field you’re searching on, but something you have multiple options. For example, on an INTEGER field, you could either search for the exact value (like “exactly 4 cylinders”) or a range (“price between €50000 and €10000” or “at least €50000” or “at most €100000”).

First let’s explain when to use which searchable field type. For example using EXACT_INTEGER on a STRING makes no sense.

EXACT_STRING lets you search for a specific string in the vehicle property. For example general.make.normalized=bmw.

EXACT_INTEGER lets you search on a specific integer. For example body.door_count=5.

RANGE lets you search with a minimum and/or maximum value if you have predefined common search filters. For example price or odometer. For example general.year=2010-2020, general.year=2010- or general.year=-2020. See below for more information.

COMPARATIVE_INTEGER lets you search with a minimum and/or maximum value. For example a timestamp. For example metadata.first_advertised=1704063600-. COMPARATIVE_INTEGER produces no dropdowncontents.

CURVE lets you search for a value close to the given value. For example the maximum price. Vehicles just over the maximum price are probably okay, vehicles one third of the price are probably not what they want. The closer the vehicle is to the desired price the better. Searching on CURVE fields influences the _score sorting. Dropdown contents are not applicable to CURVE fields.

FULLTEXT lets you use free-text searching. For example searching on aud would give you all Audi’s, but also cars equipped with an audio-system. If you have our Premium module, this also searches through our thousands of predefined keywords. For example hybrid would return vehicles with fuel type hybrid and those having the word “hybrid” in general.type.name.

BOOL lets you search for a boolean being true or false. Note that besides true and false for some vehicles we might not know this field, in which case they’ll be filtered out if any filter is given.

BOOL_TRUE lets you search for a boolean being true. Missing values are treated as false. These are commonly rendered as checkboxes (omitting the filter if the checkbox is not checked).

DISTANCE lets you search for a maximum distance from the visitor to the given field. The field you’ll use this for is likely always advertiser.coordinates.

Range fields

Range fields are usually rendered with two dropdowns on a website: one setting a minimum and the other a maximum. You also often see these rendered as a slider.

You can choose to only render one of the two filters to only allow your visitors to filter on a minimum (or maximum).

When creating a RANGE field you need to define the range options. For example for a price field that might be €3000, €10000, €15000, €20000, €25000, €30000, €50000 and €100000. When you request the /dropdowncontents, we’ll tell you how many results you’ll get when you select each specific option.

You are not restricted to searching on exactly your range options. You can also allow your visitors to enter any value they want and pass that to ILSA. For example, with the above range options, searching for sales_conditions.pricing.asking.in_eur.amount=10007-19999 also works. You still need to define the range options so we can give dropdown contents to you.

{
    "range_fields": {
        "condition.odometer.value_in_km": {
            "min": [
                {
                    "key": 10000,
                    "display_value": "10,000 km",
                    "count": 25500
                },
                {
                    "key": 50000,
                    "display_value": "50,000 km",
                    "count": 18261
                },
                {
                    "key": 100000,
                    "display_value": "100,000 km",
                    "count": 10558
                },
                {
                    "key": 150000,
                    "display_value": "150,000 km",
                    "count": 5083
                },
                {
                    "key": 200000,
                    "display_value": "200,000 km",
                    "count": 1937
                }
            ],
            "max": [
                {
                    "key": 10000,
                    "display_value": "10,000 km",
                    "count": 6188
                },
                {
                    "key": 50000,
                    "display_value": "50,000 km",
                    "count": 13328
                },
                {
                    "key": 100000,
                    "display_value": "100,000 km",
                    "count": 21029
                },
                {
                    "key": 150000,
                    "display_value": "150,000 km",
                    "count": 26503
                },
                {
                    "key": 200000,
                    "display_value": "200,000 km",
                    "count": 29649
                }
            ]
        }
    }
}

Trim range options

When requesting the dropdown contents, we’ll give you all the range options you’ve defined. With the backoffice setting Trim range options you can configure ILSA to automatically remove irrelevant options. This can for example be used to hide the years 2000-2009 if your oldest vehicle is from 2010. This setting has three values:

1. Use your list exactly as provided.
2. Automatically hide the lowest/highest options if you don’t have matching vehicles in your dataset.
3. Automatically hide the lowest/highest options based on the current search filters. For example, if someone is filtering on BMWs and your oldest BMW is from 2015, we’ll hide 2000-2014. Any options hidden by #2 will also be hidden by this.

Keyword completion

One of the modules available in ILSA is keyword completion. You can show suggestions which the user is typing in your keyword field. We have defined thousands of keywords (including all makes and models) through which users can search instantly.

Usage is simple: Once the user focuses your keyword field you can add _fields=keyword to your /dropdowncontents call and receive the top matching keywords as the result. You can request new suggestions for every character they type, but please don’t send requests more frequently than every 100ms (use debouncing). Don’t include _fields=keyword in your request if the field is not focused as the request is computationally expensive.

GET /dropdowncontents?_fields=keyword&_keyword_tabcompletions=3&_locale=en_GB&keyword=au

HTTP 200 OK
Content-Type: application/json

{
  "fields": {
    "keyword": [
      {
        "key": "automatic_transmission",
        "display_value": "Automatic",
        "count": 18814
      },
      {
        "key": "audi",
        "display_value": "Audi",
        "count": 2403
      },
      {
        "key": "auris",
        "display_value": "Auris",
        "count": 62
      }
    ]
  }
}

You can control the number of suggestions you get with &_keyword_tabcompletions=6.

You can let your users search for multiple keywords by passing &keyword=towbar&keyword=cruis. The tab completion suggestions are given for the last given parameter.