API Syntax

SamirD · July 22, 2009

I searched every single thing in the SM world on the API for how to use it. I've spent a good part of the whole day on this now.

I've gathered this much, you use something like:

http://api.smugmug.com/hack/rest/1.2.0/?method=smugmug.users.getTree&SessionID=&Nickname=USERNAME&SitePassword=PASSWORD

You replacing 'rest' in the path with 'json' or 'php' or 'rest' depending on the output you want. I can't replace that with 'xml-rpc'. That didn't seem to work.

The method seems to be the function you want to use.

But I have no idea what SessionID should be or where the APIKey or API secret go or even should go.

I feel so damn retarded. I know this stuff isn't this hard. Cryptic as 2000 year old Egyptian hieroglyphics, but I'm sure it's not that hard with some explanations or documentation.

Any assistance appreciated.

bwg · July 22, 2009

SamirD wrote:

I searched every single thing in the SM world on the API for how to use it. I've spent a good part of the whole day on this now.

I've gathered this much, you use something like:

You replacing 'rest' in the path with 'json' or 'php' or 'rest' depending on the output you want. I can't replace that with 'xml-rpc'. That didn't seem to work.

The method seems to be the function you want to use.

But I have no idea what SessionID should be or where the APIKey or API secret go or even should go.

I feel so damn retarded. I know this stuff isn't this hard. Cryptic as 2000 year old Egyptian hieroglyphics, but I'm sure it's not that hard with some explanations or documentation.

Any assistance appreciated.

first you'll need to request an api key here:
http://www.smugmug.com/hack/apikeys

the api documentation is on the wiki here:
http://wiki.smugmug.net/display/API/API+1.2.2

SamirD · July 22, 2009

Thank you for the reply. I've got my key, and somehow after looking at examples and other things over and over, I've figured out how to use it. The documentation never helped me with syntax.

For the rest of you who are completely in the dark on syntax. Open this in another window and read along:
http://wiki.smugmug.net/display/SmugMug/API+1.2.0

The 'Endpoints' are the base path or url depending on the format of the value returned to you. For testing, 'rest' works well because the browser will display the output.

The 'Methods' are functions that will do something if you fill in their appropriate arguements.

Each arguement if preceeded by '&' and the arguement name. Arguements can be in any order. (At least so far in my testing.)

So an API call looks something like this:

http://api.smugmug.com/hack/FORMAT/1.2.0/?method=VALUE&ARGUEMENT=VALUE&APIKey=KEY
or SSL:
http

/api.smugmug.com/hack/FORMAT/1.2.0/?method=VALUE1&ARGUEMENT=VALUE2&APIKey=KEY

Where FORMAT is rest, json, php, or xmlrpc
Where VALUE1 is the method name, eg 'smugmug.albums.get' or 'smugmug.login.withPassword'
Where ARGUEMENT is one of the arguements for the method, like 'SessionID' on method 'smugmug.users.getTree'
Where VALUE2 is the value for that arguement, like your Smugmug assigned API Key for the arguement 'APIKey' under method 'smugmug.login.withHash'

So now let's put this all together.

So let's say you want a list of all your albums outputted in the format 'rest'.

Well, first you have to login. So you can login using the following:

https://api.smugmug.com/hack/rest/1.2.0/?method=smugmug.login.withPassword&APIKey=YOURAPIKEY&EmailAddress=email@domain.com&Password=yourpassword

You get back something like this which includes your 'userid' and 'passwordhash'. You'll want to use these from now on to login.

<rsp stat="ok">
  <method>smugmug.login.withPassword</method>
  <Login PasswordHash="$7s87s657sd78$zmUjF6gTpMS6756dfuZ1" AccountType="Pro" FileSizeLimit="25165824" SmugVault="0">
    <Session id="df09977745cf85035f66c2be596a8e75"/>
    <User id="55555" NickName="yourname" DisplayName="yourname"/>
  </Login>
</rsp>

So we'll use the method 'smugmug.login.withHash' to login. It will look like this:

https://api.smugmug.com/hack/rest/1.2.0/?method=smugmug.login.withHash&APIKey=YOURAPIKEY&UserID=55555&PasswordHash=$7s87s657sd78$zmUjF6gTpMS6756dfuZ1

This will log you in without exposing your email and password even if someone gets to your source code.

Well now that we're in, we can find the method that does what we want. Hmmm...which one. This 'smugmug.albums.get' sounds promising. Well look at that, it "Retrieves a list of albums for a given user." Sounds peachy.

So now what arguements does it require? SessionID. Where do we get that? Oh yeah, it's above in the output from when we logged in.

So let's try it:

https://api.smugmug.com/hack/rest/1.2.0/?method=smugmug.albums.get&APIKey=YOURAPIKEY&SessionID=df09977745cf85035f66c2be596a8e75

And bingo! You get something like this:

