Financial Gadgets

Google Finance provides an easy-to-use Market Data API for gadgets that developers can use to retrieve and display stock market information in gadgets. This document describes how to get information from Google Finance for gadgets you create.

Contents

Introduction

To use the Finance Market Data API, your gadget spec must include the following:

• Under <ModulePrefs>, a <Require feature="finance"/> tag to tell the gadget to load the finance library.
• JavaScript functions, HTML IDs, and objects that let your gadget manipulate financial data. See the reference for a complete list of the functions in the finance library.

Gadgets that use the Market Data API can only run in iGoogle--either production iGoogle, or the iGoogle sandbox. However, they must be based on the legacy gadgets API, and not use gadgets.* or OpenSocial.

Want to get started right away? Let's jump right in with a quick example that shows you how to display stock quotes in a gadget.

Simple Example

To display stock quotes in your gadget:

1. Create a named span tag as a placeholder for each stock quote that you want to display.
2. Create a new google.finance.Quote object.
3. Call enableDomUpdates to associate each span tag from step 1 with a stock symbol.
4. Call getQuotes for each symbol, and that's it!

This example displays quotes from 3 stocks:

Hello world!
Here is your portfolio:<br/>
  GOOG: <span id=_IG_SYM1_l></span> (<span id=_IG_SYM1_c></span>)<br/>
  AAPL: <span id=_IG_SYM2_l></span> (<span id=_IG_SYM2_c></span>)<br/>
  INTC: <span id=_IG_SYM3_l></span> (<span id=_IG_SYM3_c></span>)<br/>

  
<script type="text/javascript">
  var quote = new google.finance.Quote();
  quote.enableDomUpdates( { 'GOOG' : '_IG_SYM1', 'AAPL' : '_IG_SYM2', 
    'INTC' : '_IG_SYM3' } );

  quote.getQuotes(["GOOG", "AAPL", "INTC"]);
</script>

This code produces output that looks like this:

Hello world! Here is your portfolio:
GOOG: 631.58 (+15.58)
AAPL: 171.46 (+1.88)
INTC: 26.65 (+1.17)

Note that this gadget displays two quotes for each stock: the current price, and the day's change. The gadget specifies these values by using a suffix on the span tag IDs. For example, the span ID _IG_SYM1_l includes the _l suffix, which tells Google Finance to return the last price traded of the stock. Similarly, the ID _IG_SYM1_c ends with the _c suffix, which returns the stock's change since close. The Span IDs section includes a table that lists all the suffixes you can use.

Here is the complete gadget spec for the example:

<?xml version="1.0" encoding="UTF-8" ?>
    
<Module>
  <ModulePrefs title="hellofinance">
    <Require feature="finance"/>
  </ModulePrefs>
  <Content type="html">
  <![CDATA[

Hello world!
Here is your portfolio:<br/>
  GOOG: <span id=_IG_SYM1_l></span> (<span id=_IG_SYM1_c></span>)<br/>
  AAPL: <span id=_IG_SYM2_l></span> (<span id=_IG_SYM2_c></span>)<br/>
  INTC: <span id=_IG_SYM3_l></span> (<span id=_IG_SYM3_c></span>)<br/>

  
<script>
  var quote = new google.finance.Quote();
  quote.enableDomUpdates( { 'GOOG' : '_IG_SYM1', 'AAPL' : '_IG_SYM2', 
    'INTC' : '_IG_SYM3' } );

  quote.getQuotes(["GOOG", "AAPL", "INTC"]);
</script>
  ]]>

  </Content>
</Module>

JavaScript API

The Market Data API includes the following JavaScript functions:

All these functions are defined by the quote object you create. So, for example, you call getQuotes by writing quote.getQuotes.

Beyond the Basics

In the previous section, you got a taste of the Google Market Data API for Gadgets as we built our Hello World gadget. This section describes how to use more advanced features:

