WWW::SmugMug::API - Perl wrapper for the SmugMug API

- NAME
- VERSION
- SYNOPSIS
- SUBROUTINES/METHODS

- new
- albums_applyWatermark
- albums_changeSettings
- albums_create
- albums_delete
- albums_get
- albums_getInfo
- albums_getStats
- albums_removeWatermark
- albums_reSort
- albumtemplates_changeSettings
- albumtemplates_create
- albumtemplates_get
- categories_create
- categories_delete
- categories_get
- categories_rename
- family_add
- family_get
- family_remove
- family_removeAll
- friends_add
- friends_get
- friends_remove
- friends_removeAll
- images_applyWatermark
- images_changePosition
- images_changeSettings
- images_crop
- images_delete
- images_getEXIF
- images_getInfo
- images_getStats
- images_getURLs
- images_removeWatermark
- images_rotate
- images_zoomThumbnail
- login_anonymously
- products_get
- propricing_getPortfolio
- propricing_getAlbum
- propricing_getImage
- sharegroups_addAlbum
- sharegroups_create
- sharegroups_delete
- sharegroups_get
- sharegroups_getInfo
- sharegroups_removeAlbum
- subcategories_create
- subcategories_delete
- subcategories_get
- subcategories_getAll
- subcategories_rename
- themes_get
- users_getDisplayName
- users_getTransferStats
- users_getTree
- watermarks_changeSettings
- watermarks_create
- watermarks_delete
- watermarks_get
- watermarks_getInfo
- getSessionID
- images_upload

- DIAGNOSTICS
- CONFIGURATION AND ENVIRONMENT
- DEPENDENCIES
- INCOMPATIBILITIES
- BUGS AND LIMITATIONS
- SUPPORT
- AUTHOR
- ACKNOWLEDGEMENTS
- LICENSE AND COPYRIGHT

# NAME

WWW::SmugMug::API - Perl wrapper for the SmugMug API

# VERSION

Version 1.02

# SYNOPSIS

        use WWW::SmugMug::API;

        my $sm_api = WWW::SmugMug::API->new(
            {
                sm_api_key => 'changeme',
                secure     => 1,
            }
        );

        $sm_api->login_withPassword(
            {
                EmailAddress => 'me@privacy.net',
                Password     => 'password',
            }
        );
        ...
        $sm_api->logout;

    =head1 DESCRIPTION

Provides a low-level wrapper for the 1.2.0 version of the SmugMug API. Calls requiring a SessionID use the one returned from the last successful login call (login_anonymously, login_withPassword, or login_withHash), and calls requiring the API key use the sm_api_key parameter passed to the constructor; these provided parameters cannot be overridden. All other required parameters must be provided by the caller.

The wrapper will silently discard any parameters that it does not recognise.

