Hacking with the Flickr API by isp11018


									Hacking with the Flickr API

        Ross Harmes
        What We’ll Cover
•  API basics
  –  API key, auth, UTF-8
  –  Request and response formats
•  Commonly used methods
  –  people, photos, geo
•  API kits
•  Cool API features that aren't well
The Basics
                API Basics
•  The Flickr API consists of a set of callable
   methods, and some API endpoints
   (corresponding to a request format)


•  To perform an action using the Flickr API,
   you need
  –  a calling convention (a request format)
  –  a method
  –  some arguments
              API Basics
•  Required parameters:
  –  method is used to specify the calling
  –  api_key is used to specify your API Key.
       API Basics: Method
•  Required
•  Looks like this:


•  Each method takes a set of
      API Basics: API Key
•  Required, but easily obtainable:


•  Use a new key for each project
•  Every call must include this key
 API Basics: Authentication
•  Some methods require the user to be
   logged in
  –  This is noted in each methods' documentation
•  There are step-by-step guides for
   authenticating the user, one each for
   web apps, desktop apps, and mobile

       API Basics: UTF-8
•  The Flickr API expects all data to
   be UTF-8 encoded

•  Sending data in any other encoding
   will result in garbage
  – It wont be dangerous garbage (we will
    always store valid UTF-8) but it will
    still be garbage.
API Basics: Request Format
•  Valid request formats:
   –  REST
      •  Endpoint:   http://api.flickr.com/services/rest/	

   –  XML-RPC
      •  Endpoint:   http://api.flickr.com/services/xmlrpc/	

   –  SOAP
      •  Endpoint:   http://api.flickr.com/services/soap/

•  The default response format for each is the request
 API Basics: Response Format
•  Possible response formats:
  –  REST
     •  format=rest	
  –  XML-RPC
     •  format=xmlrpc
  –  SOAP
     •  format=soap
  –  JSON
     •  format=json
  –  PHP (serialized)
     •  format=php	
  –  Feeds (only available on some methods)
     •  More on this in a few slides
Commonly Used Methods
  Commonly Used Methods
•  flickr.people.findByUsername	
 –  Takes a username, returns an nsid	
 –  This nsid is used to identify the user in
    later calls
   •  Can be used for fetching user info, photos,
      favorites, contacts, tags, etc.
  Commonly Used Methods
•  flickr.people.getInfo	
  –  Takes an nsid, returns information
     about that user, including:
    •  Username and realname
    •  Location
    •  Photostream and Profile page URLs
    •  Server info needed assemble their buddy
       icon URL
    •  Some general photo info
  Commonly Used Methods
•  flickr.people.getPublicPhotos	
 –  Takes an nsid and some optional
    parameters, returns info on up to 500 of
    that users' public photos
 –  Optional args:
   •  page and per_page, used for pagination
   •  extras, returns extra info with each photo
      –  license, date_taken, geo, tags,
         machine_tags, views, and more
 Commonly Used Methods
•  flickr.interestingness.getList	
 –  Similar to
    flickr.people.getPublicPhotos, but
    takes an optional date instead of an
    nsid (uses the same optional args)
 –  Returns a list of interesting photos for
    the date given
  Commonly Used Methods
•  flickr.contacts.getPublicList
   and flickr.contacts.getList	
 –  Takes an nsid and returns a list of the
    contacts for a given user.
 –  getList requires auth, but returns
    more info and allows additional
  Commonly Used Methods
•  flickr.places.findByLatLon	
 –  Takes a lat/lon and optional accuracy	
 –  Returns a place_id for that location,
    which can be used to find photos taken
    near by
 –  accuracy lets you specify level: world
    (1), country (~3), region (~6), city
    (~11), street (~16).
  Commonly Used Methods
•  flickr.photos.search	
  –  Very powerful; takes a huge number of
     optional args, returns info on a list of
     photos that match.
  –  Some args:
    •  user_id, tags, text, license, sort,
       bbox, content_type, machine_tags,
       woe_id, place_id, lat, lon, radius	
  Commonly Used Methods
•  Testing and Reflection:
  –  flickr.test.echo	
  –  flickr.test.login	
  –  flickr.test.null

  –  flickr.reflection.getMethodInfo	
  –  flickr.reflection.getMethods

  –  flickr.com/services/api/explore/?
     method=<method name here>
