Google Finance APIs and Tools (Labs)

Google Finance Portfolio Data API
- Developer's Guide
  - Java
  - JavaScript ^New!
- Reference Guide
Finance Tools
- Finance gadgets
Google Data APIs

Reference Guide

This document provides detailed reference documentation for the raw protocol (XML and HTTP) for the Google Finance Portfolio Data API.

This document doesn't contain information about the programming-language client libraries. For client-library reference information, see the links from the programming-language-specific sections of the developer's guide.

Audience
Finance feed types
Finance query parameters reference
Finance elements reference

Audience

This document is intended for programmers who want to write client applications that can interact with Google Finance.

It's a reference document; it assumes that you understand the concepts presented in the developer's guide, and the general ideas behind the Google Data APIs protocol.

Finance feed types

The Finance Data API provides a hierarchical set of three feed types:

Portfolio feed: Lists all of the user's portfolios.
Position feed: Lists all of the positions in a particular portfolio.
Transaction feed: Lists all of the transactions that have been recorded for a particular position.

Note that this API interacts only with users' portfolio data; the Finance Portfolio Data API doesn't provide access to stock quotes or other real-world financial data hosted by Google Finance.

Portfolio feed

A portfolio is a collection of positions that the user holds in various securities, plus metadata.

The portfolio feed lists all of the user's portfolios. Each portfolio entry contains the portfolio's title along with data such as currency, total market value, and overall performance statistics.

For example, a user, Liz (liz@gmail.com), might have two portfolios: a technology portfolio and energy portfolio. After her credentials are authenticated, Liz can retrieve her portfolio feed from the following URL:

http://finance.google.com/finance/feeds/default/portfolios

This feed contains two entries: one for her technology portfolio and one for her energy portfolio. Liz can also directly retrieve the entry for one of her portfolios by appending the portfolio number to the request URL. For example, she could retrieve the entry for her first portfolio using the following URL:

http://finance.google.com/finance/feeds/default/portfolios/1

Each portfolio entry also contains a link to the portfolio's position feed.

Position feed

A position is a collection of information about a security that the user holds.

A position feed lists all of the positions in a particular portfolio. Each position entry contains the ticker exchange and symbol for a stock, mutual fund, or other security, along with the number of units of that security that the user holds, and other relevant data, such as performance statistics.

For example, Liz can retrieve the position feed for her technology portfolio from the following URL:

http://finance.google.com/finance/feeds/default/portfolios/1/positions

The returned feed contains a list of the holdings and watchlist items in the portfolio. This list might contain entries for NASDAQ:GOOG, NASDAQ:AAPL, NYSE:IBM, and other items that Liz has added to her Google Finance technology portfolio.

Note: Positions are identified by their "ticker," which consists of an exchange (such as NYSE) and a symbol (such as GE).

Liz can retrieve a specific position entry by appending the entry's ticker to the feed URL:

http://finance.google.com/finance/feeds/default/portfolios/1/positions/NASDAQ:GOOG

Each position entry also contains a link to the position's transaction feed.

Transaction feed

A transaction is a collection of information about an instance of buying or selling a particular security.

A transaction feed lists all of the transactions that have been recorded for a particular position. Each transaction entry contains a transaction type (Buy, Sell, Sell Short, or Buy to Cover), a number of units, the price, any commission, and any notes.

For example, Liz can retrieve her transaction feed for NASDAQ:GOOG from the following URL:

http://finance.google.com/finance/feeds/default/portfolios/1/positions/NASDAQ:GOOG/transactions

This feed lists each transaction that affects Liz's NASDAQ:GOOG position.

Each transaction is identified by transaction ID number, and the entry corresponding to a particular transaction can be retrieved individually:

http://finance.google.com/finance/feeds/default/portfolios/1/positions/NASDAQ:GOOG/transactions/1

Finance query parameters reference

Google Finance supports the standard alt query parameter. Google Finance does not currently support any other Google Data API query parameters, such as full-text search.

