WordStream API interface class for WordPress

wordstream-api-class.php

<?php 

/**
 * Class containing all the functionality to get data from the WordStream API
 *
 * @link http://api.wordstream.com/doc/introduction
 *
 * @author Joost de Valk <joost@yoast.com>
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 *
 * @since 1.1
 *
 * @package WPSEO_WordStream
 */
class WPSEO_WordStream {

	private $session_id  = '';
	private $cache_group = 'wpseo_wordstream';
	public $last_error   = '';
	public $logged_in    = false;
	
	/**
	 * Constructor
	 *
	 * @since 1.1
	 */
	function __construct() {
		// Set a session ID
		$this->login();
	}

	/**
	 * Helper function that grabs a URL from WordStream, checks the return statements, caches and returns the body if OK.
	 *
	 * @since 1.1
	 * @param string $url API URL to call.
	 * @param boolean $cache Whether or not to cache this request, defaults to true.
	 * @return object $ret The returned object data
	 */
	private function get_url( $url, $cache = true ) {

		$key = md5( $url );
		
		if ( $cache && $cached_res = wp_cache_get( $key, $this->cache_group ) ) { 
			return $cached_res;
		} else {
			$ret = wp_remote_get( 'https://api.wordstream.com/' . $url );

			if ( is_wp_error( $ret ) ) {
				$this->last_error = __('An error occurred while trying to reach the WordStream API.');
				return false;
			}
			
			$ret = json_decode( $ret['body'] );

			if ( 'OK' != $ret->code ) {
				switch( $ret->code ) {
					case 'INSUFFICIENT_CREDITS':
						$this->last_error = __('Insufficient API Credits.');
						break;
					case 'ERROR':
						$this->last_error = str_replace( 'href="/', 'href="http://www.wordstream.com/', $ret->error );
						break;
				}
				return false;
			}

			// FIXME: the cache needs an expiration time depending on how long session_id is valid, will need to inquire after 
			// validity as it's not documented.
			if ( $cache )
				wp_cache_add( $key, $ret->data, $this->cache_group );
				
			return $ret->data;
		}
	}

	/**
	 * Grabs a Session ID from the WordStream API service and set the class variable $session_id to that value
	 * 
	 * @link http://api.wordstream.com/doc/?n=root.API_REFERENCE.authentication.login
	 * @since 1.1
	 * @uses $session_id class variable used for authentication
	 */
	private function login() {
		$options = get_option( 'wpseo_wordstream' );
		
		$ret = $this->get_url( sprintf( 'authentication/login?username=%s&password=%s', $options['username'], $options['password'] ) );

		if ( $ret ) {
			$this->session_id = $ret->session_id;
			$this->logged_in  = true;
			return true;
		}
		
		return false;
	}

	/**
	 * Logs out of the current session and invalidates the session token.
	 *
	 * @link http://api.wordstream.com/doc?n=root.API_REFERENCE.authentication.logout
	 * @since 1.1
	 */
	private function logout() {
		$this->get_url( sprintf( 'authentication/logout?session_id=%s', $this->session_id ) );
	}

	/**
	 * Grabs the number of remaining monthly credits
	 *
	 * @link http://api.wordstream.com/doc?n=root.API_REFERENCE.authentication.get_api_credits
	 * @since 1.1
	 * @return object two values, credits_per_month and remaining_monthly_credits
	 */
	public function get_credits() {
		return $this->get_url( sprintf( 'authentication/get_api_credits?session_id=%s', $this->session_id ), false );
	}
	
	/**
	 * Grabs Keyword Niches for seed keyword
	 *
	 * @link http://api.wordstream.com/doc?n=root.API_REFERENCE.keywordtool.get_keyword_niches
	 * @since 1.1
	 * @param $seed string the seed words for which to get the niches
	 * @param $max the maximum number of results to return
	 * @return $keywords array of keyword niches
	 */
	public function get_keyword_niches( $seed, $max ) {
		if ( is_array( $seed ) )
			$seed = implode( "\n", $seed );
		return $this->get_url( sprintf( 'keywordtool/get_keyword_niches?seeds=%s&max_niches=%d&session_id=%s', urlencode( $seed ), $max, urlencode( $this->session_id ) ) );
	}
	
	/**
	 * Grabs Keyword Volumes for seed keywords
	 *
	 * @since 1.1
	 * @link http://api.wordstream.com/doc?n=root.API_REFERENCE.keywordtool.get_keyword_volumes
	 * @param $keywords array the keywords for which to get the volumes
	 * @return $keywords array of keywords
	 */
	public function get_keyword_volumes( $keywords ) {
		$keywords = implode( "\n", (array) $keywords );
		return $this->get_url( sprintf( 'keywordtool/get_keyword_volumes?keywords=%s&session_id=%s', urlencode( $keywords ), urlencode( $this->session_id ) ) );
	}
	
	/**
	 * Grabs Keywords for seed keyword
	 *
	 * @link http://api.wordstream.com/doc?n=root.API_REFERENCE.keywordtool.get_keywords
	 * @since 1.1
	 * @param $seed string the seed words for which to get the keywords
	 * @param $max the maximum number of results to return
	 * @return $keywords array of keywords
	 */
	public function get_keywords( $seed, $max ) {
		if ( is_array( $seed ) )
			$seed = implode( "\n", $seed );
		return $this->get_url( sprintf( 'keywordtool/get_keywords?seeds=%s&max_results=%d&session_id=%s', urlencode( $seed ), $max, urlencode( $this->session_id ) ) );
	}

	/**
	 * Grabs Question Keywords for seed keyword
	 *
	 * @since 1.1
	 * @link http://api.wordstream.com/doc/?n=root.API_REFERENCE.keywordtool.get_question_keywords
	 * @param $seed string the seed words for which to get the related keywords
	 * @param $max the maximum number of results to return
	 * @return $keywords array of keywords
	 */
	public function get_question_keywords( $seed, $max ) {
		if ( is_array( $seed ) )
			$seed = implode( "\n", $seed );
		return $this->get_url( sprintf( 'keywordtool/get_question_keywords?seeds=%s&max_results=%d&session_id=%s', urlencode( $seed ), $max, urlencode( $this->session_id ) ) );
	}
	
	/**
	 * Grabs Related Keywords for seed keyword
	 *
	 * @since 1.1
	 * @link http://api.wordstream.com/doc?n=root.API_REFERENCE.keywordtool.get_related_keywords
	 * @param $seed string the seed words for which to get the related keywords
	 * @param $max the maximum number of results to return
	 * @return $keywords array of keywords
	 */
	public function get_related_keywords( $seed, $max ) {
		if ( is_array( $seed ) )
			$seed = implode( "\n", $seed );
		return $this->get_url( sprintf( 'keywordtool/get_related_keywords?seeds=%s&max_results=%d&session_id=%s', urlencode( $seed ), $max, urlencode( $this->session_id ) ) );
	}
		
}