MSN Search API PHP Client

Microsoft has recently published their own MSN Search API (now competing with Google and Yahoo) implemented as a SOAP Web Service. After some deliberation on the MSN Search API forums, I managed to develop a small PHP class to handle the API (thanks to quodlibet for his help identifying a small bug.)

The class uses nuSOAP for interacting with the SOAP server. You will need to download nuSOAP and copy it inside a folter named nusoap, located in the same location as this class’ file.

The source code for the class is the following (save it as MSNWebSearch.class.php):

<?php

define ('NUSOAP_PATH', dirname(__FILE__) . '/nusoap');
define ('MSN_API_KEY', 'Insert here your default MSN API key');
define ('MSN_API_ENDPOINT', 'http://soap.search.msn.com/webservices.asmx');
define ('MSN_API_NAMESPACE', 'http://schemas.microsoft.com/MSNSearch/2005/09/fex');

require_once(NUSOAP_PATH . '/nusoap.php');

class MSNWebSearch
{
	var $apiKey;
	var $filterAdult;
	var $languages;
	var $page;
	var $pages;
	var $query;
	var $records;
	var $recordsPerPage;

	function &MSNWebSearch($apiKey = null)
	{
		$this->apiKey = isset($apiKey) ? $apiKey : MSN_API_KEY;
		$this->filterAdult = false;
		$this->languages = 'en-US';
		$this->recordsPerPage = 10;
		$this->page = 1;
	}

	function getApiKey()
	{
		return $this->apiKey;
	}

	function setApiKey($apiKey)
	{
		$this->apiKey = $apiKey;
	}

	function getErrorMessage()
	{
		return $this->errorMessage;
	}

	function getFilterAdult()
	{
		return $this->filterAdult;
	}

	function setFilterAdult($filterAdult)
	{
		$this->filterAdult = $filterAdult;
	}

	function getLanguages()
	{
		return $this->languages;
	}

	function setLanguages($languages)
	{
		$this->languages = $languages;
	}

	function getPage()
	{
		return $this->page;
	}

	function setPage($page)
	{
		if ($page < 1)
		{
			$page = 1;
		}

		$this->page = $page;
	}

	function getPages()
	{
		return $this->pages;
	}

	function getQuery()
	{
		return $this->query;
	}

	function setQuery($query)
	{
		$this->query = $query;
	}

	function getRecords()
	{
		return $this->records;
	}

	function getRecordsPerPage()
	{
		return $this->recordsPerPage;
	}

	function setRecordsPerPage($recordsPerPage)
	{
		$this->recordsPerPage = is_int($recordsPerPage) && $recordsPerPage > 0 ? $recordsPerPage : 10;
	}

	function get()
	{
		$startIndex = ($this->page - 1) * $this->recordsPerPage;
		$elementsCount = $this->recordsPerPage;

		$parameters = array(
			'AppID' => $this->apiKey,
			'Query' => $this->query,
			'CultureInfo' => $this->languages,
			'SafeSearch' => ($this->filterAdult ? 'Strict' : 'Off'),
			'Requests' => array (
				'SourceRequest' => array (
					'Source' => 'Web',
					'Offset' => $startIndex,
					'Count' => $elementsCount,
					'ResultFields' => 'All'
				)
			)
		);

		if (isset($this->country))
		{
			$parameters['Location'] = $this->country;
		}

		$soapClient =& new soapclient(MSN_API_ENDPOINT);

		$soapResult = $soapClient->call('Search', array ('Request' => $parameters), MSN_API_NAMESPACE );

		if ($soapClient->getError())
		{
			$this->errorMessage = $soapClient->getError();

			return false;
		}

		$this->records = $soapResult['Responses']['SourceResponse']['Total'];
		$this->pages = ceil($this->records / $this->recordsPerPage);

		if (is_array($soapResult['Responses']['SourceResponse']['Results']))
		{
			$result = array();

			foreach ($soapResult['Responses']['SourceResponse']['Results'] as $item)
			{
				$result[] = array (
					'url' => $item['Url'],
					'urlDisplay' => $item['DisplayUrl'],
					'urlCache' => $item['CacheUrl'],
					'title' => isset($item['Title']) && trim($item['Title']) != '' ? $item['Title'] : $item['DisplayUrl'],
					'snippet' => $item['Description']
				);
			}
		}
		else
		{
			$result = array();
		}

		return $result;
	}
}
?>