For more information about the alt parameter, see the Google Data APIs protocol reference document.

The Finance Data API also supports the following Finance-specific boolean parameters. For each of these parameters, the possible values are true and false; the default value is false.

These query parameters apply only to requests for feeds, not to requests for individual entries.

Parameter	Meaning	Notes
`returns`	Specify `returns=true` to request that information about total financial returns and performance statistics be included in the feed entries.	Supported only in portfolio and position feeds.
`positions`	Specify `positions=true` to request that the position feed for each portfolio entry be embedded as an inline feed, contained in the feed link element.	Supported only in portfolio feeds. If the `returns` parameter is also set, returns data is included in the inlined feed as well.
`transactions`	Specify `transactions=true` to request that the transaction feed for each position entry be embedded as an inline feed, contained in the feed link element.	Supported only in position feeds.

For example, imagine that Liz queries the following URL:

http://finance.google.com/finance/feeds/default/portfolios/1/positions?returns=true&transactions=true

The server returns the position feed for Liz's technology portfolio. The entries in the feed include financial returns and perfomance statistics for each position. Inside each entry, the feed link element contains both a link to the transaction feed for the position, and the transaction feed itself.

Inlining a position or transaction feed can be useful; it allows a user to retrieve more information in a single query.

About returns

Returns are disabled by default because the server takes longer to provide a feed that includes performance statistics.

Excluding returns also allows for the feed's <updated> element to indicate when the portfolio has lasted been edited by the user (rather than last updated with performance statistics), which allows an automated feed reader to cache query results on portfolios that do not change frequently.

If returns are included, they're provided for the following periods:

One week
Four weeks
Year-to-date
One year
Three years
Five years
Overall

Along with returns, several financial-performance statistics are included:

Cost Basis
Day's Gain
Total Gain
Market Value

Finance elements reference

The Finance Data API uses several standard Atom and Google data elements, such as <atom:id>, <atom:title>, <atom:category>, and <gd:feedLink>. For information about these standard elements, see the Atom specification and the Kinds document.

In addition to the standard elements, the Finance Data API uses the elements described in this section.

The elements specific to the Google Finance Portfolio Data API are defined in a "gf" namespace. This section also includes reference information about the <gd:money> element.

Note: In the tables that follow, a prefix of @ on a property indicates that it is an attribute; a prefix of gf: indicates that it is a child Finance element. A suffix of ? indicates the property is optional, while a suffix of + indicates that at least one such element is required; otherwise, exactly one is required.

In all elements and attributes that refer to percentages, percentage values are expressed as decimal fractions. For example, a percentage value of "1.89" means 189%.

Note: If the date of last edit to a portfolio, position, or transaction is unknown, the item's <updated> element is set to a default date of January 1, 2007.

gd:money

An amount of money in a particular currency.

The <gd:money> element can appear as a child of a variety of other elements.

Properties

Property	Type	Description
`@amount`	`xsd:float`	Amount of money.
`@currencyCode`	`xsd:string`	ISO4217 currency code.

Example

<gd:money amount='650.0' currencyCode='EUR'/>

Schema

element gd:money {
  attribute amount { xsd:float },
  attribute currencyCode { xsd:string }
}

gf:portfolioData

Contains an overview of a portfolio, including currency, returns, and performance statistics.

The <gf:portfolioData> element can appear only as a child of a portfolio <entry>.

Note: Each portfolio has a currency associated with it, specified when the portfolio is created. This is the currency in which the portfolio's value and gain data are listed, but be aware that a portfolio can contain investments listed on foreign exchanges. Such investments have values and gains listed in both the portfolio's default currency and the exchange's default currency.

Properties

