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.