The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
ImgurAPI-Client-1.2.1
River stage zero No dependents
++
/ ImgurAPI::Client

NAME

ImgurAPI::Client - Imgur API client

DESCRIPTION

This is a client module for interfacing with the Imgur API.

SYNOPSIS

Instantiation

    use ImgurAPI::Client;

    my $client = ImgurAPI::Client->new({
        'client_id' => 'your_client_id',
        'access_token' => 'your_access_token'
    });

    my $upload = $client->image_upload("helloimgur.png", 'file', {title => 'title', description => 'desc'});
    my $image_info = $client->image($upload->{'data'}->{'id'};

Authorization

Imgur uses OAuth 2.0 for authentication. OAuth 2.0 has four steps: registration, authorization, making authenticated requests and getting new access tokens after the initial one expires using a refresh token and client secret.

After registering a client application with Imgur here, the user will need to manually authorize it. Generate a authorization url using the oauth2_authorize_url method and redirect the user to the generated url. The user will be prompted to authorize the application and upon authorization, the user will be redirected to the callback endpoint URL that was specified during application registration. The callback endpoint should collect the access token and refresh token and store them somewhere your code on the backend can pull the access token from and then pass it to the client. You can also visit the authorization url in the browser and manually pull the access token, refresh token and other parameters out of the redirect url and store them somewhere your code can pull them without having a collector endpoint setup. View the official imgur documentation for authorization here.

Authentication

The client can be authenticated by setting the access token and client id. Those can be set a couple of ways. The first way is to do it is by passing them to the constructor:

    my $client = ImgurAPI::Client->new({
        'client_id' => 'your_client_id',
        'client_secret' => 'your_client_secret'
        'access_token' => 'your_access_token'
    });

The second way is to use the setter methods:

    $client->set_access_token('your_access_token');
    $client->set_client_id('your_client_id');

Refreshing Access Tokens

Access tokens expire after a period of time. To get a new access token, you can use the refresh_access_token method. This method requires the refresh token, client id and client secret. You can pass these values to the method or set them using the setter methods. If you don't pass them and they're not set, the method will die. If the function is successful it will update the internal access_token and refresh_token to use for subsequent requests and then return them in a hashref.

    my %args = (
        'refresh_token' => 'your_refresh_token',
        'client_id' => 'your_client_id',
        'client_secret' => 'your_client_secret'
    );
    my $refresh_token = get_refresh_token_from_datastore();

    my $resp = $client->refresh_access_token(\%args);
    my $new_refresh_token = $resp->{'refresh_token'};

    # Store the new refresh token somewhere persistent so it can be used later when the new access token expires.

METHODS

new

    $client = ImgurAPI::Client->new(\%args);

Valid constructor arguments are:

  • access_key - Access token used to authenticate requests.

  • client_id - Client identifier used for authorization, refresh token requests and unauthenticated requests.

  • client_secret - Client secret used for acquiring a refresh token.

  • format_type - Api endpoint response format type. Options are json (default) and xml.

  • oauth_cb_state - A parameter that's appended to the OAuth2 authorization callback URL. May be useful if you want to pass along a tracking value to the callback endpoint / collector.

  • rapidapi_key - Commercial use api key provided by RapidAPI.

  • user_agent - User agent string to use for requests (default: 'ImgurAPI::Client/X.X.X')

A getter and setter method is provided for each constructor arg.

SETTER METHODS

set_access_token

    $client->set_access_token('your_access_token');

set_client_id

    $client->set_client_id('your_client_id');

set_client_secret

    $client->set_client_secret('your_client_secret');

set_format_type

    $client->set_format_type('xml');

set_oauth_cb_state

    $client->set_oauth_cb_state('your_oauth_cb_state');

set_rapidapi_key

    $client->set_rapidapi_key('rapidapi_key');

set_user_agent

    $client->set_user_agent('your_user_agent');

GETTER METHODS

access_token

    $access_tok = $client->access_token;

client_id

    $client_id = $client->client_id;

client_secret

    $client_secret = $client->client_secret;

format_type

    $format_type = $client->format_type;

oauth_cb_state

    $oauth_cb_state = $client->oauth_cb_state;

rapidapi_key

    $rapidapi_key = $client->rapidapi_key;

response

    $response = $client->response;

This method will return the last response object from the last request.

response_content

    $response_content = $client->response_content;

This method will return the last response content from the last request.

ratelimit_headers

    $ratelimit_headers = $client->ratelimit_headers;

This method will return a hashref containing the rate limit headers from the last request. The keys returned are:

user_agent

    $user_agent = $client->user_agent;

Returns the current user agent string.

  • userlimit - The total credits that can be allocated.

  • userremaining - The total credits remaining.

  • userreset - Timestamp (unix epoch) for when the credits will be reset.

  • clientlimit - Total credits that can be allocated for the application in a day.

  • clientremaining - Total credits remaining for the application in a day.

You can also get rate limit information by calling the credits method.

API REQUEST METHODS

ACCOUNT

account
    $resp = $client->account($username);

Get account information for a given username. Pass me as the username to get the account information for the authenticated user.

account_album
    $resp = $client->account_album($username, $album_id);

Get information about a specific account album. Pass me as the username to get the account information for the authenticated user.

account_album_count
    $resp = $client->account_album_count($username);

Get the total number of albums associated with an account. Pass me as the username to get the account information for the authenticated user.

account_album_delete
    $resp = $client->account_album_delete($username, $album_id);

Delete a specific album. Pass me as the username to get the account information for the authenticated user.

account_album_ids
    $resp = $client->account_album_ids($username, \%opts);

Get all the album ids associated with the account. Pass me as the username to get the account information for the authenticated user.

Valid \%opts keys are:

  • page - Page number

account_albums
    $resp = $client->account_albums($username, \%opts);

Valid \%opts keys are:

  • page - Page number

account_block_status
    $resp = $client->account_block_status($username);

Get the current block status for a user.

account_block_create
    $resp = $client->account_block_create($username);

Block a user.

account_block_delete
    $resp = $client->account_block_delete($username);

Unblock a user.

account_blocks
    $resp = $client->account_blocks;

Get the list of usernames that have been blocked.

account_comment
    $resp = $client->account_comment($username, $comment_id);

Get information about a specific account comment.

account_comment_count
    $resp = $client->account_comment_count($username);

Get the total number of comments associated with the account username.

account_comment_delete
    $resp = $client->account_comment_delete($username, $comment_id);

Delete a specific account comment.

account_comment_ids
    $resp = $client->account_comment_ids($username, \%opts);

Valid \%opts keys are:

  • page - Page number

  • sort - Sort order. Options are best, worst and newest (default)

account_comments
    $resp = $client->account_comments($username, \%opts);

Valid \%opts keys are:

  • page - Page number

  • sort - Sort order. Options are best, worst and newest (default)

account_delete
    $resp = $client->account_delete($password, \%opts);

Valid \%opts keys are:

  • reasons - Array reference of reasons for deleting the account

  • feedback - Feedback in the form of a string for Imgur.

account_favorites
    $resp = $client->account_favorites($username, \%opts);

Valid \%opts keys are:

  • page - Page number

  • sort - Sort order. Options are oldest or newest (default)

    $resp = $client->account_gallery_favorites($username, \%opts);

Valid \%opts keys are:

  • page - Page number

  • sort - Sort order. Options are oldest or newest (default)

account_image
    $resp = $client->account_image($username, $image_id);

Get information about a specific image in the account.

account_image_count
    $resp = $client->account_image_count($username);

Get the total number of images associated with the account.

account_image_delete
    $resp = $client->account_image_delete($username, $image_id);

Delete a specific image.

account_image_ids
    $resp = $client->account_image_ids($username, \%opts);

Valid \%opts keys are:

  • page - Page number

account_images
    $resp = $client->account_images($username, \%opts);

Valid \%opts keys are:

  • page - Page number

account_reply_notifications
    $resp = $client->account_reply_notifications($username, \%opts);

Valid \%opts keys are:

  • new - Boolean value. True for unviewed notifications and false for viewed notifications.

account_settings
    $resp = $client->account_settings($username);

Get account settings for a given username.

account_settings_update
    $resp = $client->account_settings_update($username, \%opts);

Update an account's settings.

Valid \%opts keys are:

  • bio - A string for the bio.

  • public_images - A boolean value to set images to public or not by default.

  • messaging_enabled - A boolean value to allow messaging or not.

  • accepted_gallery_terms - A boolean value to accept the gallery terms.

  • username - A valid username between 4 and 63 alphanumeric characters.

  • show_mature - A boolean value to show mature images in gallery list endpoints.

  • newsletter_subscribed - A boolean value, true to subscribe to the newsletter, false to unsubscribe from the newsletter.

account_submissions
    $resp = $client->account_submissions($username, \%opts);

Valid \%opts keys are:

  • page - Page number

account_tag_follow
    $resp = $client->account_tag_follow($tag);

Follow a tag.

account_tag_unfollow
    $resp = $client->account_tag_unfollow($tag);

Unfollow a tag.

account_verify_email_send
    $resp = $client->account_verify_email_send($username);

Send a verification email.

account_verify_email_status
    $resp = $client->account_verify_email_status($username);

Get the status of the verification email.

ALBUM

album
    $resp = $client->album($album_id);

Get information about a specific album.

album_create
    $resp = $client->album_create(\%opts);

  • ids - Array reference of image ids.

  • title - Title of the album.

  • description - Description of the album.

  • cover - Image id of the cover image.

album_delete
    $resp = $client->album_delete($album_id);

Delete an album.

album_favorite
    $resp = $client->album_favorite($album_id);

Favorite an album.

album_image
    $resp = $client->album_image($album_id, $image_id);

Get information about a specific image in an album.

album_images
    $resp = $client->album_images($album_id);

Get all the images in an album.

album_images_add
    $resp = $client->album_images_add($album_id, \@image_ids);

Add images to an album.

album_images_delete
    $resp = $client->album_images_delete($album_id, \@image_ids);

Delete images from an album.

album_images_set
    $resp = $client->album_images_set($album_id, \@image_ids);

Set the images for an album.

album_update
    $resp = $client->album_update($album_id, \%opts);

Update an album. Valid \%opts keys are:

  • ids - Array reference of image ids.

  • title - Title of the album.

  • description - Description of the album.

  • cover - Image id of the cover image.

COMMENT

comment
    $resp = $client->comment($comment_id);

Get information about a specific comment.

comment_create
    $resp = $client->comment_create($image_id, $comment);

Create a new comment on an image.

comment_delete
    $resp = $client->comment_delete($comment_id);

Delete a comment.

comment_replies
    $resp = $client->comment_replies($comment_id);

Get the replies for a specific comment.

comment_reply
    $resp = $client->comment_reply($image_id, $comment_id, $comment);

Create a new reply to a comment.

comment_report
    $resp = $client->comment_report($comment_id, $reason);

Report a comment with a reason. Valid reasons are:

  • 1 - Doesn't belong on Imgur

  • 2 - Spam

  • 3 - Abusive

  • 4 - Mature content not marked as mature

  • 5 - Pornography

comment_vote
    $resp = $client->comment_vote($comment_id, $vote);

Cast a vote on a comment. Valid vote values are up, down and veto.

    $resp = $client->gallery(\%opts);

Get gallery images.

Validation options are:

  • section - Section. Options are hot (default), top and user.

  • sort - Sort order. Options are viral (default), top, time, rising.

  • page - Page number.

  • window - Time window. Options are day, week, month, year, all.

  • show_viral - Show or hide viral images in the gallery. Default is 1.

  • album_previews - Show or hide album previews in the gallery. Default is 1.

    $resp = $client->gallery_album($album_id);

Get additional information about an album in the gallery.

Get information about a specific gallery album.

    $resp = $client->gallery_image($image_id);

Get additional information about an image in the gallery.

    $resp = $client->gallery_item_comment($item_id, $comment);

Create a new comment on a gallery item.

    $resp = $client->gallery_item_comment_info($item_id, $comment_id);

Get information about a specific comment on a gallery item.

    $resp = $client->gallery_item_comments($item_id);

Get all the comments on a gallery item.

    $resp = $client->gallery_item_report($item_id, \%opts);

Report an Image in the gallery

Report a gallery item. Valid \%opts keys are:

  • reason - Reason for reporting the item. Options are 1 (doesn't belong on Imgur), 2 (spam), 3 (abusive), 4 (mature content not marked as mature), 5 (pornography).

    $resp = $client->gallery_item_tags($item_id);

Get the tags for a gallery item.

    $resp = $client->gallery_item_tags_update($item_id, \@tags);

Update the tags for a gallery item.

    $resp = $client->gallery_item_vote($item_id, $vote);

Cast a vote on a gallery item. Valid vote values are up, down and veto.

    $resp = $client->gallery_item_votes($item_id);

Get the votes for a gallery item.

    $resp = $client->gallery_image_remove($image_id);

Remove an image from the gallery.

    $resp = $client->gallery_search(\%opts);

Search the gallery. Valid \%opts keys are:

  • q - Query string (ignored if advanced is set).

  • sort - Sort order. Options are time (default), viral, top, rising.

  • window - Time window. Options are all (default), day, week, month, year.

  • page - Page number.

  • adv - Advanced search options

    • q_all - Search for all of these words.

    • q_any - Search for any of these words.

    • q_exactly - Search for exactly this word or phrase.

    • q_not - Exclude results matching this.

    • q_type - Show results for any file type, or specific file types. jpg, png, gif, anigif (animated gif), album.

    • q_size_px - Return images that are greater or equal to the width/height you specify. 300x300.

    $resp = $client->gallery_share_image($image_id, $title, \%opts);

Share an image. Valid \%opts keys are:

  • topic - Topic of the shared image.

  • terms - Terms of the shared image.

  • mature - Boolean value to mark the shared image as mature.

  • tags - Array reference of tags for the shared image.

    $resp = $client->gallery_share_album($album_id, $title, \%opts);

Share an album. Valid \%opts keys are:

  • topic - Topic of the shared image.

  • terms - Terms of the shared image.

  • mature - Boolean value to mark the shared image as mature.

  • tags - Array reference of tags for the shared image.

    $resp = $client->gallery_subreddit($subreddit, \%opts);

Get images from a subreddit.

$subreddit is the name of the subreddit to get images from.

Valid \%opts keys are:

  • sort - Sort order. Options are viral (default), time, top and rising.

  • page - Page number (default is 0)

  • window - Window of time. Options are day, week (default), month, year, all. I can't wait until NY AG starts seizing trumps assets starting monday

    $resp = $client->gallery_subreddit_image('subreddit', $image_id);
    $resp = $client->gallery_tag($tag, \%opts);

Returns tag metadata, and posts tagged with the $tag provided

  • sort - Sort order. Options are viral (default), time, top and rising.

  • page - Page number (default is 0)

  • window - Window of time. Options are day, week (default), month, year, all. I can't wait until NY AG starts seizing trumps assets starting monday

    $resp = $client->gallery_tag_info($tag);

Get gallery tag information.

    $resp = $client->gallery_tags;

Gets a list of default tags

IMAGE

image
    $resp = $client->image($image_id);

Get information about a specific image.

image_upload
    $resp = $client->image_upload($src, $type, \%opts);

Upload an image or video to imgur.

$src Path, URL or Base64 encoding of the image or video file. $type Content type can be either file, url or base64.

Valid \%opts keys are:

  • title - Title of the image.

  • description - Description of the image.

image_delete
    $resp = $client->image_delete($image_id);

Delete an image.

image_favorite
    $resp = $client->image_favorite($image_id);

Favorite an image.

image_update
    $resp = $client->image_update($image_id, \%opts);

Update an image.

Valid \%opts keys are:

  • title - Title of the image.

  • description - Description of the image.

FEED

feed
    $resp = $client->feed;

Get the authenticated user's feed.

AUTHOR

Dillan Hildebrand

LICENSE

MIT