Search API - Search Request

Sending a search request

The issuu search request is a standard HTTP GET command, which returns results in JSON format. A search request is composed of series of name-value pairs, defining the search parameters. Users make search requests through custom application, or by entering search parameters in a HTML form. An example of a possible form follows:

<form method="GET" action="http://search.issuu.com/api/2_0/document">
  <input type="text" name="q" size="40" maxlength="256" value="query string">
  <input type="submit" name="search_button" value="Search">
</form>

Alternatively, a web application may make a HTTP GET request directly:

GET /api/2_0/document?q=query+string HTTP/1.1

Each of these examples results in the same search request. The response to this request contains the first set of search results for the query “query string”, restricted to records of the type “document”.

Entry points

For all document related searches use:

http://search.issuu.com/api/2_0/document

To search inside a given document for relevant pages use:

http://search.issuu.com/api/2_0/page

Parameters

The following is a list of all valid parameters in a search request. All except q and type are optional. Default values are in green.

Parameters Valid values Search types Description
q (see query subsection) all (required) Query string
documentId string all Search within a document. Either documentId or username should be specified for page search.
username string all Search within a user’s public documents. Either documentId or username should be specified for page search.
timeframe string all Search only for the specified time interval from now. Valid arguments are 1day, 1week, 1month and 1year.
explicit 0 or 1 all By default search is restricted to none explicit documents only, to get this behaviour specify a 0 as argument value. To search within explicit documents as well specify 1. Please note, if you provide a valid cookie that setting will override the specified value.
language string all Restrict search only to documents categorized with a given Language Code, specified as a valid two letter ISO639 abbrevation.
startIndex 0…start+num < 1000 all Start index of first result in search response
pageSize 10…30 all Number of results to return in search response
sortBy (see Appendix) all Field to sort by (works on int, float and untokenized text fields including dates). Order by default is high to low. To specify ordering append a space and asc or desc after the field name. Please note, space is a special charecter, encoded with a + in URIs!
responseParams a comma separated list of field names (see Appendix) or a single * character all Returns additional fields beside default values. When a * specified all possible values are returning.
jsonCallback match regex “^[a-zA-Z0-9._[]]+$” all When format is json, the jsonCallback name will wrap the JSON-response. If “?” is given then an anonymous method is used.
- integer all Helper to break browsers caches, values are ignored.

Query strings

When you specify a simple query like q=bacon there are multiple fields are searched by default. The fields and their weight at search depends on the type of search.

You can search within specific fields (see Appendix) by using the field names in your query. For example, to search for publications with “art” in the title:

http://search.issuu.com/api/2_0/document?q=title:art

Some fields are tokenized, others are indexed in raw form. If a field is tokenized, you can search for individual tokens (words or symbols) within the field. The title field is tokenized, so a search for “art” in the title will match any title containing the word “art”. Raw fields must be searched exactly as indexed. All fields not listed below are tokenized.

The following are raw text or mixed fields:

username
tag
documentId
docname
photo
language

The following are raw numeric fields:

pageId
views
rating
total
position
pagecount

A search for a value within a certain range can be performed on raw numeric fields. The range must be specified in the form “[low TO high]”. Instead of number you should use a * character for the extreme. For example:

pagecount:[3 TO 5]

You also use quotes when a value includes spaces:

title:"modern art"

You can build more complicated queries including many fields. Seperate each with a space. Use + or - to require or exclude individual terms. Remember that special characters including space must be URLencoded!

To find “art” in the title, with the tag “book”, and without a “creative” or “zine” tag:

+title:art +tag:book -tag:creative -tag:zine

Authentication

If you perform a search using your browser while logged in to issuu, your issuu user id and authentication token are sent as cookies along with the request. This will result in your profile settings being applied to the search results. If you do not send an authentication cookie, your search will be performed as an anonymous user.