AlchemyAPI · AlchemyAPI · May 16, 2014 · May 14, 2014 · May 14, 2014 · May 15, 2014
diff --git a/README.md b/README.md
@@ -57,6 +57,51 @@ To use each function, you must first create an AlchemyAPI object. The easiest wa
 
 You can now use this object to access AlchemyAPI's text analysis functions. 
 
+### Image Keywords ###
+
+The Image Keywords API tags an image identified by a URL or image data posted in the body of an html request. For more high-level information on AlchemyAPI's Image keywords API, please visit: http://www.alchemyapi.com/products/features/image-tagging. For more technical information, please refer to the docs: http://www.alchemyapi.com/api/image-tagging.
+
+To extract entities, use:
+
+	<?php
+		$response = $alchemyapi->image_keywords(FLAVOR, DATA, OPTIONS);
+	?>
+
+Where FLAVOR can be 'url' or 'image' DATA is your url or uri-argument encoded image data, and OPTIONS is an array containing the optional parameters to modify the behavior of the call.
+
+
+**Options**
+
+The following options are available for this call. To use, include your desired options into an array and pass it as the OPTIONS parameter in the call. 
+
+-	imagePostMode -> (only applicable to image flavor)
+-		not-raw :  pass an unencoded image file with "image=URI_ENCODED_DATA"
+-		raw     :  pass an unencoded image file using POST
+-	extractMode -> 
+-     always-infer    :  (more CPU intensive, more accurate)
+-     trust-metadata  :  (less CPU intensive, less accurate) (default)
+-     only-metadata   :  (even less CPU intensive, less accurate)
+
+**Parsing**
+
+To parse the results, simply step through the response structure that is detailed in the docs. For example, here's how to print the keyword and score of each tagged image:
+
+	<?php
+		$response = $alchemyapi->image_keywords('url','http://www.lolcats.com/images/u/08/50/lolcatsdotcomur5dhkw464f8hb16.jpg', null);
+		foreach ($response['imageKeywords'] as $imagekeyword) {
+			echo 'keyword: ', $imagekeyword['text'], PHP_EOL;
+			echo 'score: ', $imagekeyword['score'], PHP_EOL;
+		}
+	?>
+
+This should print out:
+
+	keyword: cat
+	score: 0.999697
+	keyword: kitten
+	score: 0.942676
+
+
 
 
 ### Entities ###

diff --git a/alchemyapi.php b/alchemyapi.php
@@ -99,12 +99,54 @@ public function AlchemyAPI() {
 		$this->_ENDPOINTS['combined']['url'] = '/url/URLGetCombinedData';
 		$this->_ENDPOINTS['combined']['text'] = '/text/TextGetCombinedData';
 		$this->_ENDPOINTS['image']['url'] = '/url/URLGetImage';
+		$this->_ENDPOINTS['image_keywords']['url'] = '/url/URLGetRankedImageKeywords';
+		$this->_ENDPOINTS['image_keywords']['image'] = '/image/ImageGetRankedImageKeywords';
 		$this->_ENDPOINTS['taxonomy']['url'] = '/url/URLGetRankedTaxonomy';
 		$this->_ENDPOINTS['taxonomy']['html'] = '/html/HTMLGetRankedTaxonomy';
 		$this->_ENDPOINTS['taxonomy']['text'] = '/text/TextGetRankedTaxonomy';
 	}
 
 
