Reference Guide

API Identifiers

When you register for access to the iWise Wisdom API you will recieve two identifiers:

• Public Key: Used to identify your account, you need to send in all requests
• Private Key: It's only used to sign your requests, it should never be sent on requests

Get your API keys

To obtain API access keys please sign up at http://api.iwise.com

Sign Requests

In order to sign your request, you need to create a string in the following way:

"{PUBLIC_KEY}{METHOD}{TIMESTAMP}"

This string must be hashed with your private key, the hash algorithm used is SHA1, in PHP you can do it in the following way:

$signature = base64_encode(mhash(MHASH_SHA1, $str_sign, $private_key));

Create a function in PHP:

function signRequest($public_key, $method, $timestamp) {
	$str_sign = "{$public_key}{$method}{$timestamp}";
	return base64_encode(mhash(MHASH_SHA1, $str_sign, $private_key));
}

API Requests

Format

iWise Wisdom API has a REST interface for calling, the url for calling the API is the following:

http://api.iwise.com/rest/

Limit

There is a limit of 1,000 operations per day (each call to a method counts as single operation), if you exceed this limit you will recieve a usage limit error.

Methods

All the methods on iWise Wisdom API needs to have the following params:

Name	Required	Description
public_key	required	Your public key provided by api
method	required	Name of the method to call
timestamp	required	Timestamp when call is generated
signature	required	Signature as described previously

Related Authors

To retrieve related authors you may to call the getRelatedAuthors method with the following parameters:

Name	Required	Description
query	required	search text
limit	optional (default: 5)	number of maximum authors (range: 1-20)

Return Example

<?xml version="1.0" encoding="UTF-8"?>
<iwise version="1.0">
	<response>
		<author>
			<item>
				<id>14203</id>
				<name>Ingersoll, Robert G.</name>
			</item>
			<item>
				<id>830</id>
				<name>Jonson, Ben</name>
			</item>
			<item>
				<id>1019</id>
				<name>Keller, Helen</name>
			</item>
			<item>
				<id>23</id>
				<name>Shakespeare, William</name>
			</item>
			<item>
				<id>12907</id>
				<name>Shakespeare.</name>
			</item>
		</author>
	</response>
	<status>success</status>
</iwise>

Author Search

You can search author name with method authorLookup which has the following params:

Name	Required	Description
query	required	search text
limit	optional (default: 5)	number of maximum authors (range: 1-20)

Return example

<?xml version="1.0" encoding="UTF-8"?>
<iwise version="1.0">
  <response>
    <author>
      <item>
        <id>12907</id>
        <name>Shakespeare.</name>
      </item>
      <item>
        <id>23</id>
        <name>Shakespeare, William</name>
      </item>
      <item>
        <id>11364</id>
        <name>Shakespeare, William</name>
      </item>
      <item>
        <id>3257</id>
        <name>Love, Davis III</name>
      </item>
      <item>
        <id>9880</id>
        <name>Thomas Love Peacock</name>
      </item>
    </author>
  </response>
  <status>success</status>
</iwise>

     

Related Tags

To get related tags you need to call the method: getRelatedTags with following params:

Name	Required	Description
query	required	search text

Return example

<?xml version="1.0" encoding="UTF-8"?>
      <iwise version="1.0">
		<response>
			<tags>
				<item>
					<tag>Love</tag>
					<score>0.31446028</score>
				</item>
				<item>
					<tag>Writers and Writing</tag>
					<score>0.13613743</score>
				</item>
				<item>
					<tag>Fiction</tag>
					<score>0.087363854</score>
				</item>
			</tags>
		</response>
		<status>success</status>
	</iwise>

Search

The basicSearch method does a search over quotes

Name	Required	Description
query	required	search text
page	required	nnumber of page (starting from 1)
items_page	required	items to show per page

Return Example

<?xml version="1.0" encoding="UTF-8"?>
<iwise version="1.0">
  <response>
    <total_items>5634</total_items>
    <total_pages>564</total_pages>
    <quotes>
      <item>
        <id>17050</id>
        <text>Love is too young to know what conscience is.</text>
        <author_name>Shakespeare, William</author_name>
        <tags>Love</tags>
        <url>http://www.iwise.com/5ovcV</url>
        <score>0.5964395</score>
      </item>
      <item>
        <id>35557</id>
        <text>Love all, but trust a few.</text>
        <author_name>Shakespeare, William</author_name>
        <tags>Trust</tags>
        <url>http://www.iwise.com/iNeDM</url>
        <score>0.5964395</score>
      </item>
    </quotes>
  </response>
  <status>success</status>
</iwise>

Wisdom Search

The wisdomSearch method does a search over quotes and also return related authors and related tags, the params are the same as search

The return of wisdomSearch contains the return of getRelatedAuthor, getRelatedTags and search through blocks in the following way:

<?xml version="1.0" encoding="UTF-8"?>
<iwise version="1.0">
  <response>
    <search>
      <total_items>5634</total_items>
      <total_pages>564</total_pages>
      <quotes>
        <item>
	...
        </item>
        <item>
	...
        </item>
      </quotes>
    </search>
    <related_authors>
      <author>
        <item>
	...
        </item>
        <item>
	...
        </item>
      </author>
    </related_authors>
    <related_tags>
      <tags>
        <item>
	...
        </item>
        <item>
	...
        </item>
      </tags>
    </related_tags>
  </response>
  <status>success</status>
</iwise>

API Test

There is an example where you can test the methods of the api, you only need to provide your public key and private key:
http://api.iwise.com/docs/examples/api-test.php

Also you can see the source code of how it works:
http://api.iwise.com/docs/examples/api-test.phps