Developer Network Home - Help

Using JSON with Yahoo! Web Services

Using JSON (JavaScript Object Notation) with Yahoo! Web Services

JSON (JavaScript Object Notation) is a lightweight data format based on the object notation of the JavaScript language. It does not require JavaScript to read or write; it is easy to parse by any language and libraries and tools exist in many languages to handle JSON.

For a complete description of JSON and its many uses, we suggest a visit to Douglas Crockford's JSON.org, with a side trip to JSON: The Fat-Free Alternative to XML, on the same server.

Many of the Yahoo! Web Services provide JSON as an alternate output format to XML. This page describes The Yahoo! Web Services JSON output, and how to use it in your own programs. It contains these sections:

JSON Format Overview

JSON is a very simple text format based on JavaScript's object notation. The notation contains these basic elements:

A simple example of JSON output looks like this:

{
  "Image": {
    "Width":800,
    "Height":600,
    "Title":"View from 15th Floor",
    "Thumbnail":
    {
      "Url":"http:\/\/scd.mm-b1.yimg.com\/image\/481989943",
      "Height": 125,
      "Width": "100"
    },
  "IDs":[ 116, 943, 234, 38793 ]
  }
}

In this example, Image is a top-level object; all other data is a member of that object. Width, Height and Title are all simple members containing number and string data. Thumbnail is a nested object, containing members for URL, Height and Width. IDs is an array, containing number values. Note the string value for URL, in which the slashes are escaped ("\/").

How To Request JSON Output

Many Yahoo! Web Services that support JSON use common parameters for generating and working with JSON output.

Using output=json:

By default the Yahoo! Web Services return output in XML format. To get output in JSON format, use the output=json parameter in the request:

http://search.yahooapis.com/ImageSearchService/V1/imageSearch?appid=YahooDemo&query=Madonna&output=json

Using callback=function:

The callback parameter (callback=function) wraps the JSON output text in parentheses and a function name of your choosing. For example:

http://search.yahooapis.com/ImageSearchService/V1/imageSearch?appid=YahooDemo&query=Madonna&output=json&callback=ws_results

Callback function names may only use upper and lowercase alphabetic characters (A-Z, a-z), numbers (0-9), the period (.), the underscore (_), and brackets ([ and ]). Brackets must be URL-encoded; see note below.

Results wrapped in callbacks look like this:

ws_results( ...json output... );

Because JSON output is native JavaScript, you do not have to parse or evaluate the returned object in your callback function. You can immediately access the elements inside it, just as if you had passed an object reference to your ws_result function.

In addition to a simple function name, callbacks can also use JavaScript object or array references, like this:

callback=ws_results.obj

... or this:

callback=ws_results.obj.array[4]

Important: brackets requested in callbacks must be URL encoded, like this:

http://search.yahooapis.com/ImageSearchService/V1/imageSearch?appid=YahooDemo&query=Madonna&output=json&callback=ws_results.obj.array%5B4%5D

Callbacks are particularly useful for use with web service requests in client-side JavaScript. Normally web service requests using the XMLHttpRequest object run afoul of browser security restrictions that prevent files from being loaded across domains. This restriction requires you to proxy your requests on the server side or use server rewrites to trick the browser into thinking the web service data is coming from the same site as your web content.

Using JSON and callbacks, you can place the Yahoo! Web Service request inside a <script> tag, and operate on the results with a function elsewhere in the JavaScript code on the page. Using this mechanism, the JSON output from the Yahoo! Web Services request is loaded when the enclosing web page is loaded. No proxy or server trickery is required.

Here's a very simple working example.

<html>
<head>
<title>How Many Pictures Of Madonna Do We Have?</title>
</head>
</body>
<script type="text/javascript">
function ws_results(obj) {
	alert(obj.ResultSet.totalResultsAvailable);
}
</script>
<script type="text/javascript" src="http://search.yahooapis.com/ImageSearchService/V1/imageSearch?appid=YahooDemo&query=Madonna&output=json&callback=ws_results"></script>
<body></body>
</html>

Save this to your desktop as madonna.html, drag it into your browser, and boggle at the results. (Does the world really need 631,000 pictures of the Material Girl? The mind reels....)

Using JSON in your Script or Application

JSON output text can be directly compiled by JavaScript, using eval():

var myObj = eval( '(' + jsontext + ')' );

Note that eval will compile everything in the JSON text with no security or sanity checking. Although the JSON provided by the Yahoo! Web Services will not contain hostile code you may be more comfortable with a JSON parser which simply checks the JSON text for structure without executing any of the code. An open-source JSON parser is available at crockford.com (json.org).

Some Security Concerns

