NAME
WWW::StatsMix - Interface to StatsMix API.
VERSION
Version 0.05
DESCRIPTION
StatsMix provides an API that can be used to create, retrieve, update, and delete metrics and stats resources. The API is built using RESTful principles.
The current version is 2.0.
To get an API key, you can sign up for a free Developer account here.
If you go over the number of API requests available to your account, the API will return a 403 Forbidden error and an explanation. The number of API requests and profiles you can create is based on the type of account you have. For example, Standard plans are limited to 300,000 API requests per month.
SYNOPSIS
Use Strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your API Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $metric_1 = $api->create_metric({ name => "Testing - 1" });
my $metric_2 = $api->create_metric({ name => "Testing - 2", include_in_email => 0 });
$api->update_metric($metric_2->id, { name => "Testing - 3", include_in_email => 1 });
my $metrics = $api->get_metrics;
my $only_2 = $api->get_metrics({ limit => 2 });METHODS
create_metric(\%params)
It creates new metric and returns the object of type WWW::StatsMix::Metric.The possible parameters for the method are as below:
+------------------+-----------------------------------------------------------------------+
| Key | Description |
+------------------+-----------------------------------------------------------------------+
| name | The name of the metric. Metric names must be unique within a profile. |
| (required) | |
| | |
| profile_id | The profile the metric belongs in. |
| (optional) | |
| | |
| sharing | Sharing status for the metric. Either "public" (unauthenticated users |
| (optional) | can view the metric at the specific URL) or "none" (default). |
| | |
| include_in_email | This specifies whether to include the metric in the daily |
| (optional) | StatsMix email sent to users. |
| | |
| url | Publicly accessible URL for the metric (only if sharing is set |
| (optional) | to "public"). |
+------------------+-----------------------------------------------------------------------+
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $metric = $api->create_metric({ name => "Testing API - 2" });
print "Id: ", $metric->id, "\n";update_metric($metric_id, \%params)
It updates the metric & returns the object of type WWW::StatsMix::Metric. This requires mandatory param 'metric_id' and atleast one of the following key as ref to hash format data. Possible parameters are as below:
+------------------+-----------------------------------------------------------------------+
| Key | Description |
+------------------+-----------------------------------------------------------------------+
| name | The name of the metric. Metric names must be unique within a profile. |
| | |
| sharing | Sharing status for the metric. Either "public" (unauthenticated users |
| | can view the metric at the specific URL) or "none" (default). |
| | |
| include_in_email | This specifies whether to include the metric in the daily |
| | StatsMix email sent to users. |
| | |
| url | Publicly accessible URL for the metric (only if sharing is set |
| | to "public"). |
+------------------+-----------------------------------------------------------------------+
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $metric_id = <your_metric_id>;
my $metric = $api->update_metric($metric_id, { name => "Testing API - new" });
print "Name: ", $metric->name, "\n";delete_metric($metric_id)
It deletes the metric and returns the object of type WWW::StatsMix::Metric. It requires mandatory 'metric_id'.
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $metric_id = <your_metric_id>;
my $metric = $api->delete_metric($metric_id);
print "Name: ", $metric->name, "\n";get_metrics(\%params)
The method get_metrics() will return a default of up to 50 records. The parameter limit can be passed to specify the number of records to return. The parameter profile_id can also be used to scope records to a particular profile. Parameters start_date & end_date can be used to limit the date range based on the timestamp in a stat's generated_at. The result of the call is reference to list of WWW::StatsMix::Metric objects.
+------------+---------------------------------------------------------------+
| Key | Description |
+------------+---------------------------------------------------------------+
| limit | Limit the number of metrics. Default is 50. |
| (optional) | |
| | |
| profile_id | Scope the search to a particular profile. |
| (optional) | |
| | |
| start_date | Limit the searh in date range against stats generated_at key. |
| / end_date | Valid format is YYYY-MM-DD. |
| (optional) | |
+------------+---------------------------------------------------------------+
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $profile_id = <your_profile_id>;
my $limit = <your_limit_count>;
my $metrics_all = $api->get_metrics;
my $metrics_by_limit = $api->get_metrics({ limit => $limit });
my $metrics_by_profile = $api->get_metrics({ profile_id => $profile_id });create_stat(\%params)
The method create_stat() creates stat for the given metric. You can also create stat with ref_id. It returns an object of type WWW::StatsMix::Stat.
+--------------+----------------------------------------------------------------------------+
| Key | Description |
+--------------+----------------------------------------------------------------------------+
| metric_id | The metric id for which the stat would be created. |
| (required) | |
| | |
| value | The numeric value of the stat with a decimal precision of two. Decimal (up |
| (required) | to 11 digits on the left side of the decimal point, two on the right). |
| | |
| generated_at | Datetime for the stat. If not set, defaults to the current timestamp. This |
| (optional) | is the datetime to be used in the charts. Valid format is YYYY-MM-DD. |
| | |
| meta | hash ref data (key,value pair) about anything associated with the stat. |
| (optional) | |
| | |
| ref_id | Optional reference id for a stat. If a stat already exists for the named |
| (optional) | metric and the given ref_id, the value (and optionally generated_at and |
| | meta) will be updated instead of created. |
| | |
+--------------+----------------------------------------------------------------------------+
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $metric_id = <your_metric_id>;
my $value = <your_new_stat_value>;
my $params = { metric_id => $metric_id, value => $value };
my $stat = $api->create_stat($params);
print "Id: ", $stat->id, "\n";get_stat($metric_id, \%params)
Returns the stat details of the given stat of the metric. The stat can be either search by stat id or ref id. The return data is of type WWW::StatsMix::Stat.It requires mandatory key 'metric_id'. If both 'id' and 'ref_id' are defined then 'id' takes the precedence.
+--------+------------------------------------------------------------------+
| Key | Description |
+--------+------------------------------------------------------------------+
| id | The stat id of the stat. Required only if 'ref_id' is undefined. |
| | |
| ref_id | Ref id of the stat. Required only if 'id' is undefined. |
+--------+------------------------------------------------------------------+
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $metric_id = <your_metric_id>;
my $stat_id = <your_metric_stat_id>;
my $stat_ref_id = <your_metric_stat_ref_id>;
my $stat_by_id = $api->get_stat($metric_id, { id => $stat_id });
my $stat_by_ref_id = $api->get_stat($metric_id, { ref_id => $stat_ref_id });
print "Stat by Id (name) : ", $stat_by_id->name, "\n";
print "Stat by Ref Id (name): ", $stat_by_ref_id->name, "\n";update_stat($metric_id, \%params)
Update the stat of the metric.Stat can be located by stat id or ref id.Parameters for the method are as below. The return data is of type WWW::StatsMix::Stat.It requires mandatory key 'metric_id' and params as hash ref. Following keys can be passed in hash ref. If both 'id' and 'ref_id' are defined then 'id' takes the precedence.
+------------+----------------------------------------------------------------------------+
| Key | Description |
+------------+----------------------------------------------------------------------------+
| value | The numeric value of the stat with a decimal precision of two. Decimal (up |
| (required) | to 11 digits on the left side of the decimal point, two on the right). |
| | |
| id | The stat id of the stat. Required only if 'ref_id' is undefined. |
| | |
| ref_id | Ref id of the stat. Required only if 'id' is undefined. |
+------------+----------------------------------------------------------------------------+
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $metric_id = <your_metric_id>;
my $value = <your_stat_new_value>;
my $stat_id = <your_metric_stat_id>;
my $stat_ref_id = <your_metric_stat_ref_id>;
my $stat_by_id = $api->update_stat($metric_id, { id => $stat_id, value => $value });
my $stat_by_ref_id = $api->update_stat($metric_id, { ref_id => $stat_ref_id, value => $value });
print "Stat by Id (value) : ", $stat_by_id->value, "\n";
print "Stat by Ref Id (value): ", $stat_by_ref_id->value, "\n";delete_stat($metric_id, \%params)
Delete the stat of the metric.Stat can be located by stat id or ref id.Parameters for the method are as below. The return data is of type WWW::StatsMix::Stat.It requires mandatory key 'metric_id' and params as hash ref. The hash ref can have either 'id' or 'ref_id'. If both specified then 'id' takes the precedence.
+--------+------------------------------------------------------------------+
| Key | Description |
+--------+------------------------------------------------------------------+
| id | The stat id of the stat. Required only if 'ref_id' is undefined. |
| | |
| ref_id | Ref id of the stat. Required only if 'id' is undefined. |
+--------+------------------------------------------------------------------+
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $metric_id = <your_metric_id>;
my $stat_id = <your_metric_stat_id>;
my $stat_ref_id = <your_metric_stat_ref_id>;
my $stat_by_id = $api->delete_stat($metric_id, { id => $stat_id });
my $stat_by_ref_id = $api->delete_stat($metric_id, { ref_id => $stat_ref_id });get_stats(\%params)
The method get_stats() will return a default of up to 50 records. The parameter limit can be passed to specify the number of records to return. The parameter metric_id can also be used to scope records to a particular profile. Parameters start_date & end_date can be used to limit the date range based on the timestamp in a stat's generated_at.
+------------+---------------------------------------------------------------+
| Key | Description |
+------------+---------------------------------------------------------------+
| limit | Limit the number of metrics. Default is 50. |
| (optional) | |
| | |
| metric_id | Scope the search to a particular metric. |
| (optional) | |
| | |
| start_date | Limit the searh in date range against stats generated_at key. |
| / end_date | Valid format is YYYY-MM-DD. |
| (optional) | |
+------------+---------------------------------------------------------------+
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $metric_id = <your_metric_id>;
my $limit = <your_limit_count>;
my $stats = $api->get_stats();
my $stats_by_metric = $api->get_stats({ metric_id => $metric_id });
my $stats_by_metric_by_limit = $api->get_stats({ metric_id => $metric_id, limit => $limit });track(\%params)
It combines the functions create_stat() and create_metric() (if necessary) into a single method call. If no value is passed, the default of 1 is returned. Returns an object of type WWW::StatsMix::Stat.
+--------------+----------------------------------------------------------------------------+
| Key | Description |
+--------------+----------------------------------------------------------------------------+
| name | The name of the metric you are tracking. If a metric with that name does |
| (required) | not exist in your account, one will be created automatically. |
| | |
| value | The numeric value of the stat with a decimal precision of two. Decimal (up |
| (optional) | to 11 digits on the left side of the decimal point, two on the right). If |
| | missing default value 1 is assigned. |
| | |
| generated_at | Datetime for the stat. If not set, defaults to the current timestamp. This |
| (optional) | is the datetime to be used in the charts. Valid format is YYYY-MM-DD. |
| | |
| meta | hashref data (key,value pair) about anything associated with the stat. |
| (optional) | |
| | |
| ref_id | Optional reference id for a stat. If a stat already exists for the named |
| (optional) | metric and the given ref_id, the value (and optionally generated_at and |
| | meta) will be updated instead of created. |
| | |
| profile_id | The unique id of the profile this stat belongs to. If not set, the metric |
| (optional) | will use the first profile_id created in your account. (Developer, Basic, |
| | and Standard plans only have one profile.) |
+--------------+----------------------------------------------------------------------------+
use strict; use warnings;
use WWW::StatsMix;
my $API_KEY = "Your_API_Key";
my $api = WWW::StatsMix->new(api_key => $API_KEY);
my $name = <your_metric_name>;
my $params = { name => $metric_name };
my $stat = $api->track($params);
print "Id: ", $stat->id, "\n";AUTHOR
Mohammad S Anwar, <mohammad.anwar at yahoo.com>
REPOSITORY
https://github.com/Manwar/WWW-StatsMix
BUGS
Please report any bugs or feature requests to bug-www-statsmix at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-StatsMix. 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::StatsMixYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
LICENSE AND COPYRIGHT
Copyright (C) 2014 - 2015 Mohammad S Anwar.
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.