Property	Type	Description
`@currencyCode`	`xsd:string`	Default ISO4217 currency code for the portfolio.
`@gainPercentage`?	`xsd:double`	Percentage gain.
`@return1w`?	`xsd:double`	1 week return (percentage).
`@return4w`?	`xsd:double`	4 week return (percentage).
`@return3m`?	`xsd:double`	3 month return (percentage).
`@returnYTD`?	`xsd:double`	Year-to-date return (percentage).
`@return1y`?	`xsd:double`	1 year return (percentage).
`@return3y`?	`xsd:double`	3 year return (percentage).
`@return5y`?	`xsd:double`	5 year return (percentage).
`@returnOverall`?	`xsd:double`	Overall return (percentage).
`gf:costBasis`?	`costBasis`	Cost basis (in one or more currencies).
`gf:daysGain`?	`daysGain`	Total amount of today's gain for all current open positions (in one or more currencies).
`gf:gain`?	`gain`	Total amount of all-time gain for current open positions (in one or more currencies).
`gf:marketValue`?	`marketValue`	Current total market value (in one or more currencies).

Note that "return" takes all known transactions into account, while "gain" considers only current open positions. For example, if you purchased 100 shares of GOOG and then later sold 50 of them, "return" amounts for your GOOG position include the amount that you gained or lost on the shares you've now sold, while "gain" amounts include information only about the shares you currently hold.

Example

<gf:portfolioData currencyCode='USD' gainPercentage='1.894857932'
    return1w='-0.07711772724' return1y='0.3969560994' return3m='0.197468495'
    return3y='1.228892613' return4w='-0.003721445821' return5y='1.894857932'
    returnOverall='1.894857932' returnYTD='0.4172674026'>
  <gf:costBasis>
    <gd:money amount='52158.0' currencyCode='USD'/>
  </gf:costBasis>
  <gf:daysGain>
    <gd:money amount='7321.0' currencyCode='USD'/>
  </gf:daysGain>
  <gf:gain>
    <gd:money amount='98832.0' currencyCode='USD'/>
  </gf:gain>
  <gf:marketValue>
    <gd:money amount='150990.0' currencyCode='USD'/>
  </gf:marketValue>
</gf:portfolioData>

Schema

element gf:portfolioData {
  attribute currencyCode { xsd:string },
  attribute gainPercentage { xsd:float }?,
  attribute return1w { xsd:float }?,
  attribute return1y { xsd:float }?,
  attribute return3m { xsd:float }?,
  attribute return3y { xsd:float }?,
  attribute return4w { xsd:float }?,
  attribute return5y { xsd:float }?,
  attribute returnOverall { xsd:float }?,
  attribute returnYTD { xsd:float }?,
  ( costBasis? &
  daysGain? &
  gain? &
  marketValue? )
}

gf:positionData

Contains an overview of a position, including returns and performance statistics.

The <gf:positionData> element can appear only as a child of a position <entry>.

Note: Any given security is associated with a default currency; for example, the default currency for NASDAQ and NYSE stocks is USD, the default for securities on the Toronto Stock Exchange is CAD, and the default for the London Stock Exchange is GBP. Because the default currency for a security can't be changed, it doesn't appear in the <gf:positionData> element. If a security's default currency doesn't match the default for a portfolio that contains that security, then transactions on that security include information in both currencies.

Properties

Property	Type	Description
`@gainPercentage`?	`xsd:double`	Percentage gain.
`@return1w`?	`xsd:double`	1 week return (percentage).
`@return4w`?	`xsd:double`	4 week return (percentage).
`@return3m`?	`xsd:double`	3 month return (percentage).
`@returnYTD`?	`xsd:double`	Year-to-date return (percentage).
`@return1y`?	`xsd:double`	1 year return (percentage).
`@return3y`?	`xsd:double`	3 year return (percentage).
`@return5y`?	`xsd:double`	5 year return (percentage).
`@returnOverall`?	`xsd:double`	Overall return (percentage).
`@shares`?	`xsd:double`	Number of shares for the position (fractional shares are possible with mutual funds or reverse stock splits).
`gf:costBasis`?	`costBasis`	Cost basis (in one or more currencies).
`gf:daysGain`?	`daysGain`	Amount of today's gain for currently held shares (in one or more currencies).
`gf:gain`?	`gain`	Amount of all-time gain for currently held shares (in one or more currencies).
`gf:marketValue`?	`marketValue`	Market value (in one or more currencies).

