Search API - Getting started

Read this quick guide, and start searching right away.

Find jamie

Say you wanted to find publications about jamie.

Search strings

To search, you send a valid search string. You saw one above:

undefined
http://search.issuu.com/api/2_0/document?q=jamie

The term q (query) is required for every search, the query is what you are searching for. The query string can be almost anything you like (we'll get back to that later), and there is no distinction between lower- and upper-case.

For different types of search the API provides different entry points, and they defines how the search is done. You already seen the entry point for document search but you have more options:

URI type
http://search.issuu.com/api/2_0/document documents, including title, description and tags
http://search.issuu.com/api/2_0/page pages of a given document or all documents of a user

Paging and sorting

Some searches will return many results, so how do we handle that? The total number of results returned by a search is limited to 1000, and a single request can return up to 30 results at a time.

undefined
pageSize=[0 ... 30 ]
startIndex=[0 ... start+num < 1000 ]

pageSize is the number of results to return per request (if not specified, the default is 10). startIndex is the result to start with (default is 0, i.e. the first result).

For example, if you perform a search that returns many results, you can get the first 30 results back in a single query:

undefined
http://search.issuu.com/api/2_0/document?q=art&pageSize=30

Or as two queries, each returning 15 results:

undefined
http://search.issuu.com/api/2_0/document?q=art&pageSize=15
http://search.issuu.com/api/2_0/document?q=art&pageSize=15&startIndex=15

You can also sort the search results by specifying a sortBy field, with the optional reverse to switch the sort order. Some of the available sortBy fields are listed below. The sort fields available depend on the type of search. Take a look at the search results for the different types of searches to get an idea of the fields available, or check out the list in the Appendix.

undefined
sort=[epoch | views | rating | username | docname |  ... ]

To change ordering append asc or desc with a space to field name.
With proper encoding it's like views+asc or rating+desc.

For example, to find the jamie-related publication viewed most often:

undefined
http://search.issuu.com/api/2_0/document?q=jamie&pageSize=1&sortBy=views

Or the 10 newest users on Issuu interested in art:

undefined
http://search.issuu.com/api/2_0/us?q=art&sortBy=epoch

Query strings

When you specify a simple query like q=jamie only certain fields are searched by default. The fields searched depend on the type of search.

Type Fields searched
Document search title, content, description, tag
Page search page text only

You can search within specific fields by using the field names in your query. For example, to search for publications with "art" in the title

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

Use + or - to require or exclude terms. Separate query terms with a space. Enclose query terms with quotes if they include spaces. You can also search for a range of values (for valid fields like dates or page numbers). When you specify more query terms the default relationship is AND without explicitely stating but you could use OR and AND freely just specify them in all capitals.

Search engine returns the minimal required information by default but specifying a responseParams item with a coma separated list of additional items you have the possibility request more information in a single query.

To find all publications that are tagged either with jamie or cooking but without the phrase "breakfast food" in the title, returns tags and pagecount for each, sorted by pagecount:

undefined
http://search.issuu.com/api/2_0/document?q=-title:"breakfast%20foods"+tag:cooking+OR+tag:jamie&responseParams=tag,pagecount&sortBy=pagecount

Formats

The default response format of a search is JSON, but you can get your results in JSONP format when specifying a callback function with jsonCallback.

undefined
http://search.issuu.com/api/2_0/document?q=jamie&jsonCallback=myCallback

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.

Learn more...

To learn more about the Issuu Search API, take a look at some more of our examples or browse the API reference.