Using the suggestion server
The suggestion server is a search engine for filters, and translates names and urls to ids the API understands.
It is designed to be used interactively and as a companion to the search API. Users can start to type the name of a site or a country, and get suggestions for filters matching the terms back. The response contains useful data for building interactive UIs, like highighting information about any of the matches.
The suggestion server is also a more general bridge between urls and names in natural language and abstracted ids used by the API. Depending on the users language, the same country can be refered to as either Germany or Deutschland. With the suggestion server, you search in your language of choice, and get, among other things, the language agnostic ids back.
For an extensive list of search options, please consult the reference.
From names to ids
Whenever you want to only search for content in a particular language, on a given news site or maybe show news only from print media, you want to reference those entities by their names, like France and the New York Post. Since the API is language agnostic, and only accepts ids, the suggestion server is there to help you translate from something human-readable to a format the API understands, taking search terms in the language of your choice.
To demonstrate, if we want to use the search API to get content only from the New York Post, we could do that by adding a site filter with an id of 318:
{
"searchterm": "header:tax site:318"
}
However, we would need to get the id from somewhere.
The suggestion server can perform this translation from names to ids. If we search for New York, and ask only for the top two results, we get back a geo filter for the state of New York, and a filter for the New York Post website:
curl "https://api.opoint.com/suggest/en_GB_1:UTC+1/0/2/0/0/2147483647//new%20york"
{
"results": [
{
"id": "1372",
"name": "New York",
"url": "",
"accessGroup": 1,
"type": "geo",
"lang": "",
"meta": "",
"mo": "11",
"match": "11",
"hl": "0-2,4-7",
"weight": 1575336,
"rank": "",
"typeName": "From"
},
{
"id": "172,330084",
"name": "New York Post",
"url": "https://nypost.com",
"accessGroup": 1,
"type": "site",
"lang": "",
"meta": "us",
"mo": "11",
"match": "11",
"hl": "0-2,4-7",
"weight": 27131,
"rank": "12",
"typeName": "Source"
}
],
"search": "new york",
"tokens": 4,
"hits": 2,
"time(ms)": 0,
"warnings": "*Default english ordering set",
"next_offset": "lang:0,media:0,site:52,geo:9,timePeriod:0,ecb_rank:0,ecb_voice:0,ecb_topic:0,ecb_sentiment:0,content:0,rank:0"
}
The type and id fields contain the values that can be sent to the search API.
Interactivity
The suggestion server is designed to be used interactively, and it is particularly apt to use it in conjunction with a search field in a UI. The user can start to type the name of a site or a country, and a dropdown menu can show the sites and countries best matching the search term. The response from the server contains useful information such as names in a given language for display, and highlighting information about any of the matches.
It is the locale parameter that determines the language the search term is interpreted in, and the language of the names in the response. Changing the locale to no_NO_1 would not change the ids, but the name and the typeName, would be different. I would also search with different names, for instance Frankrike instead of France.
In addition to a search_term, the suggest endpoint takes its own list of filters, selected_filters. Using the geo filter for New York, the suggested sites will be sites found in the state of New York. When a user is building a search, any of the filters already chosen can be passed to the suggestion server, in order to add filters with more precision.
curl "https://api.opoint.com/suggest/en_GB_1:UTC+1/multiple/5/0/0/2147483647/geo:1372/" | jq '.site'
{
"seq": 3,
"cols": 1,
"action": "1208924666693124567859200",
"typeName": "Source",
"suggest": [
{
"id": "172,330084",
"name": "New York Post",
"url": "https://nypost.com",
"accessGroup": 1,
"type": "site",
"lang": "",
"meta": "us",
"mo": "11",
"match": "01",
"hl": "",
"weight": 27131,
"rank": "12"
},
{
"id": "2401,330148,330150,330149,330147,330151",
"name": "Wall Street Journal",
"url": "https://www.wsj.com",
"accessGroup": 1,
"type": "site",
"lang": "",
"meta": "us",
"mo": "11",
"match": "01",
"hl": "",
"weight": 21220,
"rank": "12"
},
{
"id": "27974",
"name": "Macon Telegraph",
"url": "https://www.macon.com",
"accessGroup": 1,
"type": "site",
"lang": "",
"meta": "us",
"mo": "11",
"match": "01",
"hl": "",
"weight": 21181,
"rank": "14"
},
{
"id": "644",
"name": "New York Daily News",
"url": "http://www.nydailynews.com",
"accessGroup": 1,
"type": "site",
"lang": "",
"meta": "us",
"mo": "11",
"match": "01",
"hl": "",
"weight": 13992,
"rank": "14"
},
{
"id": "4394",
"name": "Ein News",
"url": "https://www.einnews.com",
"accessGroup": 1,
"type": "site",
"lang": "",
"meta": "us",
"mo": "11",
"match": "01",
"hl": "",
"weight": 13979,
"rank": "14"
}
]
}
Expressions
Typically, the suggestion server is used to fetch filters, and then these filters are added to the rest of the search string, and used for making a search request to the API. Since the suggestion server returns JSON objects with all the data about the filters, the search API accepts a slightly more verbose, but in this case more convenient, format:
{
"expressions": [
{
"linemode": "R",
"searchline": {
"searchterm": "header:spotify",
"filters": [
{
"type": "lang",
"id": "no"
},
{
"type": "url",
"id": "vg.no"
}
]
}
}
],
"params": {
"requestedarticles": 10
}
}The searchterm field is changed to a list of expression objects. The linemode determines how multiple expression objects are interpreted, but can be set to R for now. The searchline field contains a searchterm, as before, but also a list of filters that will be prepended to the searchterm by the API.
This might seem like more work, but the response from the suggestion server already contains objects with type and id fields, and can therefore be relayed to the filters field directly, without having to parse it into a type:id form.