General documentation / cheat sheets for various languages and services

Flickr API

This document outlines the requirements for using the Flickr API and provides example responses for many of the endpoints.

For a more detailed reference, see the main Flickr API Documentation page.

Authentication

Many of the Flickr API endpoints can only be used in the context of a Flickr App. Create one and view the list of your Apps to find its Key and Secret.

Authenticating your personal Flickr account with your new Flickr App is more complicated. See the Flickr OAuth documentation for instructions on how to generated your personal OAuth token and secret.

Common request parameters

Formats

Unless a different format is specified, REST requests will receive REST responses (as if format=rest).

REST responses are XML, and look like this for successful requests:

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
  ...
</rsp>

Or this for bad requests:

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="fail">
  <err code="..." msg="..." />
</rsp>

By specifying format=json, we can get JSON responses for most methods.

It’s not actually JSON, though, it’s JSONP: the JSON object is wrapped in a jsonFlickrApi function call, so the full response actually looks like this:

jsonFlickrApi({...,"stat":"ok"})

To change jsonFlickrApi to something else, e.g., onPhotos, set the parameter jsoncallback, e.g.: jsoncallback=onPhotos.

By specifying format=json and nojsoncallback=1 together, we get back plain JSON.

Response to a successful request:

{
  ...,
  "stat": "ok"
}

Response to a bad request:

{
  "stat": "fail",
  "code": 112,
  "message": "Method \"flickr.photos.doesNotExist\" not found"
}

The response headers for a successful JSON request look like this:

{ "date": "Fri, 09 Aug 2013 18:46:16 GMT", "content-type": "text/javascript; charset=utf-8", "content-length": "113", "p3p": "policyref=\"http://info.yahoo.com/w3c/p3p.xml\", CP=\"CAO DSP ...\"", "cache-control": "private", "x-served-by": "www291.flickr.gf2.yahoo.com", "vary": "Accept-Encoding", "age": "0", "via": "http/1.1 fts315.flickr.gf2.yahoo.com (ApacheTrafficServer/4.0.2 [cMsSf ]), http/1.1 r07.ycpi.gf2.yahoo.net (ApacheTrafficServer [cMsSf ])", "server": "ATS", "strict-transport-security": "max-age=259200", "connection": "close" }

When the nojsoncallback=1 is used, you’ll instead see Content-Type: application/json.

Other available formats are xmlrpc (XML), soap (XML), soap2 (XML), and php_serial (PHP’s built-in serialization format).

Example responses

The sections below present example responses from several Flickr API methods. In all cases I have requested ?format=json&nojsoncallback=1, and when the Flickr API actually returns JSON, I have pretty-printed the result.

The ... placeholders indicate abbreviated arrays, where the abbreviated items look much like the shown item.

flickr.photosets.getList

{
  "photosets": {
    "cancreate": 1,
    "page": 1,
    "pages": 1,
    "perpage": 187,
    "total": 187,
    "photoset": [
      {
        "id": "72152618960573004",
        "primary": "7579195483",
        "secret": "e7ad10737c",
        "server": "3002",
        "farm": 9,
        "photos": 350,
        "videos": "0",
        "title": {
          "_content": "20120722 Iceland - LungA"
        },
        "description": {
          "_content": "flickr-store"
        },
        "needs_interstitial": 0,
        "visibility_can_see_set": 1,
        "count_views": "0",
        "count_comments": "0",
        "can_comment": 1,
        "date_create": "1343834092",
        "date_update": "1356226917"
      },
      ...
    ]
  },
  "stat": "ok"
}

flickr.photosets.getPhotos

{
  "photoset": {
    "id": "72152618960573004",
    "primary": "7579195483",
    "owner": "37268935@N00",
    "ownername": "audiere",
    "photo": [
      {
        "id": "10459686838",
        "secret": "361b191662",
        "server": "3874",
        "farm": 9,
        "title": "VB3O9913.JPG",
        "isprimary": "0",
        "ispublic": 0,
        "isfriend": 0,
        "isfamily": 0
      },
      ...
    ],
    "page": 1,
    "per_page": 500,
    "perpage": 500,
    "pages": 3,
    "total": "817",
    "title": "Out on the Farm"
  },
  "stat": "ok"
}

flickr.photos.search ? text=qwirkle

{
  "photos": {
    "page": 1,
    "pages": 4,
    "perpage": 100,
    "total": "339",
    "photo": [
      {
        "id": "31493633025",
        "owner": "21339686@N00",
        "secret": "62a3a7a100",
        "server": "8296",
        "farm": 9,
        "title": "Playing Qwirkle With The Grandparents",
        "ispublic": 1,
        "isfriend": 0,
        "isfamily": 0
      },
      ...
    ]
  },
  "stat": "ok"
}

flickr.test.login

{
  "user": {
    "id": "31408401@N00",
    "username": {
      "_content": "jamesonlawbaird"
    }
  },
  "stat": "ok"
}

upload

The upload and replace API methods are anomalous; they return XML regardless of the requested format. See below for further discussion.

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<photoid>16434286333</photoid>
</rsp>

Uploading files

Uploading new photos onto Flickr is not trivial, since OAuth usually incorporates all fields when signing a request, but Flickr API “upload” and “replace” actions specifically require the photo field to be excluded from the signature.

From the Flickr API documentation:

For details of how to obtain authentication tokens and how to sign calls, see the authentication api spec. Note that the ‘photo’ parameter should not be included in the signature. All other POST parameters should be included when generating the signature.

Uploading Photos

POST https://up.flickr.com/services/upload/

field description  
photo The file to upload.  
title The title of the photo. optional
description A description of the photo. May contain some limited HTML. optional
tags A space-separated list of tags to apply to the photo. optional
is_public Set to 0 for no, 1 for yes. Specifies who can view the photo. optional
is_friend Set to 0 for no, 1 for yes. Specifies who can view the photo. optional
is_family Set to 0 for no, 1 for yes. Specifies who can view the photo. optional
safety_level Set to 1 for Safe, 2 for Moderate, or 3 for Restricted. optional
content_type Set to 1 for Photo, 2 for Screenshot, or 3 for Other. optional
hidden Set to 1 to keep the photo in global search results, 2 to hide from public searches. optional

Replacing Photos

POST https://up.flickr.com/services/replace/

field description  
photo The file to upload.  
photo_id The ID of the photo to replace.  
async Photos may be replaced in async mode, for applications that don’t want to wait around for an upload to complete, leaving a socket connection open the whole time. Processing photos asynchronously is recommended. Please consult the documentation for details. optional