Package 'imguR' reference manual

Title:	'Imgur.com' API Client Package
Description:	A complete API client for the image hosting service 'Imgur.com', including the an 'imgur' graphics device, enabling the easy upload and sharing of plots.
Authors:	Thomas J. Leeper [aut, cre] , Aaron Statham [ctb], Yihui Xie [ctb]
Maintainer:	Thomas J. Leeper <[email protected]>
License:	GPL-3
Version:	1.0.4
Built:	2024-11-01 02:52:41 UTC
Source:	https://github.com/cloudyr/imgur

Imgur API Client Package for R

Description

This package enables intuitive uploading of plots created in R to the free image hosting service [Imgur](http://www.imgur.com) simply, quickly, and intuitively via the [Imgur v3 API](http://api.imgur.com). The package is a complete client library for the Imgur API, meaning that one can also delete, favorite, and comment on images, as well as organize them in albums and galleries. By default, all images are loaded to Imgur anonymously. Optionally, using an OAuth2.0 login, users can also gain fully access to their own Imgur user account.

Author(s)

Thomas J. Leeper and Aaron Statham

Maintainer: Thomas J. Leeper <[email protected]>

References

Imgur

API Documentation

Retrieve user account details

Description

Retrieve details of a user's account

Usage

account(account = 'me', ...)

account_verified(...)

send_verification(...)
account(account = 'me', ...)

account_verified(...)

send_verification(...)

Arguments

`account`	A username, by default the current user (if `token` is supplied). `account_verified` and `send_verification` require a `token` argument.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

account returns basic details of a user account. account_verified indicates whether one's user account has been email-verified. send_verification sends a verification email to the user's email account.

Value

An object of class “imgur_account”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
# get account details for a user account
account('thosjleeper')

# check account verification
tkn <- imgur_login()
if(!account_verified(token = tkn))
    send_verification(token = tkn)
account(token = tkn)

## End(Not run)
## Not run: 
# get account details for a user account
account('thosjleeper')

# check account verification
tkn <- imgur_login()
if(!account_verified(token = tkn))
    send_verification(token = tkn)
account(token = tkn)

## End(Not run)

Retrieve user albums

Description

Retrieve details of a user's albums

Usage

account_albums(account = 'me', ids = TRUE, ...)

account_album_count(account = 'me', ...)
account_albums(account = 'me', ids = TRUE, ...)

account_album_count(account = 'me', ...)

Arguments

`account`	A username, by default the current user (if `token` is supplied).
`ids`	A logical indicating whether to only return album IDs.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

account_albums retrieves details of a user's albums. By default (and if a token argument is supplied), the current user's albums are returned. Specifying another username is also possible with or without a token. account_album_count returns just the number of albums, which is useful for handling pagination of the results.

Value

For account_albums, a list of objects of class “imgur_albums”. For account_album_count, a number.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
account_albums('thosjleeper')

## End(Not run)
## Not run: 
account_albums('thosjleeper')

## End(Not run)

Retrieve user albums

Description

Retrieve details of a user's albums

Usage

account_comments(account = 'me', ids = FALSE, ...)

account_comment_count(account = 'me', ...)
account_comments(account = 'me', ids = FALSE, ...)

account_comment_count(account = 'me', ...)

Arguments

`account`	A username, by default the current user (if `token` is supplied).
`ids`	A logical indicating whether to only return album IDs.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

account_comments retrieves details of a user's comments. By default (and if a token argument is supplied), the current user's comments are returned. Specifying another username is also possible with or without a token. account_comment_count returns just the number of comments, which is useful for handling pagination of the results.

Value

For account_comments, an object of class “imgur_comment”. For account_comment_count, a number.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
account_comments('thosjleeper')

## End(Not run)
## Not run: 
account_comments('thosjleeper')

## End(Not run)

Retrieve user favorites

Description

Retrieve details of a user's favorite images

Usage

account_favorites(account = 'me', gallery = FALSE, ...)
account_favorites(account = 'me', gallery = FALSE, ...)

Arguments

`account`	A username, by default the current user (if `token` is supplied).
`gallery`	A logical indicating whether to only return gallery favorites.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

account_favorites retrieves details of a user's favoriates. By default (and if a token argument is supplied), the current user's favorites are returned. Specifying another username is also possible with or without a token.

Value

For account_favorites, an object of class “imgur_gallery_image” or “imgur_gallery_album”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
account_favorites('thosjleeper')

## End(Not run)
## Not run: 
account_favorites('thosjleeper')

## End(Not run)

User gallery profile

Description

Retrieve details of a user's gallery profile

Usage

account_gallery(account = 'me', ...)
account_gallery(account = 'me', ...)

Arguments

`account`	A username, by default the current user (if `token` is supplied). `account_verified` and `send_verification` require a `token` argument.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

account_gallery returns basic details of a user's gallery profile, including counts of comments, likes, submissions, and trophies.

Value

An object of class “imgur_gallery_profile”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
account_gallery(token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
account_gallery(token = tkn)

## End(Not run)

Retrieve user images

Description

Retrieve details of a user's images

Usage

account_images(account = 'me', page = NULL, ids = TRUE, ...)

account_image_count(account = 'me', ...)
account_images(account = 'me', page = NULL, ids = TRUE, ...)

account_image_count(account = 'me', ...)

Arguments

`account`	A username, by default the current user (if `token` is supplied).
`page`	Optionally, a page of results to return.
`ids`	A logical indicating whether to only return image IDs.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

account_images retrieves details of a user's images. By default (and if a token argument is supplied), the current user's images are returned. Specifying another username is also possible with or without a token. account_image_count returns just the number of images, which is useful for handling pagination of the results.

Value

For account_images, an object of class “imgur_image”. For account_image_count, a number.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
account_images('thosjleeper')

## End(Not run)
## Not run: 
account_images('thosjleeper')

## End(Not run)

Retrieve and modify account settings

Description

Retrieve and modify account settings

Usage

account_settings(bio = NULL,
                 public_images = NULL,
                 messaging_enabled = NULL,
                 album_privacy = NULL,
                 accepted_gallery_terms = NULL,
                 ...)
account_settings(bio = NULL,
                 public_images = NULL,
                 messaging_enabled = NULL,
                 album_privacy = NULL,
                 accepted_gallery_terms = NULL,
                 ...)

Arguments

`bio`	The biography of user, which is displayed in the gallery profile page.
`public_images`	A logical indicating whether images public by default.
`messaging_enabled`	A logical indicating whether private messages are allowed.
`album_privacy`	The default privacy for albums. One of “public”, “hidden”, or “secret”.
`accepted_gallery_terms`	A logical indicating whether the user agrees to the Imgur gallery terms.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

If none of the named arguments (other than token) are specified, this retrieves settings of the account. If any of the named arguments are specified, those parameters are modified.

Value

If not modifying settings, an object of “imgur_account_settings”, otherwise an object of “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()

# retrieve settings
account_settings(token = tkn)

# set albums to default to public
account_settings(album_privacy = 'public', token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()

# retrieve settings
account_settings(token = tkn)

# set albums to default to public
account_settings(album_privacy = 'public', token = tkn)

## End(Not run)

Manage album images

Description

Add images to or remove images from an album

Usage

add_album_images(album, id, ...)

remove_album_images(album, id, ...)

set_album_images(album, id, ...)
add_album_images(album, id, ...)

remove_album_images(album, id, ...)

set_album_images(album, id, ...)

Arguments

`album`	An album ID or object of class “imgur_album”.
`id`	A vector of one or more image IDs to add to the album or a list of objects of class “imgur_image”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

add_album_images adds the specified images to the album.

set_album_images removes all current images from the album and adds the specified images to the album.

remove_album_images removes the specified images from the album.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Add gallery images

Description

Add images to the gallery

Usage

add_gallery_images(album = NULL, id = NULL, title = NULL, ...)
add_gallery_images(album = NULL, id = NULL, title = NULL, ...)

Arguments

`album`	An album ID or object of class “imgur_album” to add to the gallery.
`id`	An image ID or an object of class “imgur_image” to add to the gallery.
`title`	A title for the image
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

This function adds the specified image or album to the gallery. title is required by the API. If NULL, the title is drawn from a call to get_album or get_image.

Value

An object of class “imgur_gallery_image” or “imgur_gallery_album”.

Author(s)

Thomas J. Leeper

Imgur API Authentication

Description

Description of Imgur API authentication options

Details

All calls to the Imgur.com API must be authenticated. imguR provides two authentication methods: anonymous API key authentication (the default) and OAuth2.0 authentication.

By default, all calls are made anonymously. Most operations can be performed in this way. The package provides an API key for performing operations in this way. This default key can be overridden by passing key argument through any function. This may be useful if you intend to make a large number of anonymous requests using your own registered application.

Alternatively, calls can be made with a user-specific OAuth2.0 token. This token is generated using imgur_login in an interactive session. The token allows calls to be made to a specific Imgur.com user account, which eases making subsequent changes to uploaded images (e.g., updating their metadata, adding images to an album, or deleting images). The token can then be passed using the token argument to any function.

Note: if both key and token arguments are supplied to a function, the token argument always takes precedence.

References

https://api.imgur.com/oauth2

Examples

## Not run: 
# OAuth2.0-authenticated use

# interactive OAuth login
tkn <- imgur_login()

# upload a simple graph
i <- imgur(token = tkn)
hist(rnorm(100))
u <- imgur_off(i)

# pass the `imgur_image` object to `update_image`:
update_image(u, title = 'My graph', description = 'A simple graph', token = tkn)

# or, pass just the image id:
update_image(u$id, title = 'My graph', description = 'A simple graph', token = tkn)

# periodically refresh token
tkn$refresh()

## End(Not run)

## Not run: 
# anonymous use

# upload a simple graph
i <- imgur()
hist(rnorm(100))
u <- imgur_off(i)

# pass just the image deletehash:
update_image(u$deletehash, title = 'My graph', description = 'A simple graph')

## End(Not run)

## Not run: 
# OAuth2.0-authenticated use

# interactive OAuth login
tkn <- imgur_login()

# upload a simple graph
i <- imgur(token = tkn)
hist(rnorm(100))
u <- imgur_off(i)

# pass the `imgur_image` object to `update_image`:
update_image(u, title = 'My graph', description = 'A simple graph', token = tkn)

# or, pass just the image id:
update_image(u$id, title = 'My graph', description = 'A simple graph', token = tkn)

# periodically refresh token
tkn$refresh()

## End(Not run)

## Not run: 
# anonymous use

# upload a simple graph
i <- imgur()
hist(rnorm(100))
u <- imgur_off(i)

# pass just the image deletehash:
update_image(u$deletehash, title = 'My graph', description = 'A simple graph')

## End(Not run)

Block a user

Description

Block a user from sending messages

Usage

block_sender(username, ...)
block_sender(username, ...)

Arguments

`username`	A character string containing an Imgur username.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Block an Imgur user from sending messages.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
block_sender("thosjleeper", token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
block_sender("thosjleeper", token = tkn)

## End(Not run)

Create album

Description

Create an album

Usage

create_album(id = NULL,
             title = NULL, description = NULL,
             privacy = NULL, layout = NULL, cover_id = NULL, ...)
create_album(id = NULL,
             title = NULL, description = NULL,
             privacy = NULL, layout = NULL, cover_id = NULL, ...)

Arguments

`id`	A vector of one or more image IDs to add to the album or a list of objects of class “imgur_image”.
`title`	Optionally, an album title.
`description`	Optionally, an album description.
`privacy`	The privacy for the album. One of “public”, “hidden”, or “secret”.
`layout`	The layout for the album. One of “blog”, “grid”, “horizontal”, or “vertical”.)
`cover_id`	An image ID or an object of class “imgur_image”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Creates an Imgur album with the specified images and metadata. All options are are optional. Images can only be added to anonymous albums with create_album, not after the fact. Albums created with an OAuth2.0 authentication token can be modified in any way.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
i <- imgur()
hist(rnorm(20))
img <- imgur_off(i)
create_album(id = img,
             title = 'My first Imgur album',
             description = 'A simple album',
             privacy = 'hidden',
             layout = 'grid',
             cover_id = img)

## End(Not run)
## Not run: 
i <- imgur()
hist(rnorm(20))
img <- imgur_off(i)
create_album(id = img,
             title = 'My first Imgur album',
             description = 'A simple album',
             privacy = 'hidden',
             layout = 'grid',
             cover_id = img)

## End(Not run)

Create a comments

Description

Create a comment on an image

Usage

create_comment(id, comment, parent = NULL, ...)
create_comment(id, comment, parent = NULL, ...)

Arguments

`id`	An image ID or an object of class “imgur_image”.
`comment`	A character string containing the comment.
`parent`	An optional comment ID to reply to.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Value

For account_favorites, an object of class “imgur_gallery_image” or “imgur_gallery_album”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()

# comment on an image
cmt <- create_comment("vSXfU46", "This is a test comment", token = tkn)

# create a reply comment
create_comment("vSXfU46", "This is a test comment", parent = cmt, token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()

# comment on an image
cmt <- create_comment("vSXfU46", "This is a test comment", token = tkn)

# create a reply comment
create_comment("vSXfU46", "This is a test comment", parent = cmt, token = tkn)

## End(Not run)

Create a comments

Description

Create a comment on an image

Usage

create_message(recipient, body, ...)
create_message(recipient, body, ...)

Arguments

`recipient`	A character string containing the recipient's Imgur username.
`body`	A character string containing the message.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Send a message to another Imgur user.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
create_message("thosjleeper", "This is a test comment from imguR", token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
create_message("thosjleeper", "This is a test comment from imguR", token = tkn)

## End(Not run)

Delete album

Description

Delete an album

Usage

delete_album(album, ...)
delete_album(album, ...)

Arguments

`album`	An album ID or object of class “imgur_image”. If no `token` is supplied, `id` must be a deletehash from the original `upload_image` response.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Deletes an album.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
# using an OAuth token
tkn <- imgur_login()
a <- account_albums(token = tkn)
delete_album(a[[1]], token = tkn)

## End(Not run)
## Not run: 
# using an OAuth token
tkn <- imgur_login()
a <- account_albums(token = tkn)
delete_album(a[[1]], token = tkn)

## End(Not run)

Delete a comment

Description

Delete a comment from an image

Usage

delete_comment(comment, ...)
delete_comment(comment, ...)

Arguments

`comment`	A comment ID, perhaps returned by `create_comment`.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Delete a comment.

Value

An object of class “imgur_basic”

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
cmt <- create_comment("vSXfU46", comment = 'This is a test comment.')
delete_comment(cmt, token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
cmt <- create_comment("vSXfU46", comment = 'This is a test comment.')
delete_comment(cmt, token = tkn)

## End(Not run)

Delete conversation

Description

Delete a conversation

Usage

delete_conversation(id, ...)
delete_conversation(id, ...)

Arguments

`id`	A conversation ID, possibly returned by `get_conversations`.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Deletes a conversation

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Delete image

Description

Delete an image

Usage

delete_image(id, ...)
delete_image(id, ...)

Arguments

`id`	An image ID or object of class “imgur_image”. If no `token` is supplied, `id` must be a deletehash from the original `upload_image` response.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Deletes an image.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
# using a deletehash, anonymously
u <- upload_image('file.png')
delete_image(u$deletehash)

# using an OAuth token
tkn <- imgur_login()
u <- upload_image('file.png', token = tkn)
delete_image(u, token = tkn)

## End(Not run)
## Not run: 
# using a deletehash, anonymously
u <- upload_image('file.png')
delete_image(u$deletehash)

# using an OAuth token
tkn <- imgur_login()
u <- upload_image('file.png', token = tkn)
delete_image(u, token = tkn)

## End(Not run)

Favorite album

Description

Favorite an album

Usage

favorite_album(album, ...)
favorite_album(album, ...)

Arguments

`album`	An album ID or object of class “imgur_album”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Favorites an album.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
favorite_album("cVsXX", token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
favorite_album("cVsXX", token = tkn)

## End(Not run)

Favorite image

Description

Favorite an image

Usage

favorite_image(id, ...)
favorite_image(id, ...)

Arguments

`id`	An image ID or object of class “imgur_image”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Favorites an image.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
favorite_image("DgqMUeq", token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
favorite_image("DgqMUeq", token = tkn)

## End(Not run)

Get album

Description

Get album details and metadata, or images.

Usage

get_album(album, ...)

get_album_images(album, ...)
get_album(album, ...)

get_album_images(album, ...)

Arguments

`album`	An album ID or object of class “imgur_album”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Get album details and metadata, including images contained in the album.

Value

An object of class “imgur_album”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
get_album("cVsXX")

get_album_images("cVsXX")

## End(Not run)
## Not run: 
get_album("cVsXX")

get_album_images("cVsXX")

## End(Not run)

Get a comment

Description

Get a comment (and, optionally, its replies).

Usage

get_comment(comment, replies = FALSE, ...)
get_comment(comment, replies = FALSE, ...)

Arguments

`comment`	A comment ID, perhaps returned by `create_comment`.
`replies`	A logical indicating whether to return replies to the comment, in addition to the comment itself.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Retrivies a comment and, optionally, any replies to that comment.

Value

An object of class “imgur_comment”

Author(s)

Thomas J. Leeper

Get conversations

Description

Get a specific conversation or all conversations

Usage

get_conversations(id = NULL, ...)
get_conversations(id = NULL, ...)

Arguments

`id`	A conversation ID. If `NULL`, all conversations are returned.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Retrieves a named conversation, possibly returned by get_conversations, or all conversations.

Value

An object of class “imgur_message”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
get_conversations(token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
get_conversations(token = tkn)

## End(Not run)

Get gallery

Description

Get gallery details and metadata

Usage

get_gallery(section = 'hot', sort = 'viral', page = 0, 
            window = 'day', showViral = TRUE, ...)
get_gallery(section = 'hot', sort = 'viral', page = 0, 
            window = 'day', showViral = TRUE, ...)

Arguments

`section`	One of “hot” (the default), “top”, or “user”.
`sort`	One of “viral” (the default) or “time”.
`page`	A page number of results between 0 and 50.
`window`	If `section == 'top'`, one of “day” (the default), “week”, “month”, “year”, or “all”.
`showViral`	If `section == 'user'`, a logical indicating whether show viral images.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Get gallery image details and metadata.

Value

An object of class “imgur_image”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
get_gallery()

get_gallery('top', window = 'week')

## End(Not run)
## Not run: 
get_gallery()

get_gallery('top', window = 'week')

## End(Not run)

Get gallery album

Description

Get album details and metadata for an album in the gallery.

Usage

get_gallery_album(album, ...)
get_gallery_album(album, ...)

Arguments

`album`	An album ID or object of class “imgur_album” or “imgur_gallery_album”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Get album details and metadata, for an album in the gallery. This is basically the same as “get_album”.

Value

An object of class “imgur_gallery_album”.

Author(s)

Thomas J. Leeper

Get gallery image

Description

Get gallery image details and metadata

Usage

get_gallery_image(id, ...)
get_gallery_image(id, ...)

Arguments

`id`	An image ID or object of class “imgur_image” or “imgur_gallery_image”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Get gallery image details and metadata. This is basically the same as get_image.

Value

An object of class “imgur_image”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
s <- search_gallery(query = 'meme')
get_gallery_image(s[[1]])

## End(Not run)
## Not run: 
s <- search_gallery(query = 'meme')
get_gallery_image(s[[1]])

## End(Not run)

Get image

Description

Get image details and metadata

Usage

get_image(id, ...)
get_image(id, ...)

Arguments

`id`	An image ID or object of class “imgur_image”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Get image details and metadata.

Value

An object of class “imgur_image”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
get_image("vSXfU46")

## End(Not run)
## Not run: 
get_image("vSXfU46")

## End(Not run)

Get notifications

Description

Get a specific notification or all notifications

Usage

get_notifications(id = NULL, only_new = FALSE, ...)
get_notifications(id = NULL, only_new = FALSE, ...)

Arguments

`id`	A conversation ID. If `NULL`, all notifications (or all new notifications, depending on `only_new`) are returned.
`only_new`	A logical indicating whether only new notifications should be returned. Default is `FALSE`.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Retrieves a named notification, possibly returned by get_notifications, or all (new) notifications.

Value

An object of class “imgur_notification”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
get_notifications(only_new = TRUE, token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
get_notifications(only_new = TRUE, token = tkn)

## End(Not run)

Get random images

Description

Get random images from the public gallery

Usage

get_random_images(page = 0, ...)
get_random_images(page = 0, ...)

Arguments

`page`	A page number of results between 0 and 50.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Get random images from the public gallery.

Value

An object of class “imgur_gallery_album”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
get_random_images()

## End(Not run)
## Not run: 
get_random_images()

## End(Not run)

Get gallery

Description

Get gallery details and metadata

Usage

get_reddit_gallery(subreddit, sort = 'time', page = 0, window = 'day', ...)
get_reddit_gallery(subreddit, sort = 'time', page = 0, window = 'day', ...)

Arguments

`subreddit`	A character string containing the name of a sub-reddit.
`sort`	One of “time” (the default) or “top”.
`page`	A page number of results between 0 and 50.
`window`	If `sort == 'top'`, one of “day” (the default), “week”, “month”, “year”, or “all”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Get gallery image details and metadata for a sub-reddit gallery.

Value

An object of class “imgur_image”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
get_reddit_gallery('dataisbeautiful')

## End(Not run)
## Not run: 
get_reddit_gallery('dataisbeautiful')

## End(Not run)

Get reddit image

Description

Get sub-reddit gallery image details and metadata

Usage

get_reddit_image(subreddit, id, ...)
get_reddit_image(subreddit, id, ...)

Arguments

`subreddit`	A character string containing the name of a sub-reddit.
`id`	An image ID or object of class “imgur_image” or “imgur_gallery_image”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Get sub-reddit gallery image details and metadata. This is basically the same as get_gallery_image or get_image.

Value

An object of class “imgur_gallery_image”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
g <- get_reddit_gallery('dataisbeautiful')
get_reddit_image('dataisbeautiful', g[[1]])
get_image(g[[1]])

## End(Not run)
## Not run: 
g <- get_reddit_gallery('dataisbeautiful')
get_reddit_image('dataisbeautiful', g[[1]])
get_image(g[[1]])

## End(Not run)

Get replies

Description

Get replies

Usage

get_replies(only_new = FALSE, ...)
get_replies(only_new = FALSE, ...)

Arguments

`only_new`	A logical indicating whether only new notifications should be returned. Default is `FALSE`.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Retrieves replies.

Value

An object of class “imgur_notification”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
get_replies(only_new = TRUE, token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
get_replies(only_new = TRUE, token = tkn)

## End(Not run)

Workhorse HTTP functions

Description

Basic workhorse HTTP method functions for executing Imgur.com API calls

Usage

imgurGET(endpoint, 
         base_url = "https://api.imgur.com/3/", 
         key = "1babd0decbb90f2",
         token = NULL,
         ...)
imgurGET(endpoint, 
         base_url = "https://api.imgur.com/3/", 
         key = "1babd0decbb90f2",
         token = NULL,
         ...)

Arguments

`endpoint`	A named API endpoint.
`base_url`	The base URL for the API (by default the v3 API URL).
`key`	An API key (by default, the imguR package API key). The API key for version of imguR < 1.0.0 was “4feb29d00face5bc1b9dae536e15c373”. Either `key` or `token` must be specified.
`token`	Optionally, an OAuth2.0 token (returned by `imgur_login`. Either `key` or `token` must be specified.
`...`	Other arguments passed to analogous HTTP method functions from httr.

Details

These are the basic workhorse functions for the package, which users should not need to access directly (except perhaps for debugging).

Value

Generally, a list. For imgurDELETE, an empty character string.

Author(s)

Thomas J. Leeper

Initiate/close an Imgur-enabled Graphics Device

Description

Open a specified graphics device function an configure it to upload to Imgur and then close it using imgur_off.

Usage

imgur(device = png, file = NULL, title = NULL, description = NULL, 
      album = NULL, name = NULL, key = NULL, token = NULL, ...)

imgur_off(obj, ...)
imgur(device = png, file = NULL, title = NULL, description = NULL, 
      album = NULL, name = NULL, key = NULL, token = NULL, ...)

imgur_off(obj, ...)

Arguments

`device`	A graphics device function. Default is `png`.
`file`	Name of the file to be uploaded to imgur.com
`title`	Optionally, an image title.
`description`	Optionally, an image description.
`album`	Optionally, an Imgur album ID.
`name`	Optionally, a file name, otherwise the `file` filename is used.
`key`	An API key. If `NULL`, the default imguR package API key is used.
`token`	Optionally, an OAuth2.0 token (returned by `imgur_login`. If `NULL`, the API key used instead.
`obj`	An object of class “imgur_device”.
`...`	For `imgur`, other arguments passed to the specified device function. For `imgur_off`, additional arguments passed to `upload_image`.

Details

imgur is a wrapper for a local graphics device (by default, the png function. A temporary file is created by the graphics device. After plotting, a call to imgur_off uploads the file to imgur (using upload_image) and a URL of the files location is returned.

Value

For imgur, an object of class “imgur_device” to be passed to imgur_off. For imgur_off, the response from upload_image.

Author(s)

Thomas J. Leeper, based on code by Aaron Statham.

Examples

## Not run: 
i <- imgur('png')
hist(rnorm(20))
imgur_off(i)

## End(Not run)
## Not run: 
i <- imgur('png')
hist(rnorm(20))
imgur_off(i)

## End(Not run)

Login to Imgur

Description

Complete an interactive login to Imgur to generate an OAuth2.0 token

Usage

imgur_login(client_id = "1babd0decbb90f2",
            secret = "06eed15f8e3662c20d7ff95a62853266400aae5a",
            cache = TRUE)
imgur_login(client_id = "1babd0decbb90f2",
            secret = "06eed15f8e3662c20d7ff95a62853266400aae5a",
            cache = TRUE)

Arguments

`client_id`	A graphics device function. Default is `png`.
`secret`	Name of the file to be uploaded to imgur.com
`cache`	A logical indicating whether to cache the OAuth2.0 token for use later on. If `TRUE`, OAuth2.0 token is automatically cached in a file called “.httr-oauth” in the working directory.

Details

Most operations in the package can be performed anonymously using the default package API key. In order to perform most account-specific operations it is necessary to use OAuth authentication, which can only be performed interactively via a web browser. imgur_login returns an OAuth2.0 reference class object that can be passed as the token argument to all other functions in the package.

The OAuth token is moderately long lived; the response object contains a timestamp indicating its expiration time. The token can be subsequently refreshed using the refresh() method.

If cache = TRUE, the OAuth2.0 token is automatically cached in a file called “.httr-oauth” in the working directory. This token will then be loaded automatically the next time imgur_login is called (even in a new R session). To override an existing cache, set cache = FALSE.

Value

An OAuth2.0 reference class object, returned by oauth2.0_token.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
# login interactively
tkn <- imgur_login()
# use token in the `imgur` device
i <- imgur('png', token = tkn)
hist(rnorm(20))
imgur_off(i)

# reload previous token
rm(tkn)
# OAuth token is automatically stored by 
# `imgur_login` if `cache = TRUE` (the default)
# It is reloaded by calling `imgur_login`
tkn <- imgur_login()
token$refresh() # refresh token

## End(Not run)
## Not run: 
# login interactively
tkn <- imgur_login()
# use token in the `imgur` device
i <- imgur('png', token = tkn)
hist(rnorm(20))
imgur_off(i)

# reload previous token
rm(tkn)
# OAuth token is automatically stored by 
# `imgur_login` if `cache = TRUE` (the default)
# It is reloaded by calling `imgur_login`
tkn <- imgur_login()
token$refresh() # refresh token

## End(Not run)

Mark notification read

Description

Mark a notification as read

Usage

mark_notification(id, ...)
mark_notification(id, ...)

Arguments

`id`	A notification ID.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Marks a named notification as read so that it does not show in future get_notifications results.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Memes

Description

View memes and meme templates

Usage

default_memes(...)

get_memes_gallery(sort = 'viral', page = 0, window = NULL, ...)

get_meme(id, ...)
default_memes(...)

get_memes_gallery(sort = 'viral', page = 0, window = NULL, ...)

get_meme(id, ...)

Arguments

`sort`	One of “viral” (the default), “time”, or “top”.
`page`	A page number of results between 0 and 50.
`window`	One of “day”, “week”, “month”, “year”, or “all”.
`id`	An image ID, perhaps returned by `get_memes_gallery`.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

default_memes returns a list of default memes available on Imgur. get_memes_gallery returns a list of trending memes. get_meme returns a specific meme image.

Value

A list of objects of class “imgur_image” or “imgur_gallery_image”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
default_memes()
get_memes_gallery('viral', page = 1)

## End(Not run)
## Not run: 
default_memes()
get_memes_gallery('viral', page = 1)

## End(Not run)

Plot Imgur image

Description

Plot an “imgur_image” object

Usage

## S3 method for class 'imgur_image'
plot(x, ...)
## S3 method for class 'imgur_gallery_image'
plot(x, ...)
## S3 method for class 'imgur_image'
plot(x, ...)
## S3 method for class 'imgur_gallery_image'
plot(x, ...)

Arguments

`x`	An object of class “imgur_image” or “imgur_gallery_image”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Plot an object of class “imgur_image” or “imgur_gallery_image” in an R graphics window.

Value

Invisibly, an object of class “imgur_image” or “imgur_gallery_image”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
plot(get_image("vSXfU46"))

## End(Not run)
## Not run: 
plot(get_image("vSXfU46"))

## End(Not run)

API rate limits

Description

Check user- and package-level rate limits

Usage

rate_limit(...)
rate_limit(...)

Arguments

...

Other arguments passed to HTTP request functions, for example: token (an OAuth2.0 token) or key (an API key, used by default).

Details

This function returns a list detailing user- and package-level API rate limits. All calls to the API deduct one unit from rate limits, except for upload_image, which deducts 10. Rate limits are lower for anonymous requests than for authenticated requests. Limits exist at the user level and at the package level. The user-level rate limit are automatically reset periodically. The response object documents when that limit will be reset.

Rate limits are automatically checked during each request. Options can be set for low remaining usage warnings. By default (when the package is loaded) those options are: options(imgur_user_rate_warning = 20) and options(imgur_client_rate_warning = 100).

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
# rate limit for anonymous requests
rate_limit()

# rate limit for authenticated requests
tkn <- imgur_login()
rate_limit(token = tkn)

## End(Not run)
## Not run: 
# rate limit for anonymous requests
rate_limit()

# rate limit for authenticated requests
tkn <- imgur_login()
rate_limit(token = tkn)

## End(Not run)

Remove gallery image

Description

Remove images from the gallery

Usage

remove_gallery_image(id, ...)
remove_gallery_image(id, ...)

Arguments

`id`	An image ID or an object of class “imgur_image” to add to the gallery.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

This function removes the specified image from the gallery.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Report a comment

Description

Report a comment as inappropriate.

Usage

report_comment(comment, ...)
report_comment(comment, ...)

Arguments

`comment`	A comment ID, perhaps returned by `create_comment` or `get_comment`.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Reports a comment as inappropriate.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Report a gallery image

Description

Report a gallery image as inappropriate.

Usage

report_gallery_image(id, ...)
report_gallery_image(id, ...)

Arguments

`id`	An image ID.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Reports a gallery image as inappropriate.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Report a user

Description

Report a user for inappropriate behavior

Usage

report_sender(username, ...)
report_sender(username, ...)

Arguments

`username`	A character string containing an Imgur username.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Report an Imgur user for inappropiate behavior.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
tkn <- imgur_login()
block_sender("someuser", token = tkn)

## End(Not run)
## Not run: 
tkn <- imgur_login()
block_sender("someuser", token = tkn)

## End(Not run)

Search gallery

Description

Search Imgur public gallery

Usage

search_gallery(query, sort = 'time', page = 1, ...)
search_gallery(query, sort = 'time', page = 1, ...)

Arguments

`query`	A character string containing a search term.
`sort`	One of “time” or “top”.
`page`	A page number.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Search the gallery and return gallery images and associated metadata.

Value

An object of class “imgur_gallery_album”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
search_gallery(query = 'meme')

## End(Not run)
## Not run: 
search_gallery(query = 'meme')

## End(Not run)

Update album

Description

Update album metadata

Usage

update_album(album, id = NULL,
             title = NULL, description = NULL,
             privacy = NULL, layout = NULL, cover_id = NULL, ...)
update_album(album, id = NULL,
             title = NULL, description = NULL,
             privacy = NULL, layout = NULL, cover_id = NULL, ...)

Arguments

`album`	An album ID or object of class “imgur_album”. If no `token` is supplied, `album` must be a deletehash from the original `create_album` response.
`id`	A vector of one or more image IDs to add to the album or a list of objects of class “imgur_image”.
`title`	Optionally, an album title.
`description`	Optionally, an album description.
`privacy`	The privacy for the album. One of “public”, “hidden”, or “secret”.
`layout`	The layout for the album. One of “blog”, “grid”, “horizontal”, or “vertical”.)
`cover_id`	An image ID or an object of class “imgur_image”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Updates the images or metadata of an album. All options are are optional. To anonymously update an album, album must be the deletehash value from create_album.

Value

An object of class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
# update using a deletehash, anonymously
i <- imgur()
hist(rnorm(20))
img <- imgur_off(i)
a1 <-
create_album(id = img,
             title = 'My first Imgur album',
             description = 'A simple album',
             privacy = 'hidden',
             layout = 'grid',
             cover_id = img)
update_album(a1$deletehash, title = 'My second Imgur album')

# update using an OAuth token
tkn <- imgur_login()
a2 <-
create_album(id = img,
             title = 'My first Imgur album',
             description = 'A simple album',
             privacy = 'hidden',
             layout = 'grid',
             cover_id = img,
             token = tkn)
update_album(a2, title = 'My second Imgur album')

## End(Not run)
## Not run: 
# update using a deletehash, anonymously
i <- imgur()
hist(rnorm(20))
img <- imgur_off(i)
a1 <-
create_album(id = img,
             title = 'My first Imgur album',
             description = 'A simple album',
             privacy = 'hidden',
             layout = 'grid',
             cover_id = img)
update_album(a1$deletehash, title = 'My second Imgur album')

# update using an OAuth token
tkn <- imgur_login()
a2 <-
create_album(id = img,
             title = 'My first Imgur album',
             description = 'A simple album',
             privacy = 'hidden',
             layout = 'grid',
             cover_id = img,
             token = tkn)
update_album(a2, title = 'My second Imgur album')

## End(Not run)

Update image

Description

Update image metadata

Usage

update_image(id, title = NULL, description = NULL, ...)
update_image(id, title = NULL, description = NULL, ...)

Arguments

`id`	An image ID or object of class “imgur_image”. If no `token` is supplied, `id` must be a deletehash from the original `upload_image` response.
`title`	Optionally, an image title.
`description`	Optionally, an image description.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

Update the title or description of an already-uploaded image.

Value

A logical, with the class “imgur_basic”.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
# using a deletehash, anonymously
u <- upload_image('file.png')
update_image(u$deletehash, title = 'New Title')

# using an OAuth token
tkn <- imgur_login()
u <- upload_image('file.png', token = tkn)
update_image(u, title = 'New Title', token = tkn)

## End(Not run)
## Not run: 
# using a deletehash, anonymously
u <- upload_image('file.png')
update_image(u$deletehash, title = 'New Title')

# using an OAuth token
tkn <- imgur_login()
u <- upload_image('file.png', token = tkn)
update_image(u, title = 'New Title', token = tkn)

## End(Not run)

Upload an image file to Imgur

Description

Uploads a named image file to Imgur, optionally to a specified album.

Usage

upload_image(file, title = NULL, description = NULL, album = NULL,
             name = NULL, type = 'file', ...)
imgur_upload(file, title = NULL, description = NULL, album = NULL,
             name = NULL, type = 'file', ...)
upload_image(file, title = NULL, description = NULL, album = NULL,
             name = NULL, type = 'file', ...)
imgur_upload(file, title = NULL, description = NULL, album = NULL,
             name = NULL, type = 'file', ...)

Arguments

`file`	Name of the file to be uploaded to imgur.com
`title`	Optionally, an image title.
`description`	Optionally, an image description.
`album`	Optionally, an Imgur album ID.
`name`	Optionally, a file name, otherwise the `file` filename is used.
`type`	Should be “file”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token) or `key` (an API key, used by default).

Details

upload_image allows users to upload a named file to Imgur. imgur_upload is an alias that can serve as a drop-in replacement for the imgur_upload function in the knitr package.

Value

A list parsed from the imguR JSON response after uploading the plot (see the imgur API for details).

Author(s)

Thomas J. Leeper, adapted from code by Aaron Statham (imguRupload from imguR v0.1) and Yihue Xie (knitr::imgur_upload).

References

https://api.imgur.com/endpoints/image#image-upload

Examples

## Not run: 
pdf(tmpfile <- tempfile())
hist(rnorm(20))
dev.off()
upload_image(tmpfile)

## End(Not run)
## Not run: 
pdf(tmpfile <- tempfile())
hist(rnorm(20))
dev.off()
upload_image(tmpfile)

## End(Not run)

Vote on a comment

Description

Vote a comment up or down.

Usage

vote_comment(comment, vote = 'up', ...)
vote_comment(comment, vote = 'up', ...)

Arguments

`comment`	A comment ID, perhaps returned by `create_comment`.
`vote`	A character string indicating the direction of the vote, one of “up” or “down”.
`...`	Other arguments passed to HTTP request functions, for example: `token` (an OAuth2.0 token), which is required.

Details

Votes a comment up or down.

Value

An object of class “imgur_basic”

Author(s)

Thomas J. Leeper

Package 'imguR'

Help Index

Imgur API Client Package for R

Description

Author(s)

References

Retrieve user account details

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Retrieve user albums

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Retrieve user albums

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Retrieve user favorites

Description

Usage

Arguments

Details

Value

Author(s)

Examples

User gallery profile

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Retrieve user images

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Retrieve and modify account settings

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Manage album images

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Add gallery images

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Imgur API Authentication

Description