1NAME
2
3 WWW::Shorten::Bitly - Interface to shortening URLs using
4 http://bitly.com
5
6SYNOPSIS
7
8 The traditional way, using the WWW::Shorten interface:
9
10 use strict;
11 use warnings;
12
13 use WWW::Shorten::Bitly;
14 # use WWW::Shorten 'Bitly'; # or, this way
15
16 # if you have a config file with your credentials:
17 my $short_url = makeashorterlink('http://www.foo.com/some/long/url');
18 my $long_url = makealongerlink($short_url);
19
20 # otherwise
21 my $short = makeashorterlink('http://www.foo.com/some/long/url', {
22 username => 'username',
23 password => 'password',
24 ...
25 });
26
27 Or, the Object-Oriented way:
28
29 use strict;
30 use warnings;
31 use Data::Dumper;
32 use Try::Tiny qw(try catch);
33 use WWW::Shorten::Bitly;
34
35 my $bitly = WWW::Shorten::Bitly->new(
36 username => 'username',
37 password => 'password',
38 client_id => 'adflkdgalgka',
39 client_secret => 'sldfkjasdflg',
40 );
41
42 try {
43 my $res = $bitly->shorten(longUrl => 'http://google.com/');
44 say Dumper $res;
45 # {
46 # global_hash => "900913",
47 # hash => "ze6poY",
48 # long_url => "http://google.com/",
49 # new_hash => 0,
50 # url => "http://bit.ly/ze6poY"
51 # }
52 }
53 catch {
54 die("Oh, no! $_");
55 };
56
57DESCRIPTION
58
59 A Perl interface to the Bitly.com API <https://dev.bitly.com/api.html>.
60
61 You can either use the traditional (non-OO) interface provided by
62 WWW::Shorten. Or, you can use the OO interface that provides you with
63 more functionality.
64
65FUNCTIONS
66
67 In the non-OO form, WWW::Shorten::Bitly makes the following functions
68 available.
69
70 makeashorterlink
71
72 my $short_url = makeashorterlink('https://some_long_link.com');
73 # OR
74 my $short_url = makeashorterlink('https://some_long_link.com', {
75 username => 'foo',
76 password => 'bar',
77 # any other attribute can be set as well.
78 });
79
80 The function makeashorterlink will call the http://bitly.com web site,
81 passing it your long URL and will return the shorter version.
82
83 http://bitly.com requires the use of a user id and API key to shorten
84 links.
85
86 makealongerlink
87
88 my $long_url = makealongerlink('http://bit.ly/ze6poY');
89 # OR
90 my $long_url = makealongerlink('http://bit.ly/ze6poY', {
91 username => 'foo',
92 password => 'bar',
93 # any other attribute can be set as well.
94 });
95
96 The function makealongerlink does the reverse. makealongerlink will
97 accept as an argument either the full URL or just the identifier.
98
99 If anything goes wrong, either function will die.
100
101ATTRIBUTES
102
103 In the OO form, each WWW::Shorten::Bitly instance makes the following
104 attributes available. Please note that changing any attribute will
105 unset the "access_token" in WWW::Shorten::Bitly attribute and
106 effectively log you out.
107
108 access_token
109
110 my $token = $bitly->access_token;
111 $bitly = $bitly->access_token('some_access_token'); # method chaining
112
113 Gets or sets the access_token. If the token is set, then we won't try
114 to login. You can set this ahead of time if you like, or it will be set
115 on the first method call or on "login" in WWW::Shorten::Bitly.
116
117 client_id
118
119 my $id = $bitly->client_id;
120 $bitly = $bitly->client_id('some_client_id'); # method chaining
121
122 Gets or sets the client_id. This is used in the Resource Owner
123 Credentials Grants
124 <https://dev.bitly.com/authentication.html#resource_owner_credentials>
125 login method along with the "client_secret" in WWW::Shorten::Bitly
126 attribute.
127
128 client_secret
129
130 my $secret = $bitly->client_secret;
131 $bitly = $bitly->client_secret('some_secret'); # method chaining
132
133 Gets or sets the client_secret. This is used in the Resource Owner
134 Credentials Grants
135 <https://dev.bitly.com/authentication.html#resource_owner_credentials>
136 login method along with the "client_id" in WWW::Shorten::Bitly
137 attribute.
138
139 password
140
141 my $password = $bitly->password;
142 $bitly = $bitly->password('some_secret'); # method chaining
143
144 Gets or sets the password. This is used in both the Resource Owner
145 Credentials Grants
146 <https://dev.bitly.com/authentication.html#resource_owner_credentials>
147 and the HTTP Basic Authentication
148 <https://dev.bitly.com/authentication.html#basicauth> login methods.
149
150 username
151
152 my $username = $bitly->username;
153 $bitly = $bitly->username('my_username'); # method chaining
154
155 Gets or sets the username. This is used in both the Resource Owner
156 Credentials Grants
157 <https://dev.bitly.com/authentication.html#resource_owner_credentials>
158 and the HTTP Basic Authentication
159 <https://dev.bitly.com/authentication.html#basicauth> login methods.
160
161METHODS
162
163 In the OO form, WWW::Shorten::Bitly makes the following methods
164 available.
165
166 new
167
168 my $bitly = WWW::Shorten::Bitly->new(
169 access_token => 'sometokenIalreadyreceived24123123512451',
170 client_id => 'some id here',
171 client_secret => 'some super secret thing',
172 password => 'my password',
173 username => 'my_username@foobar.com'
174 );
175
176 The constructor can take any of the attributes above as parameters. If
177 you've logged in using some other form (OAuth2, etc.) then all you need
178 to do is provide the access_token.
179
180 Any or all of the attributes can be set in your configuration file. If
181 you have a configuration file and you pass parameters to new, the
182 parameters passed in will take precedence.
183
184 bitly_pro_domain
185
186 my $bpd = $bitly->bitly_pro_domain(domain => 'http://nyti.ms');
187 say Dumper $bpd;
188
189 my $bpd2 = $bitly->bitly_pro_domain(domain => 'http://example.com');
190 say Dumper $bpd2;
191
192 Query whether a given domain is a valid Bitly pro domain. Returns a
193 hash reference with the information or dies on error.
194
195 clicks
196
197 my $clicks = $bitly->clicks(
198 link => "http://bit.ly/1RmnUT",
199 unit => 'day',
200 units => -1,
201 timezone => 'America/New_York',
202 rollup => 'false', # or 'true'
203 limit => 100, # from 1 to 1000
204 unit_reference_ts => 'now', # epoch timestamp
205 );
206 say Dumper $clicks;
207
208 Get the number of clicks
209 <https://dev.bitly.com/link_metrics.html#v3_link_clicks> on a single
210 link. Returns a hash reference of information or dies.
211
212 clicks_by_day
213
214 my $clicks = $bitly->clicks_by_day(
215 link => "http://bit.ly/1RmnUT",
216 timezone => 'America/New_York',
217 rollup => 'false', # or 'true'
218 limit => 100, # from 1 to 1000
219 unit_reference_ts => 'now', # epoch timestamp
220 );
221 say Dumper $clicks;
222
223 This call used to exist, but now is merely an alias to the "clicks" in
224 WWW::Shorten::Bitly method that hard-sets the unit to 'day' and the
225 units to 7. Returns a hash reference of information or dies.
226
227 countries
228
229 my $countries = $bitly->countries(
230 unit => 'day',
231 units => -1,
232 timezone => 'America/New_York',
233 rollup => 'false', # or 'true'
234 limit => 100, # from 1 to 1000
235 unit_reference_ts => 'now', # epoch timestamp
236 );
237 say Dumper $countries;
238
239 Returns a hash reference of aggregate metrics about the countries
240 referring click traffic
241 <https://dev.bitly.com/user_metrics.html#v3_user_countries> to all of
242 the authenticated user's links. Dies on failure.
243
244 expand
245
246 my $long = $bitly->expand(
247 shortUrl => "http://bit.ly/1RmnUT", # OR
248 hash => '1RmnUT', # or: 'custom-name'
249 );
250 say $long->{long_url};
251
252 Expand a URL using https://dev.bitly.com/links.html#v3_expand. Older
253 versions of this library required you to pass a URL parameter. That
254 parameter has been aliased for your convenience. However, we urge you
255 to stick with the parameters in the API. Returns a hash reference or
256 dies.
257
258 info
259
260 my $info = $bitly->info(
261 shortUrl => 'http://bitly.com/jmv6', # OR
262 hash => 'jmv6',
263 expand_user => 'false', # or 'true'
264 );
265 say Dumper $info;
266
267 Get info about a shorter URL using the info method call
268 <https://dev.bitly.com/links.html#v3_info>. This will return a hash
269 reference full of information about the given short URL or hash. It
270 will die on failure.
271
272 login
273
274 use Try::Tiny qw(try catch);
275
276 try {
277 $bitly->login();
278 say "yay, logged in!";
279 }
280 catch {
281 warn "Crap! Our login failed! $_";
282 };
283
284 This method will just return your object instance if your access_token
285 is already set. Otherwise, it will make use of one of the two login
286 methods depending on how much information you've supplied. On success,
287 the access_token attribute will be set and your instance will be
288 returned (method-chaining). On failure, an exception with relevant
289 information will be thrown.
290
291 If you would prefer, you can use one of the other two forms of logging
292 in:
293
294 * Resource Owner Credentials Grants
295 <https://dev.bitly.com/authentication.html#resource_owner_credentials>
296
297 * HTTP Basic Authentication
298 <https://dev.bitly.com/authentication.html#basicauth>
299
300 These two forms require at least the username and password parameters.
301
302 lookup
303
304 my $info = $bitly->lookup(url => "http://www.google.com/");
305 say $info;
306
307 Use this lookup method call
308 <https://dev.bitly.com/links.html#v3_link_lookup> to query for a short
309 URL based on a long URL. Returns a hash reference or dies.
310
311 referrers
312
313 my $refs = $bitly->referrers(
314 link => "http://bit.ly/1RmnUT",
315 unit => 'day',
316 units => -1,
317 timezone => 'America/New_York',
318 rollup => 'false', # or 'true'
319 limit => 100, # from 1 to 1000
320 unit_reference_ts => 'now', # epoch timestamp
321 );
322 say Dumper $refs;
323
324 Use the referrers API call
325 <https://dev.bitly.com/link_metrics.html#v3_link_referrers> to get
326 metrics about the pages referring click traffic to a single short URL.
327 Returns a hash reference or dies.
328
329 shorten
330
331 my $short = $bitly->shorten(
332 longUrl => "http://www.example.com", # required.
333 domain => 'bit.ly', # or: 'j.mp' or 'bitly.com'
334 );
335 say $short->{url};
336
337 Shorten a URL using https://dev.bitly.com/links.html#v3_shorten. Older
338 versions of this library required you to pass a URL parameter. That
339 parameter has been aliased for your convenience. However, we urge you
340 to stick with the parameters in the API. Returns a hash reference or
341 dies.
342
343CONFIG FILES
344
345 $HOME/.bitly or _bitly on Windows Systems.
346
347 username=username
348 password=some_password_here
349 client_id=foobarbaz
350 client_secret=asdlfkjadslkgj34t34talkgjag
351
352 Set any or all "ATTRIBUTES" in WWW::Shorten::Bitly in your config file
353 in your home directory. Each key=val setting should be on its own line.
354 If any parameters are then passed to the "new" in WWW::Shorten::Bitly
355 constructor, those parameter values will take precedence over these.
356
357AUTHOR
358
359 Pankaj Jain <pjain@cpan.org>
360
361CONTRIBUTORS
362
363 * Chase Whitener <capoeirab@cpan.org>
364
365 * Joerg Meltzer <joerg@joergmeltzer.de>
366
367 * Mizar <mizar.jp@gmail.com>
368
369 * Peter Edwards <pedwards@cpan.org>
370
371 * Thai Thanh Nguyen <thai@thaiandhien.com>
372
373COPYRIGHT & LICENSE
374
375 Copyright (c) 2009 Pankaj Jain, All Rights Reserved
376 http://blog.pjain.me.
377
378 Copyright (c) 2009 Teknatus Solutions LLC, All Rights Reserved
379 http://teknatus.com.
380
381 This program is free software; you can redistribute it and/or modify it
382 under the same terms as Perl itself.
383
384