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:
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
The following is a list of all valid parameters in a search request. All except q and type are optional. Default values are marked with (d).
| Parameters | Valid values | Types | Description |
|----------------|--------------|-------|--------------------------------------|
| q (required) | (see query) | all | 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/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 | integer | all | Default 0. Start index of first |
| | | | result in search response. |
| | | | startIndex + pageSize must be less |
| | | | than 1000 |
| pageSize | 10...30 | all | Number of results to return in |
| | | | search response, default 10. |
| sortBy | sorting | 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 character, encoded with |
| | | | a + in URIs! |
| responseParams | field names | all | Field list should be comma |
| | | | separated, or a single '*' |
| | | | character. Returns additional fields |
| | | | beside default values. When a * |
| | | | specified all possible values are |
| | | | returning. |
| jsonCallback | string | all | Must match regex |
| | | | "^[a-zA-Z0-9._\[\]]+$". 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. |
- To see the fields returned for these search types, see the response section and the Appendix.
- The see how these parameters are used in searches, check out the examples and the Getting started guide.
- All text parameters are case insensitive.
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
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. Separate each with a space. Use + or - to require or exclude individual terms. Remember that special characters including space must be URL encoded!
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.