• Displaying Stock Quote Data describes how to use named span tags to specify locations in your gadget's HTML, then call enableDomUpdates and getQuotes to insert quotes directly into your HTML. The Hello World example illustrates this technique.
• Accessing Data Directly describes how you can have more fine-grained control over how stock quote data gets displayed in your gadget.

Displaying Stock Quote Data

This section describes the easiest way to display stock quote data in your gadget: include span ID tags in your HTML, then call getQuotes to insert quotes automatically. To use this approach, you can call either form of getQuotes:

• getQuotes(symbol) to retrieve and insert quotes for one symbol.
• getQuotes(array of symbols) to retrieve and insert quotes for more than one symbol.

In addition to inserting quotes into your HTML, when you call getQuotes, any listener functions you have previously specified will be called. See Accessing Data Directly for more information.

getQuotes: heart of the API

The getQuotes function provides most of the power behind the Market Data API. You call getQuotes whenever you want to ask Google Finance for a stock price. You can call getQuotes with one stock symbol, or an array of stock symbols. If you have created span tags in your HTML and associated them with stock symbols, getQuotes will insert the quotes into the span tags. In addition, when you call getQuotes, your listener functions will be called.

Span IDs

To include stock quotes from Google Finance in your gadgets, you create a named span tag where you want the stock quote to appear, as in the following example HTML snippet:

Change since close: <span id=_IG_SYM1_c></span>

You can use any name you want for the first part of your span ID; you don't have to use _IG_SYM1 as our example does. You'll use the enableDomUpdates and getQuotes functions to insert quotes into the span.

The span ID should be suffixed with a code that tells Google Finance which quote to retrieve: latest trade, change since close, and so on. The above example includes the _c suffix, which will retrieve the change since close. The part of the tag before the suffix is called the span ID prefix. In this case, the span ID prefix is _IG_SYM1.

The following table shows the suffix codes that can be used with span ID:

So, for example, to create a placeholder for the intraday high value for a stock, you would use HTML like this, with the _hi suffix:

<span id=_IG_SYM1_hi></span>

When you call enableDomUpdates, you specify which stock symbol should be used with each span tag. When you call getQuotes, you specify the stock symbol you want quotes for.

Accessing Data Directly

Displaying Stock Quote Data describes how to retrieves stock quotes and place them in your HTML, inside span tags. This section describes how access stock quote data directly, which lets you have more fine-grained control over how and where stock quotes appear in your gadgets.

To take this approach, you can call either form of getQuotes, and then use addListener to specify a function (or functions) that will be called whenever your gadget calls getQuotes(). You can then directly access the quote data through the google.finance object using the following values:

So, for example, you can access the stock's opening price by writing google.finance.OPEN.

Example

The following example specifies a listener function that displays lots of information in JavaScript alert boxes, then gets quotes for two stock symbols (which then calls the listener function):

<?xml version="1.0" encoding="UTF-8" ?>
    <Module>
  <ModulePrefs title="hellofinance">
    <Require feature="finance"/>
  </ModulePrefs>
  <Content type="html">
  <![CDATA[
   
  <script type="text/javascript">
  var quote = new google.finance.Quote();
  quote.getQuotes(["GOOG","INTC"]);
  quote.addListener(function(data) {
    alert("Last: " + data[google.finance.LAST]);
    alert("Symbol: " + data[google.finance.SYMBOL]);
    alert("Change: " + data[google.finance.CHANGE]);
    alert("Change Pct: " + data[google.finance.CHANGE_PCT]);
    alert("Open: " + data[google.finance.OPEN]);
    alert("High: " + data[google.finance.HIGH]);
    alert("Low: " + data[google.finance.LOW]);
    alert("Exchange: " + data[google.finance.EXCHANGE]);
    alert("Time: " + data[google.finance.LAST_TRADE_TIME]);
    });
    
    </script>
  ]]>
  </Content>
  </Module>

Back to top