Protocol

Searsia is designed such that each Searsia server manages multiple resources. These resources can be existing web search engines, or they can be other Searsia servers. A Searsia server has a single API query interface, which is shared with other servers (and clients) by means of an API template. For instance, the API template of the University of Twente search engine is:

https://search.utwente.nl/searsia/search?q={q?}&r={r?}

A search in Searsia typically follows the following stages:

  1. The client first calls the Searsia server with only a query. The server returns search results, some (or all) of which were previously found by the server's resources. The client may present the search results, or get even better search results as follows;
  2. The client may call the server with the query and the resource idenfitier to request the server to forward the query to the resources that previously found the search results, or;
  3. The client may query the resource directly after requesting the server for the resource's contact details.

Call with only a query

A call to the server with only a query returns the server's local search results. For instance, for the query searsia, the University of Twente API:

https://search.utwente.nl/searsia/search?q=searsia&r=

produces a result that is similar to one below:

{
  "hits": [
    {
      "title": "Searsia",
      "description": "Search for noobs",
      "score": 3.319267,
      "url": "http:\/\/searsia.org"
    },
    {
      "rid": "googlecustom",
      "title": "Projecten | Organisatie",
      "description": "UT Search is powered by Searsia ...",
      "score": 2.9963183, 
      "url": "https:\/\/www.utwente.nl\/organisatie\/nieuws-events\/dossier\/…"
    },
    {
      "rid": "publications",
      "score": 2.0
    }
  ],
  "resource": {
    "id": "utwente",
    "mimetype": "application\/searsia+json",
    "urltemplate": "https:\/\/search.utwente.nl\/search.html?q={q}",
    "favicon": "https:\/\/search.utwente.nl\/ut-icons\/ut.png",
    "testquery": "twente",
    "name": "University of Twente",
    "prior": 2,
    "apitemplate": "https:\/\/search.utwente.nl\/searsia\/search?q={q?}&r={r?}",
    "banner": "https:\/\/search.utwente.nl\/ut-icons\/utlogo-black.png"
  },
  "searsia": "v0.3.0"
}

The attribute "hits" contains search results that may have an attribute "rid", which is the resource identifier of the resource that produced the result for a previous search. Searsia ranks the results such that the resource identifiers are ranked by the relevance of the resources to the query. The attribute "resource" contains information about the server, such as its name and icon. The attribite "searsia" contains the version number of the server. Based on this results, the client may now decide to ask the server to forward the query to "googlecustom" and "publications", which is done as follows:

Call with a query and a resource identifier

A call to the server with a query and a resource identifier will let the server forward the query to the resource. For instance, for the query searsia, a call to the University of Twente API:

https://search.utwente.nl/searsia/search?q=searsia&r=publications

produces a result that is similar to one below:

{
  "hits": [
    {
      "title": "Searsia Documentation",
      "description": "Djoerd Hiemstra, Dolf Trieschnigg, Thomas Demeester, ...",
      "url": "http:\/\/doc.utwente.nl\/970499\/"
    }  
  ],
  "resource": {
    "id": "publications",
    "mimetype": "text\/html",
    "urltemplate": "http:\/\/doc.utwente.nl\/cgi\/search\/archive\/simple?q={q}",
    "favicon": "http:\/\/doc.utwente.nl\/style\/images\/fileicons\/pdf.png",
    "itempath": "\/\/div[@id='content']\/div\/table\/tbody\/tr[.\/td\/span\/a]",
    "extractors": {
      "title": "(.\/\/a)[1]",
      "description": ".",
      "image": "(.\/\/img)[last()]\/@src",
      "url": ".\/\/@href"
    },
    "testquery": "test",
    "name": "Publications",
    "prior": 1,
    "apitemplate": "http:\/\/doc.utwente.nl\/cgi\/search\/archive\/simple?q={q}"
  },
  "searsia": "v0.3.0"
}

The attribute "hits" contains search results of the resource "publications". The attribute "resource" contains contact information for the Publications search engine. In some cases additional information such as API keys need to be provided. In this example, however, the contact information suffices to contact Publications directly. Instead of forwarding the query, a client may only ask for the contact details, and then forward the query itself. A request for the contact details is done by the call in the next section:

Call with only a resource identifier

A call to the server with only a resource identifier returns the contact information of the resource. For instance, for the resource googlecustom, a call to the University of Twente API:

https://search.utwente.nl/searsia/search?q=&r=googlecustom

produces a result that is similar to one below:

{
  "resource": {
    "id": "googlecustom",
    "name": "University of Twente by Google",
    "mimetype": "application\/json",
    "urltemplate": "https:\/\/www.google.com\/cse?cx=003637895283361378319:95lv8knurmc",
    "favicon": "http:\/\/www.google.com\/s2\/favicons?domain=google.com",
    "itempath": "\/\/results",
    "extractors": {
      "title": ".\/titleNoFormatting",
      "description": ".\/contentNoFormatting",
      "image": ".\/richSnippet\/cseThumbnail\/src",
      "url": ".\/unescapedUrl"
    },
    "testquery": "twente",
    "prior": 2,
    "apitemplate": "https:\/\/www.googleapis.com\/customsearch\/v1element?key={apikey}…
  },
  "searsia": "v0.3.0"
}

The attribute "resource" contains contact information for Google's Custom search engine. To use this resource directly, you will have to obtain a API key from Google, and add it as a secret parameter.