API Kits
              API Kits
•  There are kits for most popular
   languages that encapsulate all of the
   API calls in a nice interface
•  These are not maintained by Flickr;
   use at your own risk
•  Well suited to Hack Day, as they take
   care of the details for you
                   API Kits
•  Full list at:

•  Some supported languages:

  ActionScript, C, Java, .NET, Obj-C,
  Perl, PHP, Python, Ruby
                  API Kits
•  Some create native wrappers for
   each API method (phpFlickr):


 $f = new phpFlickr("[API Key]");

 $person = $f->people_findByUsername('rossharmes');

 // Get the user's first 36 public photos

 $photos = $f->people_getPublicPhotos(

     $person['id'], NULL, 36);

                  API Kits
•  Some have one method that takes
   the API method name as an arg

 require_once 'Flickr/API.php';

 $api =& new Flickr_API(array(

      'api_key' => '1234567890'


 $response = $api->callMethod(


     array('foo' => 'bar')


              API Kits
•  Each has a completely different
•  Check the documentation and
•  Once properly configured, they will
   save you lots of time
Cool API Features That
  Aren't Well Known
        Cool API Features
•  Radial Geo Queries
  –  Use the optional lat, lon, and radius
     arguments to flickr.photos.search	
  –  Narrows your results to photos that fall
     within the radius given
  –  You can also specify any other args, to
     further narrow the results.

   Example: return all CC-licensed photos with
   the tag "mural" within 4 miles of 25th and
        Cool API Features
•  Contact Search (experimental)
  –  Use the optional contact argument to
  –  Narrows your results to your contacts
     (with all) or your friends and family
     (with ff)

   Example: return all photos from my
   contacts with the word "Ross" in the
   title, description or tags
        Cool API Features
•  flickr.places.placesForUser (new)
  –  Return a list of the top 100 unique places
     clustered by a given placetype for a user
  –  Optional place_type parameter; allows
     you to a place type to cluster photos by:
    •  neighbourhood, locality, region, country	

   Example: return all of the countries that a
   given user has taken photos in
        Cool API Features
•  WOE IDs
  –  WOE IDs are the unique identifiers in the
     giant database of places that we (Flickr,
     FireEagle, and Y!) use
  –  In Flickr, every geo-tagged photo has up to
     (6) WOE IDs associated with mapping to:
    •  neighbourhood, locality, county (maybe), region,
       country and continent

       Cool API Features
•  API Responses as Feeds (new,
  –  flickr.photos.search and
     flickr.favorites.getList take an
     optional argument format	
    •  Some values: feed-rss_100, feed-
       rss_200, feed-atom_10, feed-kml, and
       lots more
        Cool API Features
•  More on API Responses as Feeds
  –  Gives you:
    •  the ability to subscribe to the output of a
       Flickr API call in a feed aggregator
    •  the ability to get the results of Flickr API
       calls as KML (or GeoRSS)
    •  the ability to use the Flickr API in those
       devices that support RSS feeds (like photo

        Cool API Features
•  Machine Tags
  –  "If you’re not already familiar with machine
     tags the easiest way to think of them is
     being like a plain old tag but with a special
     syntax that allows users to define
     additional structured data about that tag.

   In turn the magic space hamsters that run
   the site have been trained to recognize,
   index and allow for searches across
   multiple facets of a given machine tag."
           Cool API Features
•  Machine Tags
  –  Structure: e.g. lastfm:event=34640	
    •  a namespace, lastfm	
    •  a predicate, event	
    •  a value, 34640	
  –  Some examples:
    •    flickr:user=bees	   •    flora:tree=coniferous 	
    •    upcoming:event=	    •    medium:paint=oil	
    •    facebook:user=	     •    geo:lat=	
    •    *:user=	            •    geo:lon=	
    •    *:locality=	
    •    *:*=sanfrancisco	
        Cool API Features
•  (Much) more info on Machine Tags
  –  Official announcement:
  –  Some blog posts:


  –  Some good links:
                                             The End


Photo credits (in order): 60's chainsaw blade shot by hemmob, nuts! by paul+photos=moody, every screw you need by st bernard,
                         Tool drawers II by JustABigGeek, Chip Off The Old Block by evanleavitt, tools by tashland

To top