Read this quick guide, and start searching right away.
Say you wanted to find publications about jamie.
- Open your browser.
- Type or copy-paste this into the address field of your browser:
http://search.issuu.com/api/2_0/document?q=jamie
- You should get something like this in return.
{
"response": {
"start": 0,
"numFound": 24830,
"docs": [
{
"docname": "jamie_cullum-catching_tales-so",
"username": "jazzjeppe",
"documentId": "081222014257-84334c46304345bdacf74e0e70ab5f07"
},
{
"docname": "jamie_oliver_-__genial_kochen_",
"username": "nuhsarche",
"documentId": "090213204230-d57667b328944876912a8b9764408209"
},
{
"docname": "jamie_oliver",
"username": "hahaha",
"documentId": "090315001951-b165f0eb652d49918101fe36ab97d335"
},
{
"docname": "vanguard",
"username": "vanguard_jamie",
"documentId": "080508035242-f066fb3e528c43c8b15ff2daf3bc43ce"
},
{
"docname": "album",
"username": "purdue_alumni",
"documentId": "100211204537-d8cd2f738baa4753972d965741138f27"
},
{
"docname": "thompson_ferraro_-_sculpture_annual",
"username": "thompsonferraro",
"documentId": "090625202154-a2f108b1513f47c6824b25bb5e26b43d"
},
{
"docname": "hknknk",
"username": "amandalimphotography",
"documentId": "080909174613-baaac30d52ab496b8abe4cc9fa68196d"
},
{
"docname": "intro1-30-minuteswimtest-08010",
"username": "csca.org",
"documentId": "090203221218-3aeb956500d14c5992fa6191a212b391"
},
{
"docname": "intro1-30-minuteswimtest-08010-1",
"username": "csca.org",
"documentId": "090304004142-f4c79dcad83c454c99913b7f1f185cf4"
},
{
"docname": "jamie_foxx-nba-allstar_pr-2-",
"username": "societybluepr",
"documentId": "100316023731-b4b0d4010c57458eaf209051e307c8bd"
}
]
}
}
To search, you send a valid search string. You saw one above:
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 |
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.
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:
http://search.issuu.com/api/2_0/document?q=art&pageSize=30
Or as two queries, each returning 15 results:
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.
sort=[epoch | rating | username | docname | ... ]
To change ordering append asc or desc with a space to field name.
With proper encoding it's like rating+asc or rating+desc.
For example, to find the jamie-related publication rated highest:
http://search.issuu.com/api/2_0/document?q=jamie&pageSize=1&sortBy=rating
Or the 10 newest users on Issuu interested in art:
http://search.issuu.com/api/2_0/us?q=art&sortBy=epoch
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
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:
http://search.issuu.com/api/2_0/document?q=-title:"breakfast%20foods"+tag:cooking+OR+tag:jamie&responseParams=tag,pagecount&sortBy=pagecount
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.
http://search.issuu.com/api/2_0/document?q=jamie&jsonCallback=myCallback
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.
To learn more about the Issuu Search API, take a look at some more of our examples or browse the API reference.