Problem

You want to build a page about someone like Barack Obama or Steve Jobs or some organization like Google or NBA.

Topics are pre-defined people, organizations, places, diseases, issues, events and products in the daylife eco-system.

Things you can put on a topic page:

• Top relevant Stories in recent times
• Photos related to the topic (you will need your own licenses with Getty, AP and/or Reuters)
• Top Quotes said by the topic or about the topic
• Other Topics that are connected to your topic (a.k.a. Connections)
• A timeline of coverage in mainstream news and blogs over a period of time
• An abstract from wikipedia giving basic information about the topic 

Read more below to see the code (in PHP) that builds this page.

 You can also make the following customizations on these topic page: 

• Show data in a time range that you want for e.g. today, past week, past month or any custom time interval
• Show results only from a particular set of sources (what we call source filtering)
• Show results in a chronologically sorted or relevance sorted order
• Show 10 or 20 or 30 results or as many as you want 

Pre-requisites

There are only a very few things you need to do before you can start playing with the DayPIs.

a. Signup on our Developer site

b. Wait for an email that sends you a set of API credentials - an Accesskey and a Sharedsecret

Once you have your API credentials, you are ready to build your topic pages.

Solution

DayPIs suite of Topic APIs help you build these topic pages. If you follow the simple set of steps below, building a full topic page will be a piece of cake. I have tried to illustrate the steps using PHP code.

Step 0: Get a daypi client and configure your api credentials

The developer site has sample code for simple clients in several programming languages that talk to the DayPI. I will use the one in PHP for illustrating the steps below.

#Include the client in your code base
include_once('publicapi.php');

#configure the daylife api server url here
$daylife_server = "freeapi.daylife.com";
$protocol = "jsonrest";
$version = "4.4";
$publicapi_access_url = "http://" . $daylife_server . "/" . $protocol . "/publicapi/"	 . $version . "/";

#configure your api credentials here
$accesskey = "8befa1cf0a7c0291613242235638a662";
$sharedsecret = "2e548ef751397c653752057adcff0c9f"; 
	
#initialize your api client	 
$publicapi = new PublicApi($publicapi_access_url, $accesskey, $sharedsecret)

Step 1: Get a topic name or a topic id

This is the trickiest and most important part of building topic pages. You need a handle, either, a full topic name (as in the daylife system) or a topic id to make any Topic API call. There are a few ways that you will have one of these handles:

• You have a pre-defined list of names or topic ids
• You have a name. You can call search_getMatchingTopics to get list of all topics that have a matching name.

search_getMatchingTopics(query="Hillary Clinton", .......)

• You have a topic name or a topic id returned by an API call that returns you connections

$params = array(
	'query' => 'Hillary Clinton'
	);

#get Matching Topics
$matching_topics = $publicapi->search_getMatchingTopics($params); 

Once you have the topic name, initialize your parameters for subsequent API calls.

Step 2: Get Stories

topic_getRelatedStories gives you a list of stories for a particular topic.

#initialize your parameters
$params = array(
	'name' => 'Hillary Rodham Clinton',        # topic name
	'end_time' => time()                # Current time in epochs
	'start_time' => time() - (7*86400)    # Current time minus 7 days in epoch
	'sort' => 'date',                        # sort by relevance or date
	'limit' => 10,                             # number of results
	);
#make the API call
$stories = $publicapi->topic_getRelatedStories($params);

Here is a sample request: http://freeapi.daylife.com/xmlrest/publicapi/4.4/topic_getRelatedStories?name=Hillary%20Rodham%20Clinton&start_time=2008-02-22&end_time=2008-02-29&sort=date&offset=0&limit=10&accesskey=8befa1cf0a7c0291613242235638a662&signature=504aca2cd086b3f46a2510a7d4cc74c1

Step 3: Get Photos

topic_getRelatedImages returns photos for a topic. You will need your own licenses with Getty, AP or Reuters and  a source_filter_id from us to get back images. Please contact us at developer@daylife.com to get a source filter.

#initialize your parameters
$params = array(
	'name' => 'Hillary Rodham Clinton',			# topic name
	'end_time' => time()					# Current time in epochs
	'start_time' => time() - (7*86400)		# Current time minus 7 days in epoch
	'sort' => 'date',							# sort by relevance or date
	'limit' => 10,								# number of results,
	'source_filter_id' => $img_source_filter_id	# source filter provided by daylife on request
);

#make the API call
$images = $publicapi->topic_getRelatedImages($params);

Here is a sample request (you will need to put your source_filter_id):
http://freeapi.daylife.com/xmlrest/publicapi/4.4/topic_getRelatedImages?name=Hillary%20Rodham%20Clinton&start_time=2008-02-22&end_time=2008-02-29&sort=date&offset=0&limit=10&source_filter_id=%3Cyour%20source%20filter%20id%3E&accesskey=8befa1cf0a7c0291613242235638a662&signature=504aca2cd086b3f46a2510a7d4cc74c1

