If you have installed Seeks with default configuration, or setup your own collaborative search ring, you’re ready to take advantage of it.

There are basically two non-exclusive ways to use your Seeks collaborative search ring:

  • The easiest way to collaborate is to simply use your Seeks instance as a regular Web search engine. This is a passive recommendation scheme.

    For this 

    use the HTTP method POST on resource /search/txt/query/snippet_id

    where you replace query with the string of your choice and snippet_id with the result id you wish to recommend. This id is generated by Seeks, you need to get a list of results first, in which every returned result snippets comes with an id you can then reuse.

  • A more active way of using it is to rely on the API to curate queries and results. This is an active recommendation scheme.

    For this 

    use the HTTP method POST on resource /recommendation/query?
url=http%3A%2F%2Fwww.example.com%2F

    where the url parameter must be URL encoded.

The main difference between the two is that the first one only let you passively recommend the results that appear into the list of results for each of your queries, whereas the second method actively attaches results to one or more queries.. So for instance, if you are using Seeks with Google as a background generic search engine, you will get results from Google. Those results you select and click will be recommended to other users performing similar queries throughout your collaborative search ring.

So this is useful but sometimes falls short because the background search engine, even Google, falls short of your expectations. Simple example, you would like to know the five finalists to some startup competition. Very much likely you will get results about the competition itself, and from there you would locate the list of finalists with high probability.
Now, what you can do with Seeks is to add the websites of every of the five finalist to the query itself. This is what the API is for.

Using curl, to you would add to the list of best basket players of all time by doing something like

curl  -X POST
"http://www.seeks-project.info/search_exp.php/recommendation
/five+best+basket+players+of+all+time?
url=http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FMichael_Jordan&lang=en"

That’s it, we’ve just added Michael Jordan’s wikipedia page to the query ‘five best basket players of all time’.

You can check that it’s there:

curl  -X POST
"http://www.seeks-project.info/search_exp.php/recommendation
/txt/five+best+basket+players+of+all+time?output=json"

and you would get something like:

{"query":"five best basket players of all time","npeers":2,
"qtime":0.16,"snippets":[{"id":1391458535,
"title":"Michael Jordan - Wikipedia, the free encyclopedia",
"url":"http://en.wikipedia.org/wiki/michael_jordan","summary":"","seeks_meta":1,
"seeks_score":0.239827,"rank":0,
"cite":"http://en.wikipedia.org/wiki/michael_jordan",
"engines":["seeks"],"type":"webpage","personalized":"yes","snpeers":1,"hits":1}]}

(Note that you can use the Seeks CLI to perform these operations).

Now, mixing up the passive and the active recommendation schemes you can recommend search results throughout your search ring, and get recommended new results as well.

Finally, Seeks gives you the ability to reject recommendations. But while recommendations are global, that is they are shared with all Seeks instances throughout the ring, rejection is local, only affects you. This is very much like your mailbox spam filter.

There are two calls to reject results:

  • using 
    HTTP method DELETE on the /search/txt/query/snippet_id

    resource does cancel any recommendation ‘booster’ on that result snippet;

  • using 
    HTTP method DELETE on the /recommendation/query/snippet_id

    removes the result snippet from database definitely.

Why two calls ? Because the first one cancels the passive recommendation scheme, whereas the second one cancels the active recommendation scheme.

With two recommendation calls, and two rejection calls for control, you’re ready to collaborate within a search ring.

If you cannot make your Seeks instance available to the public, you may be interested in learning more about cross-posting your results.