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

• method: string (required). The method you wish to invoke.
• api_key: string (required). Your OAuth API key.
• format: string (optional). The desired response format.

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/

Replacing Photos

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