+
+	/**
+	  *	Returns tag for an image URL or image included in the body of the http request.
+	  *	For an overview, please refer to: http://www.alchemyapi.com/products/features/image-tagging/ 
+	  *	For the docs, please refer to: http://www.alchemyapi.com/api/image-tagging/
+	  *	
+	  *	INPUT:
+	  *	flavor -> which version of the call, i.e. url or image.
+	  *	image -> the image to analyze, either the url or image data.
+	  *	options -> various parameters that can be used to adjust how the API works, see below for more info on the available options.
+	  *	
+	  *	Available Options:
+	  *	imagePostMode -> (only applicable to image flavor)
+	  *		not-raw :  pass an unencoded image file with "image=URI_ENCODED_DATA"
+	  *		raw     :  pass an unencoded image file using POST
+	  *	extractMode -> 
+	  *     always-infer    :  (more CPU intensive, more accurate)
+	  *     trust-metadata  :  (less CPU intensive, less accurate) (default)
+	  *     only-metadata   :  (even less CPU intensive, less accurate)
+	  *
+	  *	OUTPUT:
+	  *	The response, already converted from JSON to a PHP object. 
+	*/
+	public function image_keywords($flavor, $image, $options) {
+		//Make sure this request supports the flavor
+		if (!array_key_exists($flavor, $this->_ENDPOINTS['image_keywords'])) {
+			return array('status'=>'ERROR','statusInfo'=>'Image tagging for ' . $flavor . ' not available');
+		}
+
+		//Add the image to the options and analyze
+		if($flavor=='url'){
+			$options[$flavor] = $image;
+			return $this->analyze($this->_ENDPOINTS['image_keywords'][$flavor], $options);
+		}
+		else{
+			return $this->analyzeImage($this->_ENDPOINTS['image_keywords'][$flavor], $options, $image);	
+		}
+	}
+
+
 	/**
 	  *	Extracts the entities for text, a URL or HTML.
 	  *	For an overview, please refer to: http://www.alchemyapi.com/products/features/entity-extraction/ 
@@ -694,6 +736,30 @@ private function analyze($endpoint, $params) {
 		//Create the HTTP header
 		$header = array('http' => array('method' => 'POST','header'=>'Content-Type: application/x-www-form-urlencode', 'content'=>http_build_query($params)));
 
+		//Fire off the HTTP Request
+		try {
+			$fp = @fopen($url, 'rb',false, stream_context_create($header));
+			$response = @stream_get_contents($fp);
+			fclose($fp);
+			return json_decode($response, true);
+		} catch (Exception $e) {
+			return array('status'=>'ERROR', 'statusInfo'=>'Network error');
+		}
+	}
+	//Use to create request for image API
+		private function analyzeImage($endpoint, $params, $imageData) {
+
+
+		//Add the API Key and set the output mode to JSON
+		$params['apikey'] = $this->_api_key;
+		$params['outputMode'] = 'json';
+
+		//Insert the base URL
+		$url = $this->_BASE_URL . $endpoint . '?' . http_build_query($params);
+
+		//Create the HTTP header
+		$header = array('http' => array('method' => 'POST','header'=>'Content-Type: application/x-www-form-urlencode', 'content'=>$imageData));
+
 		//Fire off the HTTP Request
 		try {
 			$fp = @fopen($url, 'rb',false, stream_context_create($header));

diff --git a/example.php b/example.php
@@ -23,7 +23,6 @@
 	$demo_url = 'http://www.npr.org/2013/11/26/247336038/dont-stuff-the-turkey-and-other-tips-from-americas-test-kitchen';
 	$demo_html = '<html><head><title>PHP Demo | AlchemyAPI</title></head><body><h1>Did you know that AlchemyAPI works on HTML?</h1><p>Well, you do now.</p></body></html>';
 
-
 	echo PHP_EOL;
 	echo PHP_EOL;  
 	echo '            ,                                                                                                                              ', PHP_EOL;
@@ -49,7 +48,74 @@
 	echo '          :~                                                                                                                               ', PHP_EOL;
 
 
+	echo PHP_EOL;
+	echo PHP_EOL;
+	echo '############################################', PHP_EOL;
+	echo '#       Image Keyword Example              #', PHP_EOL;
+	echo '############################################', PHP_EOL;
+	echo PHP_EOL;
+	echo PHP_EOL;
+
+	echo 'Processing Image URL: ', $demo_url, PHP_EOL;
+	echo PHP_EOL;
+
+	$response = $alchemyapi->image_keywords('url', $demo_url, array('extractMode'=>'trust-metadata'));
+
+	if ($response['status'] == 'OK') {
+		echo '## Response Object ##', PHP_EOL;
+		echo print_r($response);
+
+		echo PHP_EOL;
+		echo '## Image Keywords ##', PHP_EOL;
+		foreach ($response['imageKeywords'] as $imageKeywords) {
+			echo 'image keyword: ', $imageKeywords['text'], PHP_EOL;	
+			echo 'score: ', $imageKeywords['score'], PHP_EOL;		
+			echo PHP_EOL;
+		}
+	} else {
+		echo 'Error in the image keyword extraction call: ', $response['statusInfo'];
+	}
+	echo PHP_EOL;
+	echo PHP_EOL;
+	echo PHP_EOL;
+	echo PHP_EOL;
+	/*
+	$imageName = "grumpy-cat-meme-hmmm.jpg";
+	$imageFile = fopen($imageName, "r") or die("Unable to open file!");
+	$imageData = fread($imageFile,filesize($imageName));
+	fclose($imageFile);
+
+
+	echo PHP_EOL;
+	echo PHP_EOL;
+	echo '############################################', PHP_EOL;
+	echo '#       Image Keyword Example with image   #', PHP_EOL;
+	echo '############################################', PHP_EOL;
+	echo PHP_EOL;
+	echo PHP_EOL;
+
+	echo 'Processing Image File: ', $imageName, PHP_EOL;
+	echo PHP_EOL;
+
+	$response = $alchemyapi->image_keywords('image', $imageData, array('imagePostMode'=>'raw'));
 
+	if ($response['status'] == 'OK') {
+		echo '## Response Object ##', PHP_EOL;
+		echo print_r($response);
+
+		echo PHP_EOL;
+		echo '## Image Keywords ##', PHP_EOL;
+		foreach ($response['imageKeywords'] as $imageKeywords) {
+			echo 'image keyword: ', $imageKeywords['text'], PHP_EOL;	
+			echo 'score: ', $imageKeywords['score'], PHP_EOL;		
+			echo PHP_EOL;
+		}
+	} else {
+		echo 'Error in the image keyword extraction call: ', $response['statusInfo'];
+	}
+	echo PHP_EOL;
+	echo PHP_EOL;*/
+	echo PHP_EOL;
 	echo PHP_EOL;
 	echo PHP_EOL;
 	echo '############################################', PHP_EOL;

diff --git a/grumpy-cat-meme-hmmm.jpg b/grumpy-cat-meme-hmmm.jpg
diff --git a/tests.php b/tests.php
@@ -23,7 +23,44 @@
 	$test_text = 'Bob broke my heart, and then made up this silly sentence to test the PHP SDK';  
 	$test_html = '<html><head><title>The best SDK Test | AlchemyAPI</title></head><body><h1>Hello World!</h1><p>My favorite language is PHP</p></body></html>';
 	$test_url = 'http://www.nytimes.com/2013/07/13/us/politics/a-day-of-friction-notable-even-for-a-fractious-congress.html?_r=0';
+	$imageName = "grumpy-cat-meme-hmmm.jpg";
+	$imageFile = fopen($imageName, "r") or die("Unable to open file!");
+	$imageData = fread($imageFile,filesize($imageName));
+	fclose($imageFile);
 
+	//image keywords
+	echo 'Checking image keywords . . . ', PHP_EOL;
+	$response = $alchemyapi->image_keywords('url', $test_url, null);
+	assert($response['status'] == 'OK');
+	$response = $alchemyapi->image_keywords('image', $imageData, array('imagePostMode'=>'raw'));
+	assert($response['status'] == 'OK');
+	$response = $alchemyapi->image_keywords('random', $test_url, null);
+	assert($response['status'] == 'ERROR');	//invalid flavor
+	echo 'Image keyword tests complete!', PHP_EOL, PHP_EOL;
+
+	//image extraction
+	echo 'Checking image extraction . . . ', PHP_EOL;
+	$response = $alchemyapi->imageExtraction('url',$test_url, null);
+	assert($response['status'] == 'OK');
+	$response = $alchemyapi->imageExtraction('random', $test_url, null);
+	assert($response['status'] == 'ERROR');	//invalid flavor
+	echo 'Image extraction tests complete!', PHP_EOL, PHP_EOL;
+
+	//taxonomy
+	echo 'Checking Taxonomy . . . ', PHP_EOL;
+	$response = $alchemyapi->taxonomy('text',$test_text, null);
+	assert($response['status'] == 'OK');
+	$response = $alchemyapi->taxonomy('random', $test_text, null);
+	assert($response['status'] == 'ERROR');	//invalid flavor
+	echo 'Taxonomy tests complete!', PHP_EOL, PHP_EOL;
+
+	//combined
+	echo 'Checking Combined . . . ', PHP_EOL;
+	$response = $alchemyapi->combined('text',$test_text, null);
+	assert($response['status'] == 'OK');
+	$response = $alchemyapi->combined('random', $test_text, null);
+	assert($response['status'] == 'ERROR');	//invalid flavor
+	echo 'Combined tests complete!', PHP_EOL, PHP_EOL;
 
 	//Entities
 	echo 'Checking entities . . . ', PHP_EOL;