NAME

WebService::Bitly - A Perl interface to the bit.ly API

VERSION

This document describes version 0.06 of WebService::Bitly.

SYNOPSIS

use WebService::Bitly;

my $bitly = WebService::Bitly->new(
    user_name => 'shibayu',
    user_api_key => 'R_1234567890abcdefg',
);

my $shorten = $bitly->shorten('http://example.com/');
if ($shorten->is_error) {
    warn $shorten->status_code;
    warn $shorten->status_txt;
}
else {
    my $short_url = $shorten->short_url;
}

DESCRIPTION

WebService::Bitly provides an interface to the bit.ly API.

this module is similar as WWW::Shorten::Bitly, but WWW::Shorten::Bitly only supports shorten and expand API. WebService::Bitly supports all.

To get information about bit.ly API, see http://code.google.com/p/bitly-api/wiki/ApiDocumentation.

METHODS

new(%param)

Create a new WebService::Bitly object with hash parameter.

my $bitly = WebService::Bitly->new(
    user_name        => 'shibayu36',
    user_api_key     => 'R_1234567890abcdefg',
    end_user_name    => 'bitly_end_user',
    end_user_api_key => 'R_abcdefg123456789',
    domain           => 'j.mp',
);

Set up initial state by following parameters.

user_name

Required parameter. bit.ly user name.
user_api_key

Required parameter. bit.ly user api key.
end_user_name

Optional parameter. bit.ly end-user name. This parameter is used by shorten and validate method.
end_user_api_key

Optional parameter. bit.ly end-user api key. This parameter is used by shorten and validate method.
domain

Optional parameter. Specify 'j.mp', if you want to use j.mp domain in shorten method.

shorten($url)

Get shorten result from long url. you can make requests on behalf of another bit.ly user, if you specify end_user_name and end_user_api_key in new or set_end_user_info method.

my $shorten = $bitly->shorten('http://example.com');
if (!$shorten->is_error) {
    print $shorten->short_url;
    print $shorten->hash;
}

You can get data by following method of result object.

is_error

return 1, if request is failed.
short_url
is_new_hash

return 1, if specified url was shortened first time.
hash
global_hash
long_url

expand(%param)

Get long URL from given bit.ly URL or hash (or multiple).

parameters

short_urls: bit.ly short url arrayref
hashes: bit.ly hash arrayref

my $expand = $bitly->expand(
    short_urls => ['http://bit.ly/abcdef', 'http://bit.ly/fedcba'],
    hashes     => ['123456', '654321'],
);
if (!$expand->is_error) {
    for $result ($expand->results) {
        print $result->long_url if !$result->is_error;
    }
}

You can get expand results by $expand->results method. This method returns array in array context, or returns array refference in scalar context. Each result object has following method.

short_url
hash
user_hash
global_hash
long_url
is_error

return error message, if error occured by the url.

validate

Validate end-user name and end-user api key, which are set by new or set_end_user_info method.

$bitly->set_end_user_info('end_user', 'R_1234567890123456');
print $bitly->end_user_name;    # 'end_user'
print $bitly->end_user_api_key; # 'R_1234567890123456'
if ($bitly->validate->is_valid) {
    ...
}

set_end_user_info($end_user_name, $end_user_api_key)

Set end-user name and end-user api key.

clicks(%param)

Get statistics about the clicks from given bit.ly URL or hash (or multiple). You can use this in much the same way as expand method. Each result object has following method.

short_url
hash
user_hash
global_hash
user_clicks
global_clicks
is_error

referrers(%param)

Get a list of referring sites for a specified short url or hash.

parameters

Specify either short_url or hash, but not both.

short_url: bit.ly short url
hash: bit.ly hash

You can get data by following method of result object.

is_error
created_by
global_hash
short_url
user_hash
referrers

returns array or arrayref of referrer information object. array context returns array, and scalar context returns arrayref. you can use accessor method such as clicks, referrer, referrer_app and url.

my $result = $bitly->referrers(short_url => 'http://bit.ly/abcdef');
print $result->short_url;
for my $referrer ($result->refferers) {
    printf '%s : %s', $referrer->referrer, $referrer->clicks;
}

countries

Get a list of countries for a specified short url or hash. You can use this in much the same way as referrers method. you are be able to data by following method of result object.

is_error
created_by
global_hash
short_url
user_hash
countries

returns array or arrayref of arrayref of countries information object depending on context. you can use accessor method such as clicks and country.

clicks_by_minute

Get time series clicks per minute by short urls and hashes. You can use this in much the same way as expand method. Each result object has following method.

is_error
short_url
hash
user_hash
global_hash
clicks

arrayref of the number of clicks per minutes.

clicks_by_day

Get time series clicks per day for the last 30 days by short urls and hashes. You can use this in much the same way as clicks_by_minute method. Each result object has following method.

is_error
short_url
hash
user_hash
global_hash
clicks

arrayref of clicks information object. each object has accessor for clicks and day_start.

my $result_clicks = $bitly->clicks_by_day(short_url => ['http://bit.ly/abcdef'], hash => ['abcdef']);
for my $result (@{$result_clicks->results}) {
    print $result->user_hash;
    for my $clicks (@{$result->clicks}) {
        print $clicks->clicks;
        print $clicks->day_start;
    }
}

bitly_pro_domain($domain)

Check whether a given short domain is assigned for bitly.Pro.

my $result = $bitly->bitly_pro_domain('nyti.ms');
if ($result->is_pro_domain) {
    ...
}

lookup([@urls])

Get shortened url information from given urls.

my $lookup = $bitly->lookup([
    'http://code.google.com/p/bitly-api/wiki/ApiDocumentation',
    'http://betaworks.com/',
]);
if (!$lookup->is_error) {
    for my $result ($lookup->results) {
        print $result->short_url;
    }
}

Each result object has following method.

global_hash
short_url
url
is_error

return error message, if error occured by the url.

info(%param)

Get detail page information from given bit.ly URL or hash (or multiple). You can use this in much the same way as expand method. Each result object has following method.

short_url
hash
user_hash
global_hash
title

page title.
created_by

the bit.ly username that originally shortened this link.
is_error

return error message, if error occured by the url.

REPOSITORY

http://github.com/shiba-yu36/WebService-Bitly

AUTHOR

Yuki Shibazaki, <shibayu36 at gmail.com>

COPYRIGHT AND LICENSE

WebService::Bitly is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

To install WebService::Bitly, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WebService::Bitly

CPAN shell

perl -MCPAN -e shell
install WebService::Bitly

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

new(%param)

shorten($url)

expand(%param)

parameters

validate

set_end_user_info($end_user_name, $end_user_api_key)

clicks(%param)

referrers(%param)

parameters

countries

clicks_by_minute

clicks_by_day

bitly_pro_domain($domain)

lookup([@urls])

info(%param)

SEE ALSO

REPOSITORY

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions