Fotki Public API Documentation

You will need a secret and a public key to use Fotki public API. For all API calls the following parameter is needed: api_key – API public key. Many methods require the user to be logged in. So here is an authorization procedure.

Authorization

First of all you must obtain API keys (public and secure). The authorization procedure consists of the following steps:
  1. Application makes background call to http://secure.fotki.com/api_auth?method=flickr.auth.getFrob&api_key=1234567890&api_sig=8a9e6894545aef457e120a
  2. Previous call returns frob = '45f86824465'
  3. Then application launches a web­browser with the URL –
    http://secure.fotki.com/api_auth?api_key=1234567890&perms=write&frob=45f86824465&api_sig=749a65949043ae1452d7500
  4. If user is not logged in to Fotki, he will be asked to do so.
  5. Then user is asked to allow application to read/write to his account
  6. If user says “YES” ­ Fotki updates it's database, and user is told to go back to application.
  7. When user returns to application and clicks “continue” button
  8. The application makes background call to
    http://secure.fotki.com/api_auth?method=flickr.auth.getToken&api_key=1234567890&frob=45f86824465&api_sig=4a1e56834d17ee2195672111
  9. Call from previous step returns token '0987654321'
  10. Authorization procedure is done. Now application is allowed to call methods, that require authorization, using “auth_token” received in previous step (step 9)
    Example call: http://api.fotki.com/v2flkr/flickr_photosets_getList?api_sig=261967ecf9d9665a75452b0c6f4f2731&api_key=1234567890&auth_token=4*JYGgd979*dflhjgJKH4698HHH97

Request Formats

POST/GET:
It’s a simple HTTP GET or POST request. Example of REST request:
http://api.fotki.com/v2flkr/upload?title=NewPhoto&description=NewPhotoDescription&tags=new,photo,api&photo=[photo_itself]

Response Formats

DEFAULT Response Format:
By default response is simple xml‐document
Example: 
<?xml version="1.0" encoding="utf­8" ?>
<rsp stat="ok">
   <photoid>487624164546</photoid>
</rsp>
if error occurs, so: 
<?xml version="1.0" encoding="utf­8" ?>
<rsp stat="fail">
   <err code="12" msg="Cannot upload photo" />
</rsp>
JSON response format:
If you specify “format=json” in your request, Fotki will response in JSON­format. It is almost the same as DEFAULT Response Format, but transformed in JSON – read json.org to get more info about this format.

Example:
DEFAULT XML: 
<?xml version="1.0" encoding="utf­8" ?>
<rsp stat="ok">
   <photoid>487624164546</photoid>
</rsp>
JSON for this DEFAULT XML: 
{"photo" : {"_content":"487624164546"} , "stat":"ok"}

API Functions

Every API–call must be signed. So every API–call must contain api_sig parameter.

Signing procedure:
  1. Sort your argument list into alphabetical order based on the parameter name:
    e.g. one=1, two=2, three=3 sorts to one=1, three=3, two=2
  2. concatenate you SECRET key (obtained from Fotki) with sorted name/values:
    e.g. SECRETone1three3two2
  3. calculate md5() of this string
  4. append this value to every API­call:
    e.g. api_sig=4d3c0a9b690f5cf5d1973a77bdecd76a

http://api.fotki.com/v2flkr/flickr_photos_getInfo : Get information about a photo.

This method does not require authorization.

Parameters:
api_key (Required)
   Your API public key.
photo_id (Required)
   The id of the photo to get information for.

Example Response 
<photo id="4878654632" license="3" rotation="90" originalformat="png">
   <owner nsid="46656165646" username="none" realname="Real None" location="San Francisco" />
   <title>Title</title>
   <description>It is Description</description>
   <visibility ispublic="1" isfriend="0" isfamily="0" />
   <dates posted="1711655130" taken="2009­06­25 15:22:19" takengranularity="0" lastupdate="1815627043" />
   <permissions permcomment="3" permaddmeta="2" />
   <editability cancomment="1" canaddmeta="1" />
   <comments>1</comments>
   <tags>
      <tag id="465456465" author="46656165646" raw="tag1">tag1</tag>
      <tag id="465456464" author="46656165646" raw="tag2">tag2</tag>
   </tags>
   <urls>
      <url type="photopage">http://www.fotki.com/none/test­album/Title.png</url>
   </urls>
</photo>

http://api.fotki.com/v2flkr/flickr_photos_getNotInSet : Returns a list of your photos that are not part of any sets.

This method requires authorization.

Parameters:
api_key (Required)
   Your API public key.

Example Response
This method returns the standard photo list xml: 
<photos page="1" pages="3" perpage="10" total="25">
   <photo id="466654687" owner="321546454456" title="title1" ispublic="1" isfriend="0" isfamily="0" />
   <photo id="654548864" owner="321546454456" title="title2" ispublic="0" isfriend="1" isfamily="1" />
   <photo id="465432132" owner="321546454456" title="title3" ispublic="1" isfriend="0" isfamily="0" />
   <photo id="4565213888" owner="321546454456" title="title4" ispublic="1" isfriend="0" isfamily="0" />
</photos>

http://api.fotki.com/v2flkr/flickr_photosets_addPhoto : Add a photo to the end of an existing photoset.

This method requires authorization.

Parameters:
api_key (Required)
   Your API public key.
photoset_id (Required)
   The id of the photoset
photo_id (Required)
   The id of the photo.

Example Response
This method returns empty success or fail response


http://api.fotki.com/v2flkr/flickr_photosets_create : Create a new photoset for the calling user.

This method requires authorization.

Parameters:
api_key (Required)
   Your API public key.
btitle (Required)
   A title for the photoset.
description (Optional)
   A description of the photoset.
primary_photo_id (Required)
   The id of the photo to represent this set. The photo must belong to the calling user.

Example Response 
<photoset id="45654895" url="http://www.fotki.com/none/newphotoset/" />

http://api.fotki.com/v2flkr/flickr_photosets_delete : Delete a photoset

This method requires authorization.

Parameters:
api_key (Required)
   Your API public key.
photoset_id (Required)
   The id of the photoset to delete

Example Response
This method returns empty success or fail response


http://api.fotki.com/v2flkr/flickr_photosets_editMeta : Modify the meta‐data for a photoset.

This method requires authorization.

Parameters:
api_key (Required)
   Your API public key.
photoset_id (Required)
   The id of the photoset to delete
title (Required)
   The new title for the photoset.
description (Optional)
   A description of the photoset. May contain limited html.

Example Response
This method returns empty success or fail response


http://api.fotki.com/v2flkr/flickr_photosets_getList : Returns the photosets belonging to the specified user.

This method does not require authorization.

Parameters:
api_key (Required)
   Your API application key.
user_id (Optional)
   The ID of the user to get a photoset list for.

Example Response 
<photosets cancreate="1">
   <photoset id="456786521" primary="46876213" photos="2" farm="1">
      <title>Test</title>
      <description>Test description</description>
   </photoset>
   <photoset id="721364646" primary="4566687963" photos="12" farm="1">
      <title>Next Set</title>
      <description>This is description too</description>
   </photoset>
</photosets>

http://api.fotki.com/v2flkr/flickr_photosets_getPhotos : Get the list of photos in a set.

This method does not require authorization.

Parameters:
api_key (Required)
   Your API application key. See here for more details.
photoset_id (Required)
   The id of the photoset to return the photos for

Example Response 
<photoset id="456786521" primary="46876213" page="1" perpage="500" pages="1" total="2">
   <photo id="45456488" title="photo in this set" isprimary="0" />
   <photo id="46876213" title="fotki is cool" isprimary="1" />
</photoset>

http://api.fotki.com/v2flkr/upload : Upload a photo

This method requires authorization.

Parameters:
api_key (Required)
   Your API application key.
photo
   The file to upload.
title (optional)
   The title of the photo.
description (optional)
   A description of the photo
tags (optional)
   A space­seperated photo tags

Example Response 
<photoid>468786232</photoid>

[back]