Step 4a: Get Quotes said by the topic

topic_getQuotesBy returns quotes said by a topic.

#initialize your parameters
$params = array(
	'name' => 'Hillary Rodham Clinton',		# topic name
	'end_time' => time()				# Current time in epochs
	'start_time' => time() - (7*86400)	# Current time minus 7 days in epoch
	'sort' => 'date',						# sort by relevance or date
	'limit' => 10,							 # number of results
	'include_topic_type' => array('person',
		'place', 'organization')		# types of connections to return
);

#make the API call
$quotes_by = $publicapi->topic_getQuotesBy($params);

Here is a sample request:
http://freeapi.daylife.com/xmlrest/publicapi/4.4/topic_getQuotesBy?name=Hillary%20Rodham%20Clinton&start_time=2008-02-22&end_time=2008-02-29&offset=0&limit=10&sort=date&accesskey=8befa1cf0a7c0291613242235638a662&signature=504aca2cd086b3f46a2510a7d4cc74c1
 

Step 4b: Get Quotes about the topic

topic_getRelatedQuotes returns quotes from articles that are related to the topic.

#initialize your parameters
$params = array(
	'name' => 'Hillary Rodham Clinton',		# topic name
	'end_time' => time()				# Current time in epochs
	'start_time' => time() - (7*86400)	# Current time minus 7 days in epoch
	'sort' => 'date',						# sort by relevance or date
	'limit' => 10,							 # number of results
);

#make the API call
$quotes_about = $publicapi->topic_getRelatedQuotes($params);

Here is a sample request:
http://freeapi.daylife.com/xmlrest/publicapi/4.4/topic_getRelatedQuotes?name=Hillary%20Rodham%20Clinton&start_time=2008-02-22&end_time=2008-02-29&offset=0&limit=10&sort=date&accesskey=8befa1cf0a7c0291613242235638a662&signature=504aca2cd086b3f46a2510a7d4cc74c1
 

Step 5: Get Connections

topic_getRelatedTopics returns quotes from articles that mention the topic

#initialize your parameters
$params = array(
	'name' => 'Hillary Rodham Clinton',			# topic name
	'end_time' => time()					# Current time in epochs
	'start_time' => time() - (7*86400)		# Current time minus 7 days in epoch
	'sort' => 'date',							# sort by relevance or date
	'limit' => 10,								# number of results,
	'include_image' => 1						# include a thumbnail for each connection
);

#make the API call
$connections = $publicapi->topic_getRelatedTopics($params);

Here is a sample request:
http://freeapi.daylife.com/xmlrest/publicapi/4.4/topic_getRelatedTopics?name=Hillary%20Rodham%20Clinton&start_time=2008-02-22&end_time=2008-02-29&sort=date&offset=0&limit=10&include_topic_type=person&include_topic_type=organization&include_topic_type=place&include_image=1&accesskey=8befa1cf0a7c0291613242235638a662&signature=504aca2cd086b3f46a2510a7d4cc74c1

Step 6: Get Timeline Data

topic_getTimeline returns a digest of number of mentions in news and blogs for the topic on  per day basis.

#initialize your parameters
$params = array(
	'name' => 'Hillary Rodham Clinton',			# topic name
	'end_time' => time()					# Current time in epochs
	'start_time' => time() - (7*86400)		# Current time minus 7 days in epoch
);

#make the API call
$stories = $publicapi->topic_getTimeline($params);

Here is a sample request:

http://freeapi.daylife.com/xmlrest/publicapi/4.4/topic_getTimeline?name=Hillary%20Rodham%20Clinton&start_time=2008-02-22&end_time=2008-02-29&accesskey=8befa1cf0a7c0291613242235638a662&signature=504aca2cd086b3f46a2510a7d4cc74c1

Step 7: Get the wikipedia abstract and a thumbnail image for the topic

topic_getInfo

#initialize your parameters
$params = array(
	'name' => 'Hillary Rodham Clinton',	# topic name
	'include_wikipedia_info' => 1		# return wikipedia abstract for the topic
	'include_image' =>	1				# return one thumbnail for the topic
);

#make the API call
$info = $publicapi->topic_getInfo($params);

Here is a sample request:
http://freeapi.daylife.com/xmlrest/publicapi/4.4/topic_getInfo?name=Hillary%20Rodham%20Clinton&include_image=1&include_wikipedia_info=1&accesskey=8befa1cf0a7c0291613242235638a662&signature=504aca2cd086b3f46a2510a7d4cc74c1