NewsBoss Wires Filter Expressions (WiFEs) evaluate JSONPath filters and are used to test stories for distribution into a queue as they are received, similar to the way selector codes are used.
For a complete description of the JSONPath syntax, see the JSONPath Syntax section below and the links therein. But briefly, at the core of a WiFE is the E(...), or Evaluate, function. WiFEs contain one or more E functions, which enclose a JSONPath filter expression in parentheses, like E(<JSONPath expression>). The E(...) function evaluates to either TRUE or FALSE, depending on whether the JSONPath expression results in an empty JSON object when applied to the raw JSON story data.
WiFE E(...) functions can be grouped with others using parentheses, and individual E(...) functions or groups can be combined using the 'or' operator |, and the 'and' operator &.
Each E(...) function must be wholly on the same line.
If the WiFE is evaluated as TRUE, then the story is distributed to the selected story queue.
For example, this is a WiFE that will match AP Media stories relating to the states of Texas and Illinois. The WiFE syntax is shown in green and the JSONPath expressions are shown in blue. Similar WiFEs can be created to filter for other states, cities, countries or regions, examples of which are given below.
; Filter for Texas and Illinois... E($.item[?($..place[?(@.locationtype.name=='State' && @.name=='Texas')])]) | E($.item[?($..place[?(@.locationtype.name=='State' && @.name=='Illinois')])])Points to note about the above example are:
- text after a ; character is considered a comment and is not considered part of the filter expression;
- there are two E(...) functions on separate lines, each one enclosing a JSONPath expression. These E(...) functions are OR'ed together using the | operator at the end of the second line. In this case, if either E(...) function evaluates to TRUE, then the result of the WiFE will be TRUE and the story will be distributed to the destination queue;
- the second line ends with a | character, which means the result of the preceding E(...) expression will be OR'ed with the result of the next E(...) expression;
- letter 'case' is critical - matches will not occur if the letter case does not match the JSON data provided by the wire service. View the raw .json files provided by the wire services to gain insight into their structure;
- JSONPath filter expressions are particular to each wire service and the format of the .json file the service provides;
- although you can have two or more WiFEs E(...) functions on the same line, it is generally clearer to keep them separated on lines of their own.
AP Media
These examples and templates apply to the AP (Associated Press) Media product.
The WiFE examples below can be copied/pasted into the Filter Expression field in Wires and modified if necessary. You can also use the WiFE templates if available to select available entities (country, state and city names), and copy the resulting WiFEs using the Copy buttons.
- Select stories that are related to a particular Country
- Select stories that are related to a particular US state
- Select stories that are related to multiple US states
- Select stories that are related to a particular city of a US state
- Select stories that are related to 3 cities of a US state
- Select 'SummaryBrief' stories
- Select Business Summary Briefs
- Exclude 'SummaryBrief' stories from a queue
- Select 'Sportradar' stories
- Select 'NewsWatch' stories
- Select stories based on AP Media Product codes
Select stories that are related to a particular Country.
This example matches if the JSON story item object contains a place object with a name of Ukraine, and that place object has a location object with a name of Nation.
; Filter stories for Nation E($.item[?($..place[?(@.locationtype.name == 'Nation' && @.name == '')])])
Select stories that are related to a particular US state.
This example matches if the JSON story item object contains a place object with a name of a US state, and that place object has a location object with a name of State.
; Florida state stories E($.item[?($..place[?(@.locationtype.name == 'State' && @.name == 'Florida')])])Use this template to create and copy a US State filter expression...
E($.item[?($..place[?(@.locationtype.name == 'State' && @.name == '')])])
Select stories that are related to multiple US states.
On a single line...; Texas or Illinois stories E($.item[?($..place[?(@.locationtype.name == 'State' && (@.name == 'Texas' || @.name == 'Illinois'))])])or use multiple lines in the filter...
; Texas or Illinois stories E($.item[?($..place[?(@.locationtype.name == 'State' && @.name == 'Texas')])]) | E($.item[?($..place[?(@.locationtype.name == 'State' && @.name == 'Illinois')])])
Select stories that are related to a particular city of a US state.
For example,; Dallas, Texas stories E($.item[?($..place[?(@.locationtype.name == 'State' && @.name == 'Texas')] && $..place[?(@.locationtype.name == 'City' && @.name == 'Dallas')])])Use this template to create and copy a filter expression...
E($.item[?($..place[?(@.locationtype.name == 'State' && @.name == '')] && $..place[?(@.locationtype.name == 'City' && @.name == '')])])
or use multiple lines in the filter...
(Note the & character at the end of the first filter line!)
; State/City stories E($.item[?($..place[?(@.locationtype.name == 'State' && @.name == '')])]) & E($.item[?($..place[?(@.locationtype.name == 'City' && @.name == '')])])
Select stories that are related to 3 cities of a US state.
; State/City stories E($.item[?($..place[?(@.locationtype.name == 'State' && @.name == '')])]) & ( E($.item[?($..place[?(@.locationtype.name == 'City' && @.name == '')])]) | E($.item[?($..place[?(@.locationtype.name == 'City' && @.name == '')])]) | E($.item[?($..place[?(@.locationtype.name == 'City' && @.name == '')])]) )
Select 'SummaryBrief' stories.
;Include all SummaryBrief stories... E($.item[?($.item.title =~ /(SummaryBrief).*$/)])
Select Business Summary Briefs...
;SummaryBrief-Business stories... E($.item[?($.item.title == 'SummaryBrief-Business')])
Exclude 'SummaryBrief' stories from a queue.
;Exclude any SummaryBrief stories (updated to avoid regex recursion)... E($.item[?($.item.title =~ /^(?!SummaryBrief).*/)])
Select 'Sportradar' stories.
; Sportradar stories E($.item[?($.item.provider == 'Sportradar')])
Select 'NewsWatch' stories.
; NewsWatch stories E($.item[?($.item.title == 'AP NewsWatch')])
Select stories based on AP Media Product codes.
This example matches if the JSON story object contains a meta.products object with an id of a 46587, which is the AP Media Product Code for Broadcast - Summaries - National News.
; Broadcast - Summaries - National News E($.item[?($..meta.products[?(@.id == 46587)])])
NOTE: The available AP Media Products are dependent on your AP Media subscription.
Enter your AP Media API Key below to allow the selection of product codes included in your AP Media subscription.
API Key:
ADVANCED
JSONPath Syntax
The NewsBoss JSON story filter is based on the JSONPath - XPath for JSON query language developed by Stefan Goessner, and implemented in C++ using the jsoncons library by Daniel Parker.
The syntax summary below was extracted from the JsonCons JsonPath documentation page, where further information and general examples can be found.
Paths
| Selector | Description |
|---|---|
$ |
Represents the root JSON value |
@ |
Represents the value currently being processed |
.<name> or .'<name>' or ."<name>" |
The '.' character followed by a JSON object member name, unquoted or quoted |
['<name>'] or ["<name>"] |
Subscript operator with quoted JSON object member name |
[<index>] |
Index expression used to access elements in a JSON array. A negative index value indicates that indexing is relative to the end of the array. |
* or ['*'] |
Wildcard. All objects/elements regardless their names. |
[start:stop:step] |
Array slice notation, following Python |
^ |
Parent operator borrowed from JSONPath Plus |
.. |
Recursive descent |
[,] |
Union operator for alternative object names or array indices or JSONPath expressions |
?<expr> |
Filter by expression |
Filter Selector
filter-expression = "?" expression
expression = single-quoted-string
expression =/ json-literal ; any valid JSON value
expression =/ jsonpath
expression =/ unary-expression / binary-expression / regex-expression / paren-expression
paren-expression = "(" expression ")"
unary-expression=unary-operator expression
binary-expression = expression binary-operator expression
regex-expression = expression regex-operator "/" regex "/" [i]
unary-operator = "!" / "-"
binary-operator = "*" / "/" / "%" / "+" / "-" / "&&" / "||" / <" / "<=" / "==" / ">=" / ">" / "!="
regex-operator = "=~"
;
; "regex" represents regular expression characters
function-expression = unquoted-string (
no-args /
one-or-more-args )
no-args = "(" ")"
one-or-more-args = "(" ( function-arg *( "," function-arg ) ) ")"
function-arg = expression
Binary Operators
| Operator | Expression | Description |
|---|---|---|
* |
expression * expression | Left times right |
/ |
expression / expression | Left divided by right |
% |
expression % expression | Remainder |
+ |
expression + expression | Left plus right |
- |
expression - expression | Left minus right |
&& |
expression && expression | Left is true and right is true |
|| |
expression || expression |
Left is true or right is true |
== |
expression == expression | Left is equal to right |
!= |
expression != expression | Left is not equal to right |
< |
expression < expression | Left is less than right |
<= |
expression <= expression | Left is less than or equal to right |
> |
expression > expression | Left is greater than right |
>= |
expression >= expression | Left is greater than or equal to right |
=~ |
expression =~ "/" regex "/" [i] |
Left matches regular expression, e.g. [?(@.author =~ /Evelyn.*?/)] |