Although the Yahoo! Web services contain only data and no JavaScript code, the dynamic script tag mechanism does expose your DOM to Yahoo!. If you have security concerns about the content of the JSON output from the Yahoo! Web Services and this DOM exposure, do not use a dynamic script tag -- use XMLHttpRequest and parse the JSON output by hand, or use XML output instead.

If you're interested in reading about a proposed alternative to using dynamic script tags, please go take a look at Douglas Crockford's JSONRequest page.

JSON versus XML

Both the XML and JSON output from the Yahoo! Web Services contain the same data; the only difference is in the format. The documentation on the Yahoo! Developer Network assumes XML output. Depending on the specific service you are using, there may be variations in how the XML output from the service maps onto the JSON notation, but in general you can assume these rules:

These two examples show equivalent data output in XML and JSON output.

XML:

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:yahoo:srchmi" xsi:schemaLocation="urn:yahoo:srchmi http://search.yahooapis.com/ImageSearchService/V1/ImageSearchResponse.xsd" totalResultsAvailable="229307" totalResultsReturned="2" firstResultPosition="1"><Result>
  <Title>madonna 116</Title>
  <Summary>Picture 116 of 184</Summary>
  <Url>http://www.celebritypicturesarchive.com/pictures/m/madonna/madonna-116.jpg</Url>
  <ClickUrl>http://www.celebritypicturesarchive.com/pictures/m/madonna/madonna-116.jpg</ClickUrl>
  <RefererUrl>http://www.celebritypicturesarchive.com/pgs/m/Madonna/Madonna%20picture_116.htm</RefererUrl>
  <FileSize>36990</FileSize>
  <FileFormat>jpeg</FileFormat>
  <Height>530</Height>
  <Width>425</Width>
  <Thumbnail>
    <Url>http://scd.mm-b1.yimg.com/image/481989943</Url>
    <Height>125</Height>
    <Width>100</Width>
  </Thumbnail>
</Result>
<Result>
  <Title>madonna 118</Title>
  <Summary>Picture 118 of 184</Summary>
  <Url>http://www.celebritypicturesarchive.com/pictures/m/madonna/madonna-118.jpg</Url>
  <ClickUrl>http://www.celebritypicturesarchive.com/pictures/m/madonna/madonna-118.jpg</ClickUrl>
  <RefererUrl>http://www.celebritypicturesarchive.com/pgs/m/Madonna/Madonna%20picture_118.htm</RefererUrl>
  <FileSize>40209</FileSize>
  <FileFormat>jpeg</FileFormat>
  <Height>700</Height>
  <Width>473</Width>
  <Thumbnail>
    <Url>http://scd.mm-b1.yimg.com/image/500892420</Url>
    <Height>130</Height>
    <Width>87</Width>
  </Thumbnail>
</Result>
</ResultSet>

JSON:

{"ResultSet":{
  "totalResultsAvailable":"229307",
  "totalResultsReturned":"2",
  "firstResultPosition":"1",
  "Result":[
    {
      "Title":"madonna 116",
      "Summary":"Picture 116 of 184",
      "Url":"http:\/\/www.celebritypicturesarchive.com\/pictures\/m\/madonna\/madonna-116.jpg",
      "ClickUrl":"http:\/\/www.celebritypicturesarchive.com\/pictures\/m\/madonna\/madonna-116.jpg",
      "RefererUrl":"http:\/\/www.celebritypicturesarchive.com\/pgs\/m\/Madonna\/Madonna%20picture_116.htm",
      "FileSize":"36990",
      "FileFormat":"jpeg",
      "Height":"530",
      "Width":"425",
      "Thumbnail":{
        "Url":"http:\/\/scd.mm-b1.yimg.com\/image\/481989943",
        "Height":"125",
        "Width":"100"
       }
    },
    {
      "Title":"madonna 118",
      "Summary":"Picture 118 of 184",
      "Url":"http:\/\/www.celebritypicturesarchive.com\/pictures\/m\/madonna\/madonna-118.jpg",
      "ClickUrl":"http:\/\/www.celebritypicturesarchive.com\/pictures\/m\/madonna\/madonna-118.jpg",
      "RefererUrl":"http:\/\/www.celebritypicturesarchive.com\/pgs\/m\/Madonna\/Madonna%20picture_118.htm",
      "FileSize":"40209",
      "FileFormat":"jpeg",
      "Height":"700",
      "Width":"473",
      "Thumbnail":{
        "Url":"http:\/\/scd.mm-b1.yimg.com\/image\/500892420",
        "Height":"130",
        "Width":"87"
      }
    }
  ]
}
}

Copyright © 2007 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings