api/1.2/notes.md

@@ -219,3 +219,55 @@ https://radar.squat.net/api/1.2/search/events.json?facets[category][]=bar-cafe&f
 group operator is OR, this call returns events organized by group 339006 OR 1599
 https://radar.squat.net/api/1.2/search/events.json?facets[group][]=339006&fields=*&facets[group][]=1599
 ```
+
+# Filters
+
+Filters provide a somewhat more complex way to filter results. Note: filtering only works on indexed fields. 
+
+Filters can be passed to the server by using the filter parameter:
+
+```
+https://radar.squat.net/api/1.2/search/events.json?filter[~operator][field][~comparator]=value
+```
+
+Possible operators are
+
+* `~and`: all filters with ~and must evaluate to true
+* `~or`: at least one of the ~or filters must evaluate to true
+
+Comparators:
+
+* `~e`: equals
+* `~ne`: not equal
+* `~gt`: greater than
+* `~gte`: greater or equal than
+* `~lt`: less than
+* `~lte`: less or equal than
+
+Note: filtering also works on resolved fields.
+
+Example
+
+Get all events in Berlin
+```
+https://radar.squat.net/api/1.2/search/events.json?filter[~and][field_offline:field_address:locality][~eq]=Berlin
+```
+
+Note: most of the equal filters, like in this example, can be be done with Facets in a simpler manner (see Facets).
+
+One of the more interesting things you can do is filtering for a time period
+
+Get all events in Berlin with a start date between 2020-11-03 00:00:00 and 2020-11-25 00:00:00
+```
+https://radar.squat.net/api/1.2/search/events.json?facets[city][]=Berlin&filter[~and][search_api_aggregation_1][~gt]=1604358000&filter[~or][search_api_aggregation_1][~lt]=1606258800
+```
+
+Limitations
+
+Filters can't be grouped, i.e. things like `(cond1 AND cond2) OR cond3` are not possible.
+
+A field can't be used in more than one equals filter, i.e. you can't filter for events in Berlin OR Amsterdam because that would require using the field locality twice.
+
+filter[~and][field_offline:field_address:locality][~eq]=Berlin&filter[~or][field_offline:field_address:locality
+
+This is where there will usually be facets to cover the requirement.
\ No newline at end of file