<rsp stat="ok">
  <method>smugmug.albums.get</method>
  <Albums>
	<Album id="8977694" Key="7ghdV" Title="08111601.B">
	  <Category id="292127" Name="Archive"/>
	  <SubCategory id="664318" Name="2008"/>
	</Album>
	<Album id="9003692" Key="psZex" Title="08111501.B">
	  <Category id="292127" Name="Archive"/>
	  <SubCategory id="664318" Name="2008"/>
	</Album>
	<Album id="8953330" Key="7wtpy" Title="08112201.B">
	  <Category id="292127" Name="Archive"/>
	  <SubCategory id="664318" Name="2008"/>
	</Album>
	<Album id="9965655" Key="DhhHw" Title="08111701.B">
	  <Category id="292127" Name="Archive"/>
	  <SubCategory id="664318" Name="2008"/>
	</Album>
	<Album id="9963599" Key="N6gSj" Title="08112101.B">
	  <Category id="292127" Name="Archive"/>
	  <SubCategory id="664318" Name="2008"/>
	</Album>
	<Album id="9922974" Key="ks9zF" Title="08112301.B">
	  <Category id="292127" Name="Archive"/>
	  <SubCategory id="664318" Name="2008"/>
	</Album>
	<Album id="9920747" Key="ThxmY" Title="08122501.B">
	  <Category id="292127" Name="Archive"/>
	  <SubCategory id="664318" Name="2008"/>
	</Album>
	<Album id="9922057" Key="oqJhc" Title="08122901.B">
	  <Category id="292127" Name="Archive"/>
	  <SubCategory id="664318" Name="2008"/>
	</Album>
  </Albums>
</rsp>

You will use this inside of other html or javascript or whatever programming language, but you can also use it straight from the browser to just get some information that you can then parse manually.

This is probably basic stuff to most programmers, but is base64 encoded Chinese to the rest of us!

I wrote this for myself because I'd forget all this by tommorrow. If you the reader also find it useful, that's a bonus. <img src="https://us.v-cdn.net/6029383/emoji/thumb.gif" border="0" alt="" >

I'll be using this knowledge to design a php script that will get all my albums on a daily basis from a particular gallery, turn these into custom urls, combine them with other smugmug custom urls, randomly feed one of the galleries to the random picture generator to get a picture url, parse that picture url to re-create a custom picture url as well as a link to the original picture in the gallery.

This little module will replace the random picture module I'm using on my web site, www.huntsvillecarscene.com. I'm not a programmer. This is going to be fun. :cry

devbobo · July 26, 2009

Hey Samir,

Good to see that you are having some fun with the API

If you are going to use php, I recommend that you use the php api (or json) as it's the easiest way to interact with the response.

Say, you had the response to a PHP API call in the variable $rsp, to convert that back to a PHP object you just call...

$obj = unserialize($rsp);

Also, instead of bumping a whole load of random threads, keep this thread going with your progress and what info you are looking for...and I'll help you as as required.

Cheers,

David

devbobo · July 26, 2009

Also, you might want to check out Colin Seymour's php wrapper for the API...it may take a look of the headache out of actually building all the api interaction yourself.

Cheers,

David

SamirD · July 26, 2009

Thank you for the reply. I've been playing with this over the weekend since I couldn't work on anything else. I've been using phpsmug since this keeps everything in one language.

So far, it pulls the list of albums, and then builds gallery urls from the album and album key fields. Now I need to figure out how to write that to a file.

One thing that's interesting though, I've noticed that a php \n isn't creating a newline. Not sure if it is a phpsmug thing or something else.

Also, I haven't had any luck using loginwithhash even with \$ as replacements for the $ in the hash. I think these may be related.

devbobo · July 26, 2009

Post (or PM me) your current code and i'll take a look.

Typically, parameters that take strings should be url encoded, try using urlencode($str) to do this.

Cheers,

David

SamirD · July 27, 2009

pm sent.

SamirD · August 28, 2009

Back to working on this using phpsmug. My passwordhash contains periods. Do these need escaping in php? I know the dollar signs do.

I haven't had any luck on using login_withHash and thought this may be an issue. regular login works fine.

pearsonartphoto · August 28, 2009

It's funny, I've had almost the exact same reaction as you did to the API, and while I am a programmer, I'm not a web programmer at all... My first ever script that does a thing is listed below, and it took me a good deal to work my way through it... Funny how that is sometimes... Still, it's nice to dust off my old Python skills and put them to use to do something new and interesting, that's for sure. So far all this does is print the name of every album I've ever made, but it's a framework for something to come. Oh, and a good simple first URL, just to help those who didn't know to put a question mark like myself.

https://api.smugmug.com/services/api/json/1.2.2/?APIKey=PUBLIC_API_KEY&method=smugmug.login.anonymously

import urllib, urllib.parse, urllib.request, json

APIServer="https://api.smugmug.com/services/api/json/1.2.2/?"

def smugmug_call(keys) :
url=APIServer+urllib.parse.urlencode(keys);
raw_data=urllib.request.urlopen(url)
results=json.loads(raw_data.readall().decode())
return results

session = smugmug_call({"APIKey": APIKey,"method":"smugmug.login.anonymously"})
albums=smugmug_call({'SessionID' : session,'NickName':'pearsonartphoto',"method":'smugmug.albums.get'})
index=0
for album in albums:
index+=1
print(index,album)

SamirD · November 3, 2010

I'm so glad I wrote this.

I've read this so many times and didn't have to re-invent the wheel each time I wanted to work with the API.

SamirD · September 19, 2012

Came in handy again. Maybe it will help someone else too.

API Syntax

Comments