The usage of this class is quite simple. Take a look at the following index.php file to see an example. You can see it working here. Please note that where it says 'My MSN API Key', you need to insert your own MSN API Key. If you don’t have one, get one now.

<?php
require_once(dirname(__FILE__) . '/MSNWebSearch.class.php');

if (isset($_GET) && isset($_GET['query']) && trim($_GET['query']) != '')
{
	$currentPage = 1;

	if (isset($_GET['page']))
	{
		$currentPage = $_GET['page'];
	}

	$msnSearch =& new MSNWebSearch();

	$msnSearch->setApiKey('My MSN API Key');
	$msnSearch->setQuery($_GET['query']);
	$msnSearch->setPage($currentPage);

	$result =& $msnSearch->get();

	if ($result !== false)
	{
		if ($msnSearch->getPages() > 1)
		{
			$navigation = array();

			$navigation['pages'] = $msnSearch->getPages();

			if ($msnSearch->getPage() > 1)
			{
				$navigation['back'] = $PHP_SELF . '?page=' . ($msnSearch->getPage() - 1) . '&query=' . urlencode($msnSearch->getQuery());
			}

			if ($msnSearch->getPage() < $msnSearch->getPages())
			{
				$navigation['next'] = $PHP_SELF . '?page=' . ($msnSearch->getPage() + 1) . '&query=' . urlencode($msnSearch->getQuery());
			}
		}
	}
}
?>
<html>
	<head>
		<titlevMSN Web Search</title>
	</head>
	<body>
		<center><p>
			<form action="<?php echo $PHP_SELF; ?>" method="GET">
				Search:
				<input type="text" name="query" size="70" value="<?php echo isset($_GET['query']) ? $_GET['query'] : ''; ?>" />
				<input type="submit" value="Search" />
				<?php
				if (isset($msnSearch) && $result !== false)
				{
				?>
				<br />
				<b><?php echo $msnSearch->getRecords(); ?></b> records matched your query.
				<?php
				}
				?>
			</form>
		</p></center>
		<?php
		if (isset($msnSearch) && $result === false)
		{
			?>
			There was an error with your search. Error message: <b><?php echo $msnSearch->getErrorMessage(); ?></b>.
			<?php
		}
		else if (isset($msnSearch))
		{
			if (isset($navigation))
			{
			?>
			<center><p>
				Pages: <b><?php echo $msnSearch->getPages(); ?></b>
				<?php
				if (isset($navigation['back']))
				{
				?>
				<a href="<?php echo $navigation['back']; ?>">Previous</a>
				<?php
				}

				if (isset($navigation['back']) && isset($navigation['next']))
				{
				?>
				|
				<?php
				}

				if (isset($navigation['next']))
				{
				?>
				<a href="<?php echo $navigation['next']; ?>">Next</a>
				<?php
				}
				?>
			</p></center>
			<?php
			}
			?>
			<ul>
			<?php
			foreach ($result as $item)
			{
			?>
			<li>
				<a href="<?php echo $item['url']; ?>"><?php echo $item['title']; ?></a>: <?php echo $item['snippet']; ?>
				<br />
				<font color="#008000"><?php echo $item['urlDisplay']; ?></font> - <a href="<?php echo $item['urlCache']; ?>">Cache</a>
			</li>
			<?php
			}
			?>
			</ul>
			<?php
		}
		?>
	</body>
</html>

Hope this helps anyone.

UPDATE [Aug 20, 2006]: After receiving some emails saying that the class didn’t work (which in fact does), I decided to publish a ZIP file that contains a working MSN Search Based Page. It includes nuSOAP as of July 19, 2006. First, download the ZIP file. Then, uncompress to a new directory on your webserver and EDIT the file index.php, looking for line 3. Insert your MSN API KEY there. After specifying your API key, you should be good to go for testing.

Related posts:

1. Get a taste of AJAX with PHP