Method names are the API methods with the 'smugmug.' prefix removed and '_' substituted for '.' (e.g. 'smugmug.login.withPassword becomes `login_withPassword())`

Methods return hash references. The value of the 'stat' key will be 'ok' if the call succeeded, 'fail' otherwise. Fail responses contain three key/value pairs: 'stat', 'message', and 'code'. Message is an informative message about the failure. The code will be positive for an error thrown by SmugMug and negative for one from the wrapper. The following error codes are known:

-3

  Session not initialised. Before calling any other methods, you must successfully call login_anonymously, login_withPassword, or login_withHash.

-2

  HTTP error. Message will be the complete error (e.g. '404 Not Found')

-1

  Missing required parameter. All parameters listed in the documentation as required must be provided, or the wrapper will reject the call.

- Invalid login.

- Invalid session.

- Invalid user.

- System error.

- Wrong format. (Image format when uploading, I believe)

- Invalid album.

- Ancient version.

- Empty set.

- Invalid API key.

NOTE: While this wrapper does provide a method called images_upload, per the best practices recommendation of the SmugMug developers we use a binary uploading method (HTTP PUT) to upload the image; it is not an implementation of the API method smugmug.images.upload. images_uploadFromURL is not provided.

# SUBROUTINES/METHODS

## new

Create a new client object. Parameters:

sm_api_key

  API key

agent

  Useragent string.

secure

  Set this to `1` to use SSL. Defaults to `0`

timeout

  Time (in seconds) to wait for a response. Defaults to 30.

retry

  Set this to `1` to retry on error. Defaults to `0`

## albums_applyWatermark

Calls smugmug.albums.applyWatermark.

Parameters:

AlbumID (integer) (required)
WatermarkID (integer) (required)

## albums_changeSettings

Calls smugmug.albums.changeSettings.

Parameters:

AlbumID (integer) (required)
Title (string)
CategoryID (integer)
SubCategoryID (integer)
Description (string)
Keywords (string)
AlbumTemplateID (integer)
Geography (boolean)
HighlightID (integer)
Position (integer)
Header (boolean)
Clean (boolean)
EXIF (boolean)
Filenames (boolean)
SquareThumbs (boolean)
TemplateID (integer)
SortMethod (string)
SortDirection (boolean)
Password (string)
PasswordHint (string)
Public (boolean)
WorldSearchable (boolean)
SmugSearchable (boolean)
External (boolean)
Protected (boolean)
Watermarking (boolean)
WatermarkID (integer)
HideOwner (boolean)
Larges (boolean)
XLarges (boolean)
X2Larges (boolean)
X3Larges (boolean)
Originals (boolean)
CanRank (boolean)
FriendEdit (boolean)
FamilyEdit (boolean)
Comments (boolean)
Share (boolean)
Printable (boolean)
DefaultColor (boolean)
ProofDays (integer)
Backprinting (string)
UnsharpAmount (float)
UnsharpRadius (float)
UnsharpThreshold (float)
UnsharpSigma (float)
CommunityID (integer)

## albums_create

Calls smugmug.albums.create.

Parameters:

Title (string) (required)
CategoryID (string) (required)
SubCategoryID (integer)
Description (string)
Keywords (string)
AlbumTemplateID (integer)
Geography (boolean)
HighlightID (integer)
Position (integer)
Header (boolean)
Clean (boolean)
EXIF (boolean)
Filenames (boolean)
SquareThumbs (boolean)
TemplateID (integer)
SortMethod (string)
SortDirection (boolean)
Password (string)
PasswordHint (string)
Public (boolean)
WorldSearchable (boolean)
SmugSearchable (boolean)
External (boolean)
Protected (boolean)
Watermarking (boolean)
WatermarkID (integer)
HideOwner (boolean)
Larges (boolean)
XLarges (boolean)
X2Larges (boolean)
X3Larges (boolean)
Originals (boolean)
CanRank (boolean)
FriendEdit (boolean)
FamilyEdit (boolean)
Comments (boolean)
Share (boolean)
Printable (boolean)
DefaultColor (boolean)
ProofDays (integer)
Backprinting (string)
UnsharpAmount (float)
UnsharpRadius (float)
UnsharpThreshold (float)
UnsharpSigma (float)
CommunityID (integer)

## albums_delete

Calls smugmug.albums.delete.

Parameters:

AlbumID (integer) (required)

## albums_get

Calls smugmug.albums.get.

Parameters:

NickName (string)
Heavy (boolean)
SitePassword (string)
ShareGroup ()

## albums_getInfo

Calls smugmug.albums.getInfo.

Parameters:

AlbumID (string) (required)
Password (string)
SitePassword (string)
AlbumKey (string)

## albums_getStats

Calls smugmug.albums.getStats.

Parameters:

AlbumID (integer) (required)
Month (integer) (required)
Year (integer) (required)
Heavy (boolean)

## albums_removeWatermark

Calls smugmug.albums.removeWatermark.

Parameters:

AlbumID (integer) (required)

## albums_reSort

Calls smugmug.albums.reSort.

Parameters:

AlbumID (integer) (required)
By (string) (required)
Direction (string) (required)

## albumtemplates_changeSettings

Calls smugmug.albumtemplates.changeSettings.

Parameters:

AlbumTemplateID (integer) (required)
Name (string)
HighlightID (integer)
SortMethod (string)
SortDirection (boolean)
Public (boolean)
Password (string)
PasswordHint (string)
Printable (boolean)
Filenames (boolean)
Comments (boolean)
External (boolean)
Originals (boolean)
EXIF (boolean)
Share (boolean)
Header (boolean)
Larges (boolean)
XLarges (boolean)
X2Larges (boolean)
X3Larges (boolean)
Clean (boolean)
Protected (boolean)
Watermarking (boolean)
FamilyEdit (boolean)
FriendEdit (boolean)
HideOwner (boolean)
DefaultColor (boolean)
Geography (boolean)
CanRank (boolean)
ProofDays (integer)
Backprinting (string)
SmugSearchable (boolean)
UnsharpAmount (float)
UnsharpRadius (float)
UnsharpThreshold (float)
UnsharpSigma (float)
WorldSearchable (boolean)
TemplateID (integer)
CommunityID (integer)
WatermarkID (integer)

## albumtemplates_create

Calls smugmug.albumtemplates.create.

Parameters:

Name (string)
HighlightID (integer)
SortMethod (string)
SortDirection (boolean)
Public (boolean)
Password (string)
PasswordHint (string)
Printable (boolean)
Filenames (boolean)
Comments (boolean)
External (boolean)
Originals (boolean)
EXIF (boolean)
Share (boolean)
Header (boolean)
Larges (boolean)
XLarges (boolean)
X2Larges (boolean)
X3Larges (boolean)
Clean (boolean)
Protected (boolean)
Watermarking (boolean)
FamilyEdit (boolean)
FriendEdit (boolean)
HideOwner (boolean)
DefaultColor (boolean)
Geography (boolean)
CanRank (boolean)
ProofDays (integer)
Backprinting (string)
SmugSearchable (boolean)
UnsharpAmount (float)
UnsharpRadius (float)
UnsharpThreshold (float)
UnsharpSigma (float)
WorldSearchable (boolean)
TemplateID (integer)
CommunityID (integer)
WatermarkID (integer)

## albumtemplates_get

Calls smugmug.albumtemplates.get.

Parameters:

No parameters

## categories_create

Calls smugmug.categories.create.

Parameters:

Name (string) (required)

## categories_delete

Calls smugmug.categories.delete.

Parameters:

CategoryID (integer) (required)

## categories_get

Calls smugmug.categories.get.

Parameters:

NickName (string)
SitePassword (string)

## categories_rename

Calls smugmug.categories.rename.

Parameters:

CategoryID (integer) (required)
Name (string) (required)

## family_add

Calls smugmug.family.add.

Parameters:

NickName (string) (required)

## family_get

Calls smugmug.family.get.

Parameters:

No parameters

## family_remove

Calls smugmug.family.remove.

Parameters:

NickName (string) (required)

## family_removeAll

Calls smugmug.family.removeAll.

Parameters:

No parameters

## friends_add

Calls smugmug.friends.add.

Parameters:

NickName (string) (required)

## friends_get

Calls smugmug.friends.get.

Parameters:

No parameters

## friends_remove

Calls smugmug.friends.remove.

Parameters:

NickName (string) (required)

## friends_removeAll

Calls smugmug.friends.removeAll.

Parameters:

No parameters

## images_applyWatermark

Calls smugmug.images.applyWatermark.

Parameters:

ImageID (integer) (required)
WatermarkID (integer) (required)

## images_changePosition

Calls smugmug.images.changePosition.

Parameters:

ImageID (integer) (required)
Position (integer) (required)

## images_changeSettings

Calls smugmug.images.changeSettings.

Parameters:

ImageID (integer) (required)
AlbumID (integer)
Caption (string)
Keywords (string)
Hidden (boolean)

## images_crop

Calls smugmug.images.crop.

Parameters:

ImageID (integer) (required)
Width (integer) (required)
Height (integer) (required)
X (integer) (required)
Y (integer) (required)

## images_delete

Calls smugmug.images.delete.

Parameters:

ImageID (integer) (required)

## images_getEXIF

Calls smugmug.images.getEXIF.

Parameters:

ImageID (integer) (required)
Password (string)
SitePassword (string)
ImageKey (string)

## images_getInfo

Calls smugmug.images.getInfo.

Parameters:

ImageID (integer) (required)
Password (string)
SitePassword (string)
ImageKey (string)

## images_getStats

Calls smugmug.images.getStats.

Parameters:

ImageID (integer) (required)
Month (integer) (required)

## images_getURLs

Calls smugmug.images.getURLs.

Parameters:

ImageID (integer) (required)
TemplateID (integer)
Password (string)
SitePassword (string)
ImageKey (string)

## images_removeWatermark

Calls smugmug.images.removeWatermark.

Parameters:

ImageID (integer) (required)

## images_rotate

Calls smugmug.images.rotate.

Parameters:

ImageID (integer) (required)
Degrees (integer)
Flip (boolean)

## images_zoomThumbnail

Calls smugmug.images.zoomThumbnail.

Parameters:

ImageID (integer) (required)
Width (integer) (required)
Height (integer) (required)
X (integer) (required)
Y (integer) (required)

## login_anonymously

Calls smugmug.login.anonymously.

Parameters:

No parameters

UserID (integer) (required)
PasswordHash (string) (required)

EmailAddress (string) (required)
Password (string) (required)

No parameters

## products_get

Calls smugmug.products.get.

Parameters:

No parameters

## propricing_getPortfolio

Calls smugmug.propricing.getPortfolio.

Parameters:

ProductType (string)
ProductID (integer)

## propricing_getAlbum

Calls smugmug.propricing.getAlbum.

Parameters:

AlbumID (integer) (required)
ProductType (string)
ProductID (integer)

## propricing_getImage

Calls smugmug.propricing.getImage.

Parameters:

ImageID (integer) (required)
ProductType (string)
ProductID (integer)

## sharegroups_addAlbum

Calls smugmug.sharegroups.addAlbum.

Parameters:

ShareGroupID (integer) (required)
AlbumID (integer) (required)

## sharegroups_create

Calls smugmug.sharegroups.create.

Parameters:

Name (string) (required)
Description (string)

## sharegroups_delete

Calls smugmug.sharegroups.delete.

Parameters:

ShareGroupID (integer) (required)

## sharegroups_get

Calls smugmug.sharegroups.get.

Parameters:

Heavy (boolean)

## sharegroups_getInfo

Calls smugmug.sharegroups.getInfo.

Parameters:

ShareGroupID (integer) (required)

## sharegroups_removeAlbum

Calls smugmug.sharegroups.removeAlbum.

Parameters:

ShareGroupID (integer) (required)
AlbumID (integer) (required)

## subcategories_create

Calls smugmug.subcategories.create.

Parameters:

Name (string) (required)
CategoryID (integer) (required)

## subcategories_delete

Calls smugmug.subcategories.delete.

Parameters:

SubCategoryID (integer) (required)

## subcategories_get

Calls smugmug.subcategories.get.

Parameters:

CategoryID (integer) (required)
NickName (string)
SitePassword (string)

## subcategories_getAll

Calls smugmug.subcategories.getAll.

Parameters:

NickName (string)
SitePassword (string)

## subcategories_rename

Calls smugmug.subcategories.rename.

Parameters:

SubCategoryID (integer) (required)
Name (string) (required)

## themes_get

Calls smugmug.themes.get.

Parameters:

No parameters

## users_getDisplayName

Calls smugmug.users.getDisplayName.

Parameters:

NickName (string)

## users_getTransferStats

Calls smugmug.users.getTransferStats.

Parameters:

Month (integer) (required)
Year (integer) (required)
Heavy (boolean)

## users_getTree

Calls smugmug.users.getTree.

Parameters:

NickName (string)
Heavy (boolean)
SitePassword (string)
Sharegroup ()

## watermarks_changeSettings

Calls smugmug.watermarks.changeSettings.

Parameters:

ImageID (integer) (required)
Name (string)
Pinned (string)
Dissolved (integer)
Thumbs (boolean)

## watermarks_create

Calls smugmug.watermarks.create.

Parameters:

ImageID (integer) (required)
Name (string)
Pinned (string)
Dissolved (integer)
Thumbs (boolean)

## watermarks_delete

Calls smugmug.watermarks.delete.

Parameters:

WatermarkID (integer) (required)

## watermarks_get

Calls smugmug.watermarks.get.

Parameters:

Heavy (boolean)

## watermarks_getInfo

Calls smugmug.watermarks.getInfo.

Parameters:

WatermarkID (integer) (required)

## getSessionID

Returns the currently cached SessionID.

Parameters:

No parameters

## images_upload

Uploads an image.

Parameters:

ImageData (binary) (required)
FileName (string) (required)
AlbumID (integer)
ImageID (integer)
Caption (string)
Keywords (string)
Latitude (float?)
Longitude (float?)
Altitude (integer?)

# DIAGNOSTICS

This section intentionally left blank.

# CONFIGURATION AND ENVIRONMENT

WWW::SmugMUG::API requires no special configuration or environment variables.

# DEPENDENCIES

JSON LWP::UserAgent

# INCOMPATIBILITIES

No known incompatibilities.

# BUGS AND LIMITATIONS

No known bugs.

# SUPPORT

You can find documentation for this module with the perldoc command.

        perldoc WWW::SmugMug::API

# AUTHOR

Paul Arthur, `<flowerysong00 at yahoo.com>`

# ACKNOWLEDGEMENTS

This section intentionally left blank.

# LICENSE AND COPYRIGHT

Copyright 2008 Paul Arthur MacIain, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.