Note that "return" takes all known transactions into account, while "gain" considers only currently held shares. For example, if you purchased 100 shares of GOOG and then later sold 50 of them, "return" amounts for your GOOG position include the amount that you gained or lost on the shares you've now sold, while "gain" amounts include information only about the shares you currently hold.

Example

<gf:positionData gainPercentage='4.31125' return1w='-0.08770799785'
    return1y='1.014937759' return3m='0.3299945223' return3y='4.31125'
    return4w='-0.01615050651' return5y='4.31125' returnOverall='4.31125'
    returnYTD='1.00330033' shares='1000.0'>
  <gf:costBasis>
    <gd:money amount='32000.0' currencyCode='USD'/>
  </gf:costBasis>
  <gf:daysGain>
    <gd:money amount='16200.0' currencyCode='USD'/>
  </gf:daysGain>
  <gf:gain>
    <gd:money amount='137960.0' currencyCode='USD'/>
  </gf:gain>
  <gf:marketValue>
    <gd:money amount='169960.0' currencyCode='USD'/>
  </gf:marketValue>
</gf:positionData>

Schema

element gf:positionData {
  attribute gainPercentage { xsd:float }?,
  attribute return1w { xsd:float }?,
  attribute return1y { xsd:float }?,
  attribute return3m { xsd:float }?,
  attribute return3y { xsd:float }?,
  attribute return4w { xsd:float }?,
  attribute return5y { xsd:float }?,
  attribute returnOverall { xsd:float }?,
  attribute returnYTD { xsd:float }?,
  attribute shares { xsd:float }?,
  ( costBasis? &
  daysGain? &
  gain? &
  marketValue? )
}

gf:transactionData

Contains an overview of a transaction, including the type (such as Buy or Sell), date, price, commission, and so on.

The <gf:transactionData> element can appear only as a child of a transaction <entry>.

Properties

Property	Type	Description
`@type`	`xsd:string`	Must be one of: `Buy` `Sell` `Buy to Cover` `Sell Short`
`@date`?	`xsd:date`	Date of transaction.
`@shares`?	`xsd:double`	Number of shares for the transaction (fractional shares are possible with mutual funds or reverse stock splits).
`@notes`?	`xsd:string`	Notes for the transaction.
`gf:commission`?	`commission`	Commission for the transaction.
`gf:price`?	`price`	Price per share for the transaction.

Example

<gf:transactionData date='2007-11-07T00:00:00.000' shares='1000.0' type='Buy'>
  <gf:commission>
    <gd:money amount='0.0' currencyCode='USD'/>
  </gf:commission>
  <gf:price>
    <gd:money amount='73.0' currencyCode='USD'/>
  </gf:price>
</gf:transactionData>

Schema

element gf:transactionData { attribute date { (
  xsd:date | xsd:dateTime) }?,
  attribute notes { xsd:string }?,
  attribute shares { xsd:float }?,
  attribute type { xsd:string },
  ( commission? &
  price? )
}

gf:commission

The monetary value of a commission on a transaction.

The <gf:commission> element can appear only as a child of <gf:positionData>.

Properties

Property	Type	Description
`gd:money`+	`money`	Monetary value for the data. The first money element is in the portfolio's default currency. When a security's default currency differs from the portfolio's, then a second money element is included using the security's default currency.

Example

<gf:commission>
  <gd:money amount='0.0' currencyCode='USD'/>
</gf:commission>

Schema

element gf:commission {
  money+
}

gf:costBasis

The monetary value of a portfolio or position cost.

The <gf:costBasis> element can appear only as a child of <gf:portfolioData> or <gf:positionData>.

Properties

Property	Type	Description
`gd:money`+	`money`	Monetary value for the data. The first money element is in the portfolio's default currency. When a security's default currency differs from the portfolio's, then a second money element is included using the security's default currency.

Example

<gf:costBasis>
  <gd:money amount='1000.0' currencyCode='USD'/>
