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”.
For all document related searches use:
To search inside a given document for relevant pages use:
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.|
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:
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:
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
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.