API-Instagram
view release on metacpan or search on metacpan
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The license agreements of most software companies try to keep users
at the mercy of those companies. By contrast, our General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. The
General Public License applies to the Free Software Foundation's
software and to any other program whose authors commit to using it.
You can use it for your programs, too.
When we speak of free software, we are referring to freedom, not
price. Specifically, the General Public License is designed to make
sure that you have the freedom to give away or sell copies of free
software, that you receive source code or can get it if you want it,
that you can change the software or use pieces of it in new free
programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
For example, if you distribute copies of a such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must tell them their rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
The precise terms and conditions for copying, distribution and
modification follow.
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any program or other work which
contains a notice placed by the copyright holder saying it may be
distributed under the terms of this General Public License. The
Each version is given a distinguishing version number. If the Program
specifies a version number of the license which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
the license, you may choose any version ever published by the Free Software
Foundation.
8. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
NO WARRANTY
9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
possible use to humanity, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
To do so, attach the following notices to the program. It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) 19yy <name of author>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19xx name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License. Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.
---
abstract: 'Object Oriented Interface for the Instagram REST and Search APIs'
author:
- 'Gabriel Vieira <gabriel.vieira@gmail.com>'
build_requires:
File::Spec: 0
Furl::Response: 0
IO::Handle: 0
IPC::Open3: 0
Inline::Files: 0
Test::MockObject::Extends: 0
Test::More: 0
perl: 5.010
printf "Caption: %s\n", $media->caption;
printf "Posted by %s at %s (%d likes)\n\n", $media->user->username, $media->created_time, $media->likes;
}
DESCRIPTION
This module implements an OO interface to Instagram REST API.
Authentication
Instagram API uses the OAuth2 for authentication, requering a
"client_id" and "client_secret". See
<http://instagr.am/developer/register/> for details.
Authorize
Get the AUTH URL to authenticate.
use API::Instagram;
my $instagram = API::Instagram->new({
client_id => 'xxxxxxxxxx',
client_secret => 'xxxxxxxxxx',
redirect_uri => 'http://localhost',
scope => 'basic',
response_type => 'code',
granty_type => 'authorization_code',
});
print $instagram->get_auth_url;
Authenticate
After authorization, Instagram will redirected the user to the URL in
"redirect_uri" with a code as an URL query parameter. This code is
needed to obtain an acess token.
$instagram->code( $code );
my $access_token = $instagram->get_access_token;
Request
With the access token its possible to do Instagram API requests using
the authenticated user credentials.
$instagram->access_token( $access_token );
my $me = $instagram->user;
print $me->full_name;
METHODS
new
my $instagram = API::Instagram->new({
client_id => $client_id,
client_secret => $client_secret,
redirect_uri => 'http://localhost',
scope => 'basic',
response_type => 'code',
granty_type => 'authorization_code',
no_cache => 1,
});
Returns an API::Instagram object.
Set "client_id", "client_secret" and "redirect_uri" with the ones
registered to your application. See
<http://instagram.com/developer/clients/manage/>.
"scope" is the scope of access. See
<http://instagram.com/developer/authentication/#scope>.
"response_type" and "granty_type" do no vary. See
<http://instagram.com/developer/authentication/>.
By default, API::Instagram caches created objects to avoid duplications.
You can disable this feature setting a true value to "no_chace"
parameter.
instance
my $instagram = API::Instagram->instance;
print $instagram->user->full_name;
or
client_id => $client_id,
client_secret => $client_secret,
redirect_uri => 'http://localhost',
});
Returns the singleton instance of API::Instagram.
Note: if no instance was created before, creates a new API::Instagram
object initialized with arguments provided and then returns it.
get_auth_url
my $auth_url = $instagram->get_auth_url;
print $auth_url;
Returns an Instagram authorization URL.
get_access_token
my $access_token = $instagram->get_access_token;
or
my ( $access_token, $auth_user ) = $instagram->get_access_token;
Returns the access token string if the context is looking for a scalar,
or an array containing the access token string and the authenticated
user API::Instagram::User object if looking for a list value.
media
my $media = $instagram->media( $media_id );
say $media->type;
Get information about a media object. Returns an API::Instagram::Media
object.
user
author = Gabriel Vieira <gabriel.vieira@gmail.com>
license = Perl_5
copyright_holder = Gabriel Vieira
copyright_year = 2014
[@Author::GABRIEL]
lib/API/Instagram.pm view on Meta::CPAN
use API::Instagram::Tag;
use API::Instagram::Media;
use API::Instagram::Media::Comment;
use API::Instagram::Search;
has client_id => ( is => 'ro', required => 1 );
has client_secret => ( is => 'ro', required => 1 );
has redirect_uri => ( is => 'ro', required => 1 );
has scope => ( is => 'ro', default => sub { 'basic' } );
has response_type => ( is => 'ro', default => sub { 'code' } );
has grant_type => ( is => 'ro', default => sub { 'authorization_code' } );
has code => ( is => 'rw', isa => sub { confess "Code not provided" unless $_[0] } );
has access_token => ( is => 'rw', isa => sub { confess "No access token provided" unless $_[0] } );
has no_cache => ( is => 'rw', default => sub { 0 } );
has _ua => ( is => 'ro', default => sub { Furl->new() } );
has _obj_cache => ( is => 'ro', default => sub { { User => {}, Media => {}, Location => {}, Tag => {}, 'Media::Comment' => {} } } );
has _endpoint_url => ( is => 'ro', default => sub { 'https://api.instagram.com/v1' } );
has _authorize_url => ( is => 'ro', default => sub { 'https://api.instagram.com/oauth/authorize' } );
has _access_token_url => ( is => 'ro', default => sub { 'https://api.instagram.com/oauth/access_token' } );
has _debug => ( is => 'rw', lazy => 1 );
my $instance;
sub BUILD { $instance = shift }
sub instance { $instance //= shift->new(@_) }
sub get_auth_url {
my $self = shift;
carp "User already authorized with code: " . $self->code if $self->code;
my @auth_fields = qw(client_id redirect_uri response_type scope);
for ( @auth_fields ) {
carp "ERROR: $_ required for generating authorization URL" and return unless defined $self->$_;
}
my $uri = URI->new( $self->_authorize_url );
$uri->query_form( map { $_ => $self->$_ } @auth_fields );
$uri->as_string();
}
sub get_access_token {
my $self = shift;
my @access_token_fields = qw(client_id redirect_uri grant_type client_secret code);
for ( @access_token_fields ) {
carp "ERROR: $_ required for generating access token." and return unless defined $self->$_;
lib/API/Instagram.pm view on Meta::CPAN
printf "Posted by %s at %s (%d likes)\n\n", $media->user->username, $media->created_time, $media->likes;
}
=head1 DESCRIPTION
This module implements an OO interface to Instagram REST API.
=head2 Authentication
Instagram API uses the OAuth2 for authentication, requering a C<client_id> and
C<client_secret>. See L<http://instagr.am/developer/register/> for details.
=head3 Authorize
Get the AUTH URL to authenticate.
use API::Instagram;
my $instagram = API::Instagram->new({
client_id => 'xxxxxxxxxx',
client_secret => 'xxxxxxxxxx',
redirect_uri => 'http://localhost',
scope => 'basic',
response_type => 'code',
granty_type => 'authorization_code',
});
print $instagram->get_auth_url;
=head3 Authenticate
After authorization, Instagram will redirected the user to the URL in
C<redirect_uri> with a code as an URL query parameter. This code is needed
to obtain an acess token.
$instagram->code( $code );
my $access_token = $instagram->get_access_token;
=head3 Request
With the access token its possible to do Instagram API requests using the
authenticated user credentials.
$instagram->access_token( $access_token );
my $me = $instagram->user;
print $me->full_name;
=head1 METHODS
=head2 new
my $instagram = API::Instagram->new({
client_id => $client_id,
client_secret => $client_secret,
redirect_uri => 'http://localhost',
scope => 'basic',
response_type => 'code',
granty_type => 'authorization_code',
no_cache => 1,
});
Returns an L<API::Instagram> object.
Set C<client_id>, C<client_secret> and C<redirect_uri> with the ones registered
to your application. See L<http://instagram.com/developer/clients/manage/>.
C<scope> is the scope of access. See L<http://instagram.com/developer/authentication/#scope>.
C<response_type> and C<granty_type> do no vary. See L<http://instagram.com/developer/authentication/>.
By default, L<API::Instagram> caches created objects to avoid duplications. You can disable
this feature setting a true value to C<no_chace> parameter.
=head2 instance
my $instagram = API::Instagram->instance;
print $instagram->user->full_name;
or
lib/API/Instagram.pm view on Meta::CPAN
my $instagram = API::Instagram->instance({
client_id => $client_id,
client_secret => $client_secret,
redirect_uri => 'http://localhost',
});
Returns the singleton instance of L<API::Instagram>.
Note: if no instance was created before, creates a new L<API::Instagram> object initialized with arguments provided and then returns it.
=head2 get_auth_url
my $auth_url = $instagram->get_auth_url;
print $auth_url;
Returns an Instagram authorization URL.
=head2 get_access_token
my $access_token = $instagram->get_access_token;
or
my ( $access_token, $auth_user ) = $instagram->get_access_token;
Returns the access token string if the context is looking for a scalar, or an
array containing the access token string and the authenticated user
L<API::Instagram::User> object if looking for a list value.
=head2 media
my $media = $instagram->media( $media_id );
say $media->type;
Get information about a media object. Returns an L<API::Instagram::Media> object.
=head2 user
lib/API/Instagram/Media.pm view on Meta::CPAN
my @likers = $media->get_likes( count => 5 );
Returns a list of L<API::Instagram::User> objects of users who liked the media.
Accepts C<count>.
=head2 like
$media->like;
Sets a like on the media by the authenticated user.
=head2 dislike
$media->dislike;
Removes a like on the media by the authenticated user.
=head2 comments
printf "Total Comments: %d\n", $media->comments; # Total comments when object was created
or
printf "Total Comments: %d\n", $media->comments(1); # Up to date total comments
Returns media total comments.
lib/API/Instagram/Media/Comment.pm view on Meta::CPAN
=head2 media
Returns the media where the comment was posted.
=head1 METHODS
=head2 remove
$comment->remove;
Removes the comment either on the authenticated user's media object or authored by the authenticated user.
=head1 AUTHOR
Gabriel Vieira <gabriel.vieira@gmail.com>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by Gabriel Vieira.
This is free software; you can redistribute it and/or modify it under
lib/API/Instagram/User.pm view on Meta::CPAN
my %opts = @_;
my $url = sprintf "users/%s/%s", $self->id, $opts{relationship};
my $api = $self->_api;
[ map { $api->user($_) } $api->_get_list( { %opts, url => $url } ) ]
}
sub _self_requests {
my ($self, $type, $url, %opts) = @_;
if ( $self->id ne $self->_api->user->id ){
carp "The $type is only available for the authenticated user";
return;
}
$self->_api->_get_list( { %opts, url => $url } )
}
sub BUILDARGS {
my $self = shift;
my $opts = shift;
lib/API/Instagram/User.pm view on Meta::CPAN
Returns user total followers.
=head1 METHODS
=head2 feed
my $medias = $user->feed( count => 5 );
print $_->caption . $/ for @$medias;
Returns a list of L<API::Instagram::Media> objects of the authenticated user feed.
Accepts C<count>, C<min_id> and C<max_id> as parameters.
=head2 liked_media
my $medias = $user->liked_media( count => 5 );
print $_->caption . $/ for @$medias;
Returns a list of L<API::Instagram::Media> objects of medias liked by the authenticated user.
Accepts C<count> and C<max_like_id> as parameters.
=head2 requested_by
my $requested_by = $user->get_requested_by( count => 5 );
print $_->username . $/ for @$requested_by;
Returns a list of L<API::Instagram::User> objects of users who requested this user's permission to follow.
lib/API/Instagram/User.pm view on Meta::CPAN
Returns a list of L<API::Instagram::Media> objects of user's recent medias.
Accepts C<count>, C<min_timestamp>, C<min_id>, C<max_id> and C<max_timestamp> as parameters.
=head2 relationship
my $relationship = $user->relationship;
say $relationship->{incoming_status};
Returns a C<HASH> reference contaning information about the relationship of the user with the authenticated user.
This reference contains two keys:
B<outgoing_status:> Authenticated user relationship to the user. Can be C<follows>, C<requested>, C<none>.
B<incoming_status:> A user's relationship to the authenticated user. Can be C<followed_by>, C<requested_by>, C<blocked_by_you>, C<none>.
$user->relationship('follow');
When an B<action> (as parameter) is given, it sends a request to modify the relationship to the given one.
The B<action> can be one of C<follow>/C<unfollow>/C<block>/C<unblock>/C<approve>/C<ignore>.
=head1 AUTHOR
Gabriel Vieira <gabriel.vieira@gmail.com>
t/00-instagram.t view on Meta::CPAN
my $api = API::Instagram->new({
client_id => '123',
client_secret => '456',
redirect_uri => 'http://localhost',
no_cache => 1,
_ua => $ua,
});
isa_ok( $api, 'API::Instagram');
ok $api->get_auth_url;
is $api->get_access_token, undef;
$api->code('789');
is $api->code, 789;
ok $api->get_auth_url;
is $api->user->username, undef;
is ref $api->user(123)->relationship('unfollow'), 'HASH';
my ( $access_token, $me ) = $api->get_access_token;
is $access_token, 123456789;
$api->access_token( $access_token );
is $api->access_token, 123456789;
my $api2 = API::Instagram->instance;
( run in 1.311 second using v1.01-cache-2.11-cpan-5c0b1e786e0 )