Home > Codehead Web Services

Codehead Web Services

Codehead Search Engine API; how to write your own Search Application in ~150 lines of code

We launched Codehead Web Services a while ago and have introduced 2 APIs so far [A Website Thumnail API and a Search Engine API].

Our goal is to provide some cool functionality that is rather hard to implement through a set of simple web services/APIs so users can create and enhance their own applications.

Here is a full working search engine using the Codehead Search Engine API:

<?php
 
	error_reporting(E_ALL);
 
	/* Save sort order and match mode prefrences in a session variable */
	session_start();
 
	/* Set default values for sort, match_mode and search_section */
	if (!isset($_SESSION['sort']))
		$_SESSION['sort'] = 'relevance_date';
 
	if (!isset($_SESSION['match_mode']))
		$_SESSION['match_mode'] = 'any';
 
	if (!isset($_SESSION['search_section']))
		$_SESSION['search_section'] = 'articles';
 
	include 'libs/codehead_api/codehead_api.php';
	$ch = new Codehead_API();
 
	/* Assume there is a $_GET['q'], @ makes sure PHP won't trow E_NOTICE and if there is no $_GET['q'] then $q will be empty or '' */
	$q = trim(@$_GET['q']);
 
	/* $rpp is results per page */
	$rpp = 25;
 
	/* $start is where to start the next page; at what item number? 10, 20, 50? This usually comes from a pager */
	$start = intval(@$_GET['start']);
 
	/* Whether or not the user want to change sort, match_mode or search section */
	if (isset($_GET['sort']))
		$_SESSION['sort'] = $_GET['sort'];
 
	if (isset($_GET['match_mode']))
		$_SESSION['match_mode'] = $_GET['match_mode'];
 
	if (isset($_GET['search_section']))
		$_SESSION['search_section'] = $_GET['search_section'];
 
?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Search - Powered By Codehead Search API</title>
 
	<style type="text/css">
		input { vertical-align: middle; }
	</style>
 
</head>
 
<body>
 
<!-- The search form -->
<form method="get" action="">
Search For: <input type="text" name="q" value="<?php echo __escape($q); ?>" /> <input type="submit" value="  GO  " />
</form>
Search in:
	<a href="?q=<?php echo __escape($q); ?>&search_section=articles">Articles</a> -
   <a href="?q=<?php echo __escape($q); ?>&search_section=forums">Forums</a> -
   <a href="?q=<?php echo __escape($q); ?>&search_section=jobs">Jobs</a> -
   <a href="?q=<?php echo __escape($q); ?>&search_section=news">News</a> -
   <a href="?q=<?php echo __escape($q); ?>&search_section=blogs">Blogs</a> - It's '<?php echo $_SESSION['search_section']; ?>' right now
<br />
Sort by:
	<a href="?q=<?php echo __escape($q); ?>&sort=relevance_date">Relevance Date</a> -
   <a href="?q=<?php echo __escape($q); ?>&sort=relevance">Relevance Only</a> -
   <a href="?q=<?php echo __escape($q); ?>&sort=date">Date Only</a> - It's '<?php echo $_SESSION['sort']; ?>' right now
<br />
Matching Mode:
	<a href="?q=<?php echo __escape($q); ?>&match_mode=any">Any Keyword</a> -
   <a href="?q=<?php echo __escape($q); ?>&match_mode=all">All Keywords</a> -
   <a href="?q=<?php echo __escape($q); ?>&match_mode=exact">Exact Match</a> - It's '<?php echo $_SESSION['match_mode']; ?>' right now
<br /><br />
 
<?php
 
	/* If $q is not empty, do the search */
	if ($q != '') {
 
		/* Do the actual search, note how simple and painless it is! */
		$results = $ch->search->do_search($_SESSION['search_section'], $q, $start, $rpp, $_SESSION['sort'], $_SESSION['match_mode']);
 
		/* Error checking is always necessary! */
		if ($ch->has_error) {
 
			echo 'OOPS! there was a temporary error.';
			/* If you want to display the internal error, go ahead and do */
 
		} else {
 
			/* All good, loop through and display the results */
			// echo '<pre>'; print_r($results); exit;
 
			if ($results['total'] > 0) {
 
				echo "Results $start to " .($start + $rpp) ." out of around {$results['total']} total results; search took {$results['search_time']} second(s)!<br /><br />";
 
				/* Show the previous/next page link */
				if ($results['total'] > $rpp && ($start + $rpp) < $results['total'])
					echo "<a href=\"?q=$q&start=" .($start + $rpp) ."\">Next $rpp results</a>";
 
				if ($start >= $rpp)
					echo " - <a href=\"?q=$q&start=" .($start - $rpp) ."\">Previous $rpp results</a><br /><br />";
				else
					echo "<br /><br />";
 
				foreach ($results['results'] as $id => $result) {
					/* Very rarely, some items might be deleted from the index so this check is necessary */
					if (!isset($result['title']))
						continue;
				?>
					<a href="<?php echo __escape($result['url']); ?>"><?php echo __escape($result['title']); ?></a><br />
					<small>From: <?php echo __escape($result['source_title']); ?> <?php echo __escape($result['formated_date']); ?></small><br />
					<?php echo __escape($result['content']); ?><br />
				<?php
					/* Codehead Search groups results for news stories */
					if (isset($result['grouped'])) {
						foreach ($result['grouped'] as $gresult) {
						?>
							<small><a href="<?php echo __escape($gresult['url']); ?>"><?php echo __escape($gresult['title']); ?></a> - <span style="color: #999999;"><?php echo __escape($gresult['source_title']); ?></span></small><br />
                  <?php
						}
					}
					echo '<br />';
				}
 
				/* Show the previous/next page link */
				if ($results['total'] > $rpp && ($start + $rpp) < $results['total'])
					echo "<a href=\"?q=$q&start=" .($start + $rpp) ."\">Next $rpp results</a>";
 
				if ($start >= $rpp)
					echo " - <a href=\"?q=$q&start=" .($start - $rpp) ."\">Previous $rpp results</a>";
 
			} else {
				echo 'Your search didn\'t match any documents.';
			}
 
		}
 
	}
 
?>
 
</body>
</html>
 
<?php
 
	function __escape($str) {
		return htmlentities($str, ENT_QUOTES, 'utf-8');
	}
 
?>

It’s very easy to understand this code but I’ll try to explain a few things about how it works.

Here is the full documentation of our Search Engine API:

Simple Usage

Here is the simplest way of searching our database for the term ‘PHP Sessions’:

<?php
 
/* Include and instantiate Codehead_API here, if you don't know how, read from the beginning of this documentation */
 
$results = $ch->search->do_search('articles', 'PHP Sessions');
 
if (!$ch->has_error) {
	if ($results['total'] > 0) {
 
		foreach ($results['results'] as $id => $result) {
			/* Very rarely, some items might be deleted from the index so this check is necessary */
			if (!isset($result['title']))
				continue;
		?>
			<a href="<?php echo __escape($result['url']); ?>"><?php echo __escape($result['title']); ?></a><br />
			<small>From: <?php echo __escape($result['source_title']); ?> <?php echo __escape($result['formated_date']); ?></small><br />
			<?php echo __escape($result['content']); ?><br />
		<?php
			/* Codehead Search groups results for news stories */
			if (isset($result['grouped'])) {
				foreach ($result['grouped'] as $gresult) {
				?>
					<small><a href="<?php echo __escape($gresult['url']); ?>"><?php echo __escape($gresult['title']); ?></a> - <span style="color: #999999;"><?php echo __escape($gresult['source_title']); ?></span></small><br />
				<?php
				}
			}
			echo '<br />';
		}
 
	} else {
		echo 'Your search didn\'t match any documents.';
	}
}
 
?>
<br />
			The function __escape() is not necessary but we like to escape EVERYTHING before printing, this function is very simple:<br /><br />
<pre lang="php">
<?php
 
function __escape($str) {
	return htmlentities($str, ENT_QUOTES, 'utf-8');
}
 
?>

Methods

There are 6 methods that you can use to retrieve search results:

<?php
 
array do_search(string $section, string $search_term [, int $offset [, int $results_per_page [, string $sort_mode [, string $match_mode]]]] )
 
array articles(string $search_term [, int $offset [, int $results_per_page [, string $sort_mode [, string $match_mode]]]] )
array jobs(string $search_term [, int $offset [, int $results_per_page [, string $sort_mode [, string $match_mode]]]] )
array forums(string $search_term [, int $offset [, int $results_per_page [, string $sort_mode [, string $match_mode]]]] )
array blogs(string $search_term [, int $offset [, int $results_per_page [, string $sort_mode [, string $match_mode]]]] )
array news(string $search_term [, int $offset [, int $results_per_page [, string $sort_mode [, string $match_mode]]]] )
 
?>

Below are detailed descriptions of these arguments and the reply from the server…

Search Sections

Codehead Search Engine API has 5 sections for searching:

1 – forums
2 – articles
3 – blogs
4 – news
5 – jobs

You could search these sections directly like:
```
<?php
 
$results = $ch->search->jobs('Python');
 
?>
```
Or use the generic do_search method like:
```
<?php
 
$results = $ch->search->do_search('jobs', 'Java');
 
?>
```
!!!Please note that, the default section is ‘articles’ so if you misspell the section or pass in an empty section, the API will respond with all the articles matching your term!!!
Offset and Results Per Page (RPP)