</gf:costBasis>

Schema

element gf:costBasis {
  money+
}

gf:daysGain

The monetary value of a portfolio's or position's gain today (since the previous day's market close), counting only the currently held shares. A loss is expressed as a negative value.

The <gf:daysGain> element can appear only as a child of <gf:portfolioData> or <gf:positionData>.

Properties

Property	Type	Description
`gd:money`+	`money`	Monetary value for the data. The first money element is in the portfolio's default currency. When a security's default currency differs from the portfolio's, then a second money element is included using the security's default currency.

Example

<gf:daysGain>
  <gd:money amount='1000.0' currencyCode='USD'/>
</gf:daysGain>

Schema

element gf:daysGain {
  money+
}

gf:gain

The monetary value of a portfolio's or position's total gain, counting only the currently held shares.

The <gf:gain> element can appear only as a child of <gf:portfolioData> or <gf:positionData>.

Properties

Property	Type	Description
`gd:money`+	`money`	Monetary value for the data. The first money element is in the portfolio's default currency. When a security's default currency differs from the portfolio's, then a second money element is included using the security's default currency.

Example

<gf:gain>
  <gd:money amount='1000.0' currencyCode='USD'/>
  <gd:money amount='999.0' currencyCode='CAD'/>
</gf:gain>

Schema

element gf:daysGain {
  money+
}

gf:marketValue

A portfolio's or position's total market value.

The <gf:marketValue> element can appear only as a child of <gf:portfolioData> or <gf:positionData>.

Properties

Property	Type	Description
`gd:money`+	`money`	Monetary value for the data. The first money element is in the portfolio's default currency. When a security's default currency differs from the portfolio's, then a second money element is included using the security's default currency.

Example

<gf:marketValue>
  <gd:money amount='1000.0' currencyCode='USD'/>
  <gd:money amount='650.0' currencyCode='EUR'/>
</gf:marketValue>

Schema

element gf:marketValue {
  money+
}

gf:price

The price of a transaction.

The <gf:price> element can appear only as a child of <gf:transactionData>.

Properties

Property	Type	Description
`gd:money`+	`money`	Monetary value for the data. The first money element is in the portfolio's default currency. When a security's default currency differs from the portfolio's, then a second money element is included using the security's default currency.

Example

<gf:price>
  <gd:money amount='730.0' currencyCode='USD'/>
</gf:price>

Schema

element gf:price {
  money+
}

gf:symbol

A security, including full name and ticker exchange and symbol.

The <gf:symbol> element can appear only as a child of a position <entry>.

Properties

Property	Type	Description
`@fullName`	`xsd:string`	Full name of the company or fund.
`@exchange`	`xsd:string`	Name of the exchange. (May be `MUTF`, `PINK`, or empty in the case of non-exchange-traded securities, such as mutual funds.)
`@symbol`	`xsd:string`	Security's ticker symbol.

Example

<gf:symbol exchange='NASDAQ' fullName='Google Inc.' symbol='GOOG'/>

Schema

element gf:symbol {
  attribute exchange { xsd:string },
  attribute fullName { xsd:string },
  attribute symbol { xsd:string }
}


e.g. "ajax apis" or "open source"

Google Finance APIs and Tools (Labs)

Google Finance Portfolio Data API

Finance Tools

Google Data APIs

Reference Guide

Contents

Audience

Finance feed types

Portfolio feed

Position feed

Transaction feed

Finance query parameters reference

About returns

Finance elements reference

gd:money

Properties

Example

Schema

gf:portfolioData

Properties

Example

Schema

gf:positionData

Properties

Example

Schema

gf:transactionData

Properties

Example

Schema

gf:commission

Properties

Example

Schema

gf:costBasis

Properties

Example

Schema

gf:daysGain

Properties

Example

Schema

gf:gain

Properties

Example

Schema

gf:marketValue

Properties

Example

Schema

gf:price

Properties

Example

Schema

gf:symbol

Properties

Example

Schema