HTML and JSON API

From Seeks

Returns result snippets in response to a query in HTML or JSON format.

Notice: Seeks JSON search API is available for versions of Seeks >= 0.2.2 (Bubs release).

Contents 1 URL 2 formats 3 HTTP Method 4 Resources 5 Requires Authentification 6 API Rate Limit 7 Parameters 8 Usage Notes 9 Example queries 10 Search operators 11 JSON Response

URL

http://seeks_node/search?output=html

http://seeks_node/search?output=json

where seeks_node should be replaced with the address of the seeks node you would like to search from.

formats

html

json

HTTP Method

GET

Resources

text search:

search

image search:

search_img

Requires Authentification

none

API Rate Limit

none

Parameters

• q: Required. The text to search for. See the queries section for examples on the format supported by this parameter.
  • Example: http://www.seeks-project.info/search_exp.php/search?output=json&q=markov+chain&page=1&expansion=1&action=expand
• action: Required. The action to be performed, possible values are:
  • expand: Expansion, that is the search for results. Requires an additional parameter, expansion that specifies the depth of the search.
    • Example: http://www.seeks-project.info/search_exp.php/search?output=json&q=markov+chain&page=1&expansion=3&action=expand
  • page: Requests a given page number. Requires an additional parameter, page that specifies the page number.
    • Example: http://www.seeks-project.info/search_exp.php/search?output=json&page=2&q=markov+chain&expansion=1&action=page
  • types: Requests a grouping of results per type.
    • Example: http://www.seeks-project.info/search_exp.php/search?output=json&q=markov+chain&expansion=1&action=types
  • clusterize: Requests an automated grouping of results based on their content. Requires an additional parameter clusters that specifies the maximum number of clusters (groups).
    • Example: http://www.seeks-project.info/search_exp.php/search?output=json&q=markov+chain&expansion=1&action=clusterize&clusters=10
  • similarity: Returns a subset of all results, those that are similar to a reference content. Requires an additional parameter, id that specifies the id of the reference content.
    • Example: http://www.seeks-project.info/search_exp.php/search?output=json&q=django&page=1&expansion=1&action=similarity&id=144795757
• expansion: Specifies the requested depth of the search, the higher, the more results are fetched and processed. Goes along with action=expand.
  • Example: http://www.seeks-project.info/search_exp.php/search?output=json&q=django&page=1&expansion=3&action=expand
• page: Specifies the number of the requested page. Goes along with action=page.
  • Example: http://www.seeks-project.info/search_exp.php/search?output=json&page=4&q=django&expansion=2&action=page
• rpp: Optional. Number of requested results per page. If unspecified, the number defined by the search node is used instead.
  • Example: http://www.seeks-project.info/search_exp.php/search?output=json&q=django&page=1&expansion=3&action=expand&rpp=5
• clusters: Optional. Specifies the maximum number of clusters (groups) to be constructed. Goes along with action=clusterize, default is 10 clusters.
  • Example: http://www.seeks-project.info/search_exp.php/search?output=json&q=markov+chain&page=2&expansion=1&action=clusterize&clusters=10
• id: specifies the id of a reference content, used along with action=similarity. The value of this parameter is obtained from a list of results, see the response format section for details.
  • Example: http://www.seeks-project.info/search_exp.php/search?output=json&q=django&page=1&expansion=1&action=similarity&id=144795757
• thumbs: Optional. Specifies whether a URI to a thumbails of every returned result is specified. Values are on or off.
  • Example: http://www.seeks-project.info/search_exp.php/search?output=json&page=1&q=django&expansion=2&action=expand&thumbs=on
• engines: Optional. Specifies a subset of search engines to be used in the websearch call. Values are yahoo, cuil, google, exalead and bing. (This parameter is for Seeks versions 0.2.3 and higher).
  • Example: http://www.seeks-project.info/search_exp.php/search?output=json&page=1&q=django&expansion=2&action=expand&engines=yahoo,cuil
• safesearch: Optional. Specifies whether to use safe search in the image websearch call. Values are on or off (This parameter applies to image websearch only, and to Seeks versions 0.2.4 and higher).
  • Example: http://www.seeks-project.info/search_exp.php/search_img?output=html&page=1&q=chatte&safesearch=on&action=expand&expansion=1

Usage Notes

• Query strings should be URL encoded.
• All methods will return a 400 HTTP error if one or more parameters are missing.
• Similarity calls return a 404 HTTP error if the resource cannot be found.

Example queries

• http://www.seeks-project.info/search_exp.php/search?output=json&q=django&page=1&expansion=2&action=expand
• http://www.seeks-project.info/search_exp.php/search_img?output=html&q=django&page=1&expansion=1&action=expand

Search operators

• Language is automatically selected from the HTTP headers of the query.
• Language can be enforced and directly specified within the query, such as :fr paris bars or :en django, see here for more details.

JSON Response

• http://www.seeks-project.info/search_exp.php/search?output=json&q=markov+chain&page=1&expansion=3&action=expand&rpp=2

yields:

{
      "snippets": [
            {
                "id": 753016643,
                "title": "Markov chain - Wikipedia, the free encyclopedia",
                "url": http://en.wikipedia.org/wiki/Markov_chain,
                "summary": "Wikipedia: If all states in a Markov chain are ergodic, then the chain is said to be ergodic...",
                "seeks_score": 3,
                "rank": 0.666667,
                "cite": "en.wikipedia.org/wiki/Markov_chain",
                "cached": "http://en.wikipedia.org/wiki/Markov_chain",
                "archive": "http://web.archive.org/web/*/http://en.wikipedia.org/wiki/Markov_chain",
                "engines": [
                      "google",
                      "cuil",
                      "yahoo"
                  ]
            },
            {
                "id": 284612170,
                "title": "Markov Chain",
                "url": "http://www.markovchain.net/",
                "summary": "This was the start of what would eventually become the cover band now known as Markov Chain […]",
                "seeks_score": 3,
                "rank": 9.33333,
                "cite": "markovchain.net",
                "cached": "http://x.x.x.x/search/cache?ei=UTF-8&p=markov+chain",
                "archive": "http://web.archive.org/web/*/http://www.markovchain.net/",
                 "engines": [
                      "google",
                      "yahoo",
                      "exalead"
                  ]
            }
      ]
    "date": "Thu, 06 May 2010 11:59:54 GMT",
    "qtime": 3.79
}

qtime is the processing time of the query by the Seeks node.

Groups of results obtained with action=clusterize and action=types are returned in the form:

     "clusters": [
            {
             "label": "markovchainmontecarlo monte time"
             "snippets": [ ... ]
             },
             {
             "label": "state edges states"
             "snippets": [ ... ]
             }
           ]
          "date": "Thu, 06 May 2010 11:59:54 GMT",
          "qtime": 3.79
}