Flickr API ドキュメント日本語訳

JSON Response Format

JSON, or JavaScript Object Notation, is a simple machine-readable data-interchange format, which makes constructing API applications in JavaScript easy (though it can be used from other languages too!). For more information about JSON, visit json.org.

To return an API response in JSON format, send a parameter "format" in the request with a value of "json".

Object Representation

Some simple rules are used when converting flickr REST XML into JSON objects. Some examples illustrate this best. A single tag will be translated to JSON as follows:

<foo bar="baz" />

{
	"foo": {
		"bar": "baz"
	}
}

Each element is represented by a JSON object. Element attributes are represented by an object member with a string value. Child elements are represented by an object member with an object value:

<foo bar="baz">
	<woo yay="hoopla" />
</foo>

{
	"foo": {
		"bar": "baz",
		"woo": {
			"yay": "hoopla"
		}
	}
}

Element text nodes are represented as if they were an attribute, using the special name "_content":

<foo>text here!</foo>

{
	"foo": {
		"_content": "text here!"
	}
}

For repeated elements (such as the <photo> element when fetching a list of photos), an array is used as the object member value (the member key represents the element name). Each value in the array is then an object representing a child element.

<outer>
	<photo id="1" />
	<photo id="2" />
</outer>

{
	"outer": {
		"photo": [
			{
				"id": "1"
			},
			{
				"id": "2"
			}
		]
	}
}

Successful Responses

When a request is successful, the following JSON is returned:

jsonFlickrApi({...});

The single object passed in the function call represents the REST outer <rsp> element. The root element of the REST response is then a member of this object (the stat param also is - check this to see if the call was successful). For instance, flickr.blogs.getList has a documented response as follows:

<blogs>
	<blog id="73" name="Bloxus test" needspassword="0"
		url="http://remote.bloxus.com/" /> 
	<blog id="74" name="Manila Test" needspassword="1"
		url="http://flickrtest1.userland.com/" /> 
</blogs>

And the Flickr JSON equivilent would be:

jsonFlickrApi({
	"stat": "ok",
	"blogs": {
		"blog": [
			{
				"id"		: "73",
				"name"		: "Bloxus test",
				"needspassword"	: "0",
				"url"		: "http://remote.bloxus.com/"
			},
			{
				"id"		: "74",
				"name"		: "Manila Test",
				"needspassword"	: "1",
				"url"		: "http://flickrtest1.userland.com/"
			}
		]
	}
})

In JavaScript, displaying a list of a user's blogs is then straight forward:

function jsonFlickrApi(rsp){

	if (rsp.stat != "ok"){

		// something broke!
		return;
	}

	for (var i=0; i<rsp.blogs.blog.length; i++){

		var blog = rsp.blogs.blog[i];

		var div = document.createElement('div');
		var txt = document.createTextNode(blog.name);

		div.appendChild(txt);
		document.body.appendChild(div);
	}
}

Failure Responses

Failure responses also call the jsonFlickrApi() method, but with a different JSON object. The object is not structured like the REST failure responses - instead it's simplified for JSON. For example:

jsonFlickrApi({
	"stat"		: "fail",
	"code"		: "97",
	"message"	: "Missing signature"
})

From JavaScript, you can check rsp.stat for failure, and then read the error from rsp.code and rsp.message.

Callback Function

If you just want the raw JSON, with no function wrapper, add the parameter nojsoncallback with a value of 1 to your request.

To define your own callback function name, add the parameter jsoncallback with your desired name as the value.

nojsoncallback=1	-> {...}
jsoncallback=wooYay	-> wooYay({...});

Examples

You can see a successful json response here.

You can see a json failure response here.