The Google Finance Portfolio Data API allows client applications to view and update Finance portfolio content in the form of Google Data API feeds.
Your client application can use the Finance Data API to create new portfolio and transaction entries, request a list of entries, and edit or delete existing entries.
In addition to providing some background on the capabilities of the Finance Data API, this document provides examples of basic Data API interactions using the JavaScript client library. If you're interested in understanding more about the underlying protocol that the library uses, see the Protocol section of this developer's guide.
This document is intended for programmers who want to write JavaScript client applications that can interact with Google Finance Portfolios. It provides a series of examples of basic Data API interactions using the JavaScript client library.
For Google Finance Portfolio Data API reference information, see the Protocol reference guide. This document assumes that you understand the general ideas behind the Google Data APIs protocol and the data model and control flow used by the JavaScript client library. It also assumes that you know how to program in JavaScript.
For reference information about the classes and methods provided by the client library, see the JavaScript client library API reference.
This document is designed to be read in order; each example builds on earlier examples.
You agree to abide by the Google JavaScript Client Library Terms of Use when using the JavaScript client library.
Before you can write a JavaScript client application, you need to do some setup, including obtaining a Data API key and acquiring the library.
You may want to sign up for a Finance account for testing purposes. Finance uses Google Accounts, so if you already have a Google account, you're all set.
Currently, we only support JavaScript client applications that run in a web page in a browser. Currently supported browsers are Firefox 1.5 and higher, and Internet Explorer 6.0 and higher.
The JavaScript client library handles all communication with the service's server. If you're an experienced JS developer, you may be thinking, "But what about the same origin policy?" The JavaScript client library allows your client to send Google Data API requests from any domain while remaining compliant with the browser security model.
To acquire the JavaScript client library, you need a developer key. To obtain one, go to the Google Data API key signup page, read the terms of service, and enter your website's URL. The signup page provides you with a key, which is an alphanumeric string that your client uses to identify itself to Google when the client requests the client library.
A key is associated with a website. If you want to use the JavaScript client library on another site, you should obtain another key for that site. More specifically, a key is associated with the URL that you enter on the signup page; the key applies to all URLs under the domain or directory that you specify.
Note: The Google Data API key for a given domain is the same as the Google Maps API key for that domain. If you already have a Google Maps API key for your domain, you can use that key rather than going through the Data API key signup page.
Before your client can use the client library, the client has to request the client library code from the server.
Start by using a <script> tag in the <head> section of your HTML document to fetch the Google AJAX API loader:
<script type="text/javascript" src="http://www.google.com/jsapi?key=developer_key"> </script>
Where developer_key is the key you obtained from the signup page.
To acquire the Google Data API client library after fetching the loader, use the following line in your JavaScript setup code, which must be called from the <head> section of your HTML document (or from a JavaScript file that's included using a <script> tag in the <head> section of your HTML document):
|
google.load("gdata", "1.x");
The second parameter to google.load() is the requested version number of the JavaScript client library. Our version numbering scheme is modeled after the one used by the Google Maps API. Here are the possible version numbers and what they mean:
"1""1.x""1.s""1.0", "1.1", etcAfter you've called google.load(), you have to tell the loader to wait until the page finishes loading and then call your code:
google.setOnLoadCallback(getMyFinancePortfolioFeed);
Where getMyFinancePortfolioFeed() is a function that you'll define yourself -- see the interactive tutorial section of this document for an introduction to writing such a function. Use this approach instead of having an onload handler attached to the <body> element.
The JavaScript client library uses a set of classes to represent the elements used by the Google data APIs.
Note: The underlying representation of the data is JSON, but the client library provides an abstraction layer so you don't have to work with the JSON data directly. If you want to work directly with JSON, without the client library, see Using JSON with Google Data APIs.
The library provides methods that let you asynchronously send data to and
receive data from a service that has a data API. For example, the
google.gdata.finance.FinanceService.getPortfolioFeed() method
sends a request for a feed to Google Finance Portfolios. One of the parameters you
pass is a continuation function, also known as a callback; the service
returns the feed, in JSON format, by calling the continuation function.
Within the callback function you call various get methods to use the data in the form of JavaScript objects.
To add a new entry, you create the entry using the client library's classes and methods, then call the feed.insertEntry() method to send the new entry to the service. Again you provide a continuation function, which the service calls when the entry has been successfully added. This is all illustrated in the interactive tutorial section of this document.
If you're new to JavaScript, the control flow may be a little confusing. After calling a method like getEventsFeed() or insertEntry(), in most cases your script ends. Execution resumes in the continuation function when the service returns the requested data. Therefore, anything that your client does to the returned data should be done in the continuation function, or called from that function. You may need to make some variables global in order to use them in multiple functions.
For more information about this style of programming, see "Continuation-passing style" in Wikipedia.
A client must authenticate before using the Finance Data API. The JavaScript client library uses the AuthSub authentication system. For more information about authentication with Google Data APIs in general, see the authentication documentation.
AuthSub proxy authentication is used by web applications that need to authenticate their users to Google Accounts. The website operator and the client code don't have access to the username and password for the Google Finance user; instead, the client obtains special AuthSub tokens that allow the client to act on a particular user's behalf.
Here's a brief overview of what happens during the authentication process for a web-based JavaScript client:
google.accounts.user.login() method provided by the client library, passing it a "scope" value that indicates which Google service to use. For Google Finance, the scope is "http://finance.google.com/finance/feeds/".google.accounts.user.login().Note: For the JavaScript client library to make authenticated Google Finance requests in a web browser, your page must contain an image that's hosted at the same domain as your page. It can be any image, even a single-pixel transparent image, but there must be an image on the page. If you do not want the image to appear on your page, you can use the style attribute of the <img> tag to position the image outside the rendering area. For example: style="position:absolute; top: -1000px;"
Here's the client-application code that handles logging in. We'll call the setupMyService() function from other code later.
function logMeIn() {
scope = "http://finance.google.com/finance/feeds/";
var token = google.accounts.user.login(scope);
}
function setupMyService() {
var myService =
new google.gdata.finance.FinanceService('exampleCo-exampleApp-1');
logMeIn();
return myService;
}
Tip: We strongly recommend that you provide a login button or other user input mechanism to prompt the user to start the login process manually. If, instead, you call google.accounts.user.login() immediately after loading, without waiting for user interaction, then the first thing the user sees on arrival at your page is a Google login page. If the user decides not to log in, then Google does not direct them back to your page; so from the user's point of view, they tried to visit your page but were sent away and never sent back. This scenario may be confusing and frustrating to users. In the example code in this document, we'll be calling google.accounts.user.login() immediately after loading, to keep the example simple, but we don't recommend this approach for real-world client applications.
Note that you don't have to do anything with the variable named token; the client library keeps track of the token, so you don't have to.
Note: When you create a new FinanceService object, the client library calls a method named google.gdata.client.init(), which checks that the browser the client is running in is supported, and validates the developer key. If there's an error, then the client library displays an error message to the user. If you want to handle this sort of error yourself, then you can explicitly call google.gdata.client.init(handleInitError) before you create the service, where handleInitError() is your function. If an init error occurs, then your function receives a standard Error object; you can do whatever you want with that object.
The token remains valid until you revoke it by calling google.accounts.user.logout():
function logMeOut() {
google.accounts.user.logout();
}
If you don't call logout(), then the cookie that stores the token lasts for two years, unless the user deletes it. The cookie is retained across browser sessions, so the user can close their browser and then reopen it and come back to your client and they'll still be logged in.
However, there are certain unusual circumstances in which a token can become invalid during a session. If Google Finance rejects a token, your client should handle the error condition by calling logout() to remove the cookie containing the current token, and then calling login() again to acquire a new, valid token.
There are two other AuthSub methods that you may find useful in various contexts:
google.accounts.user.checkLogin(scope) tells you whether or not the browser currently has an authentication token for the given scope.google.accounts.user.getInfo() provides detailed information about the current token, for debugging use.For details about using JavaScript to interact with AuthSub, including information on token management and on checkLogin() and getInfo(), see the Using "AuthSub" Authentication with the JavaScript Client Library document.