NAME
WWW::SEOGears - Perl Interface for SEOGears API.
VERSION
Version 0.04
SYNOPSIS
This module provides you with an perl interface to interact with the Seogears API.
use WWW::SEOGears;
my $api = WWW::SEOGears->new( { 'brandname' => $brandname,
'brandkey' => $brandkey,
'sandbox' => $boolean
});
$api->newuser($params_for_newuser);
$api->statuscheck($params_for_statuscheck);
$api->inactivate($params_for_inactivate);
$api->update($params_for_update);
$api->get_tempauth($params_for_update);SUBROUTINES/METHODS
new
Constructor.
Input takes a hashref that contains:
Required:
brandname => Brandname as listed on seogears' end.
brandkey => Brandkey received from seogears.
Will croak if the above keys are not present.
Optional:
sandbox => If specified the sandbox API url is used instead of production.
http_opts => Hashref of options that are passed on to the HTTP::Tiny object that is used internally.
Example value: { 'agent' => 'WWW-SEOGears', 'timeout' => 20, 'verify_SSL' => 0, 'SSL_options' => {'SSL_verify_mode' => 0x00} }
Deprecated (will be dropped in the upcoming update): Will emit a warning if used.
lwp => hash of options for LWP::UserAgent - will be converted to their corresponding HTTP::Tiny options.
Example value: {'parse_head' => 0, 'ssl_opts' => {'verify_hostname' => 0, 'SSL_verify_mode' => 0x00}}newuser
Creates a new user via the 'action=new' API call. Since the 'userid' and 'email' can be used to fetch details about the seogears account, storing these values locally is recommended.
Input Requires that you pass in the following parameters for the call:
userid => '123456789'
email => 'test1@testing123.com'
name => 'Testing User'
phone => '1.5552223333'
domain => 'somedomain.com'
rep => 'rep@domain.com'
placement => 'reg'
pack => '32'
price => '14.99'
months => '12'Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.
Output Hash containing the data returned by the API:
"success" => 1
"authkey" => "GB0353566P163045n07157LUFGZntgqNF042MO692S19567CIGHj727437179300tE5nt8C362803K686Yrbj4643zausyiw"
"bzid" => "30928"
"debuginfo" => "Success"
"message" => "New Account Created"statuscheck
Fetches information about a user via the 'action=statuscheck' API call.
Input Requires that you pass in the following parameters for the call:
userid => '123456789'
email => 'test1@testing123.com'Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.
Output Hash containing the data returned by the API:
"success" => 1,
"inactive" => "0"
"authkey" => "WO8407914M283278j87070OPWZGkmvsEG847ZB845Q28584YSBDt684478133472pV3ws1X655571X005Zlhh6810hsxjjka"
"bzid" => "30724"
"brand" => "brandname"
"message" => User is active. See variables for package details."
"expdate" => "2014-01-01 12:00:00"
"debuginfo" => "User exists. See variables for status and package details."
"pack" => "32"
"price" => "14.99"
"months" => "12"inactivate
Inactivates a user via the 'action=inactivate' API call.
Input Requires that you pass in the following parameters for the call:
"bzid" => "30724"
"authkey" => "WO8407914M283278j87070OPWZGkmvsEG847ZB845Q28584YSBDt684478133472pV3ws1X655571X005Zlhh6810hsxjjka"Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.
Output Hash containing the data returned by the API:
'success' => 1,
'bzid' => '30724',
'debuginfo' => 'Success BZID30724 WO8407914M283278j87070OPWZGkmvsEG847ZB845Q28584YSBDt684478133472pV3ws1X655571X005Zlhh6810hsxjjka'activate
Activates a previously inactivated user via the 'action=activate' API call.
Input Requires that you pass in the following parameters for the call:
'bzid' => '32999'
'authkey' => 'BC1052837T155165x75618ZUKZDlbpfMW795RS245L23288ORUUq323360091155yP1ng7E548072L030Zssq0043pldkebf'Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.
Output Hash containing the data returned by the API:
'success' => 1,
'bzid' => '32999',
'debuginfo' => 'Success BZID32999 BC1052837T155165x75618ZUKZDlbpfMW795RS245L23288ORUUq323360091155yP1ng7E548072L030Zssq0043pldkebf'update
Updates/Renews a user via the 'action=update' API call.
Input Requires that you pass in the following parameters for the call:
"bzid" => "30724"
"authkey" => "WO8407914M283278j87070OPWZGkmvsEG847ZB845Q28584YSBDt684478133472pV3ws1X655571X005Zlhh6810hsxjjka"
Optional params:
"email" => "newemail@testing123.com"
"phone" => "1.5552224444"
"pack" => "33"
"months" => "24"
"price" => "14.99"If pack is specified, then a price must be specified along with it.
Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.
Output Hash containing the data returned by the API:
'success' => 1,
'bzid' => '30724',
'debuginfo' => 'Success'get_tempauth
Retrieves the tempauth key for an account from the API.
Input Requires that you pass in the following parameters for the call:
bzid => '31037'
authkey => 'HH1815009C705940t76917IWWAQdvyoDR077CO567M05324BHUCa744638889409oM8kw5E097737M626Gynd3974rsetvzf'Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.
Output Hash containing the data returned by the API:
'success' => 1,
'bzid' => '31037',
'tempauthkey' => 'OU8937pI03R56Lz493j0958US34Ui9mgJG831JY756X0Tz04WGXVu762IuIxg7643vV6ju9M96J951V430Qvnw41b4qzgp2pu',
'message' => ''get_templogin_url
Generates the temporary login URL with which you can access the seogears' control panel. Essentially acts as a wrapper that stringifies the data returned by get_tempauth.
Input Requires that you pass in either:
userid => '123456789'
email => 'test1@testing123.com'Or
bzid => '31037'
authkey => 'HH1815009C705940t76917IWWAQdvyoDR077CO567M05324BHUCa744638889409oM8kw5E097737M626Gynd3974rsetvzf'If the bzid/authkey are not provied, then it will attempt to look up the proper information using the userid and email provided.
Croaks if it is unable to sanitize the %params passed successfully, or the HTTP request to the API fails.
Output Returns the login url that can be used to access the control panel on SEOgears. Example: https://seogearstools.com/api/login.html?bzid=31037&tempauthkey=OU8937pI03R56Lz493j0958US34Ui9mgJG831JY756X0Tz04WGXVu762IuIxg7643vV6ju9M96J951V430Qvnw41b4qzgp2pu
get_userurl, get_authurl, get_loginurl
Return the corresponding api url that is being used.
get_error
Returns $self->{'error'}
get_brandname
Returns $self->{'brandname'}
get_brandkey
Returns $self->{'brandkey'}
Internal Subroutines
The following are not meant to be used directly, but are available if 'finer' control is required.
_make_request_handler
Wraps the call to _make_request and handles error checks.
INPUT Takes the 'action' and sanitized paramaters hashref as input.
Output Returns undef on failure (sets $self->{error} with the proper error). Returns a hash with the decoded json data from the API server if successful.
_make_request
Makes the HTTP request to the API server.
Input The full uri to perform the HTTP request on.
Output Returns an array containing the http response, and error. If the HTTP request was successful, then the error is blank. If the HTTP request failed, then the response is blank and the error is the status line from the HTTP response.
_stringify_params
Stringifies the content of a hash such that the output can be used as the URI body of a GET request.
Input A hashref containing the sanatizied parameters for an API call.
Output String with the keys and values stringified as so '&key1=value1&key2=value2'
_sanitize_params
sanitizes the data in the hashref passed for the action specified.
Input The 'action', and a hashref that has the data that will be sanitized.
Output Boolean value indicating success. The hash is altered in place as needed.
_check_params
Input: Three hashrefs that contain the following in the specified order:
1) the hashref to the params that need to be checked.
2) the hashref to the 'required' set of params
3) the hashref to the 'optional' set of paramsOutupt: Undef if everything is good. If errors are detected, it will:
either return a hashref that has two arrays:
'required_params' - which will list the required params that are missing. And
'blank_params' - which will list the params that have blank values specified for them.
or a string with a specific error message.This also 'prunes' the first hashref of params that are not specified in either the required or the optional hashrefs.
_valid_months
Returns true if the 'months' value specified is a valid. Currently, you can set renewals to occur on a monthly or yearly (upto 3 years), so the valid values are:
1
12
24
36_get_apiurl
Depending on the action passed, it will return the initial part of the URL that you can use along with the _stringify_params method to generate the full GET url.
Valid actions and the corresponding strings that are returned:
'auth' => get_authurl().'?'
'login' => get_loginurl().'?'
'new' => get_userurl().'?action=new'
'statuscheck' => get_userurl().'?action=statuscheck'
'inactivate' => get_userurl().'?action=inactivate'
'update' => get_userurl().'?action=update'If no valid action is specified, it will set the $self->{error} and return;
_error
Internal method that is used to report and set $self->{'error'}.
It will croak if called with a true second argument. Such as:
$self->_error($msg, 1);_months_from_now
Internal helper method that will calculate the expiration date thats x months in the future - calculated via Date::Calc's Add_Delta_YMDHMS().
_translate_lwp_to_http_opts
Helper method that translates the passed in LWP opts hashref to a corresponding HTTP::Tiny opts hashref.
AUTHOR
Rishwanth Yeddula, <ryeddula@cpan.org>
ACKNOWLEDGMENTS
Thanks to Hostgator.com for funding the development of this module and providing test resources.
BUGS
Please report any bugs or feature requests to bug-www-seogears at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-SEOGears. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WWW::SEOGearsYou can also review the API documentation provided by SEOgears for more information.
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
LICENSE AND COPYRIGHT
Copyright 2014 Rishwanth Yeddula.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.
If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.
This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.
This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.
Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.