The offset is the start offset in which you want the results; if you have a pager and a user clicks on ‘Page 2′ then you must pass in the starting offset of the page 2. The default value for offset is 0 which means starting at the beginning of the result set.

Results per page (RPP) is the number of search results that you want to show on each of your SERP pages. Valid values for RPP are 10 or 25 and the default value is 10.

As an example, suppose you are showing 10 search results per page so the starting offset of your page 3 would be 3 * 10 or 30 so:
```
<?php
 
$results = $ch->search->do_search('news', 'bing', 30, 10);
 
?>
```
Will display the page 3.
Sort Mode

This is the mode in which the Search Engine API will sort your search results and valid values are:

relevance_date

Which will sort your results in order of relevance to the search term and also their freshness, this is our prefered mode.

relevance – Also Default

Will only sort your results based on their relevance to the search term. This is the default value for $sort_mode.

date

Will only sort your results based on date and it’s the least favorite sorting mode.

Examples
```
<?php
 
$results = $ch->search->do_search('news', 'bing', 30, 10, 'relevance_date');
/* or */
$results = $ch->search->do_search('news', 'bing', 30, 10, 'relevance');
/* or */
$results = $ch->search->do_search('news', 'bing', 30, 10, 'date');
 
?>
```
Match Mode

There are 3 matching modes:

any

This will tell the Search Engine API to match any of the keywords in your search term, for example if your search term is ‘SEO Jobs’, the API will return all the documents with either ‘SEO’ or ‘Jobs’ in them and that will include documents with both keywords in them too.

all – Also Default

Will return all the documents with all the keywords in them. This is also the default $match_mode.

exact

This will match all the documents with all the keywords in them but this time it will make sure that the keywords will appear in the exact order in the search term. This is basically phrase match, for example if your search term is ‘PHP Jobs Las Vegas’, the Search Engine API will return all the documents with the exact phrase ‘PHP Jobs Las Vegas’ in them.

Examples
```
<?php
 
$results = $ch->search->do_search('news', 'bing', 30, 10, 'relevance_date', 'any');
/* or */
$results = $ch->search->do_search('news', 'bing', 30, 10, 'relevance_date', 'all');
/* or */
$results = $ch->search->do_search('news', 'bing', 30, 10, 'relevance_date', 'exact');
 
?>
```
All About The Results Array

The return value of any of the above methods is an array that contains the search results along with some data about the search.

The components of this array are:

1 – results – Which is an array containing the search results.
2 – total – Is the total number of matches, this is useful when building pagers.
3 – encoding – Is the encoding of the items in the result.
4 – time_now – The current time of the server in Unix timestamp.
5 – start – The start offset of the results.
6 – rpp – Results per page.
7 – sort – Sort mode.
8 – match_mode – Match mode.
9 – search_time – The time it took to perform the search in milliseconds.

!!!Please note that, each item in the ‘results’ might contain another sub-array named ‘grouped’ which are the results that were similar to that item; this will only be the case when you search the news!!!

The best way to examine the ‘results’ array is to perform a search and then print_r() the results.
```
<?php
 
$results = $ch->search->do_search('blogs', 'snow leopard', 30, 10, 'relevance_date', 'any');
print_r($results);
 
?>
```

Any problems with the API? You can create a support ticket in your Codehead Webservice Account under Account > Help.

Good Luck

P.S. Check out the original Codehead Search, our super-fast, custom search engine, where you can scour the best content on the net for computer and web related jobs, forum posts, articles and tutorials, blog posts and news stories all in one place.

Comments (0) Filed under: Codehead Web Services,PHP,Programming,Search Engines,Web Development Posted by: Codehead

Back To Previous Page

Codehead Web Services

Codehead Search Engine API; how to write your own Search Application in ~150 lines of code

Simple Usage

Methods

Search Sections

Offset and Results Per Page (RPP)

Sort Mode

relevance_date

relevance – Also Default

date

Examples

Match Mode

any

all – Also Default

exact

Examples

All About The Results Array

CODEHEAD

Downloads

Categories

RSS Feed

Search

Codehead Web Services

Codehead Search Engine API; how to write your own Search Application in ~150 lines of code

Simple Usage

Methods

Search Sections

Offset and Results Per Page (RPP)

Sort Mode

relevance_date

relevance – Also Default

date

Examples

Match Mode

any

all – Also Default

exact

Examples

All About The Results Array

CODEHEAD

Downloads

Categories

RSS Feed

Search

Tags