YoutualFunds Web API

What is it?

Many traders use computer programs to place trades. To accommodate these traders, YoutualFunds.com makes available a web-based API. All calls to this API are accomplished through HTTP/HTTPS, by having your program call a URL.

Who can use it, and how?

Anyone who is a registered YoutualFunds.com user has access to the YoutualFunds.com web API.

You may request info for any public fund on YoutualFunds.com with the web API, but you may only allocate funds that you own.

Using the web API is easy. Your software needs to be able to request a Web URL. This is a trivial matter in most programming languages.

Note that you can manually test this interface by simply typing a Web address into your browser. This will allow you to see how the system works.

How to create the URL

The strategy for using the Web interface is as follows. You will code a web address (URL) which contains all the information necessary to request information about a fund, or create an allocation for a fund.

The URL is in the following format:


https://www.youtualfunds.com/yfapi?[PARAMETERS]

EVERY request must contain the email address and password associated with your YoutualFunds.com account as parameters, as well as additional parameters for each type of request (see Actions, below).

Use of http:// instead of https:// will work, but it is strongly recommended you use a secure https:// connection, as you are sending your password with each request.

A response is then returned, in XML format. Each response contains a status tag with a value of either 'OK' or 'ERROR', along with other additional information (as specified in Actions, below).

Actions

getPrice

 Get current price of a given Youtual Fund

 Parameters:

    email => the email address associated with your YoutualFund account 
    
    password => the password associated with your YoutualFund account

    fundSymbol => the YoutualFund Symbol for the fund you are requesting information about

 Example:

    /yfapi?action=getPrice&email=you@abcdef.com&password=yourpass&fundSymbol=^EXIT

    returns (success example):
   
    <xml>
        <price>105.46</price>
        <status>OK</status>
    </xml>

   or, on failure would return a message like:

    <xml>
        <price>No matching fund exists</price>
        <status>ERROR</status>
    </xml>

doAllocate

 Request allocation of stocks/funds within a YoutualFund you own.
 Note that this completely replaces your previous allocation, so if you want to retain some of your 
 previous holdings, use getHoldings() first, to read your current positions. 
 All percentages added together must equal 100% or less.

 Parameters:

    email => the email address associated with your YoutualFund account 
    
    password => the password associated with your YoutualFund account

    fundSymbol => the YoutualFund Symbol for the fund for which you are requesting an allocation

    holdingX => each stock or YoutualFund you wish to allocate where X is a numeric number
    
    percentX => percent of each stock or YoutualFund you wish to allocate where X matches the number used in holdingX 
			(defaults to 0)
    
    directionX => long|short for each stock or YoutualFund you wish to allocate where X matches the number used in holdingX 
			(defaults to 'long')

    notes => optional notes on the allocation

 Example:

    /yfapi?action=doAllocate&email=you@abcdef.com&password=yourpass&fundSymbol=^EXIT&
	holding1=IBM&percent1=30&direction1=long&holding2=^SWING&percent2=20&direction2=short

    returns (if successful):

    <xml>
      <status>OK</status>
    </xml>

getHoldings

 Get current holdings of a given Youtual Fund

 Parameters:

    email => the email address associated with your YoutualFund account 
    
    password => the password associated with your YoutualFund account

    fundSymbol => the YoutualFund Symbol for the fund you are requesting information about

 Example:

    /yfapi?action=getHoldings&email=you@abcdef.com&password=yourpass&fundSymbol=^EXIT

    returns (for example):

    <xml>
      <holdings>
        <holding>
          <direction>long</direction>
          <fund_impact>0.05</fund_impact>
          <is_youtualfund>0</is_youtualfund>
          <name>Agilent Technologies Inc.</name>
          <percent>15</percent>
          <symbol>A</symbol>
        </holding>
        <holding>
          <direction>long</direction>
          <fund_impact>0.00</fund_impact>
          <is_youtualfund>0</is_youtualfund>
          <name>International Business Machines Corp.</name>
          <percent>40</percent>
          <symbol>IBM</symbol>
        </holding>
        <holding>
          <direction>short</direction>
          <fund_impact>-0.05</fund_impact>
          <is_youtualfund>1</is_youtualfund>
          <name>Head for the Exits</name>
          <percent>40</percent>
          <symbol>^EXIT</symbol>
        </holding>
      </holdings>
      <status>OK</status>
    </xml>

addNote

 Add note to a given fund's timeline.  Can specify allocation id.

 Parameters:

    email => the email address associated with your YoutualFund account 
    
    password => the password associated with your YoutualFund account

    fundSymbol => the YoutualFund Symbol for the fund for which you are writing a note
    
    notes => note text

    allocID => optional allocation ID to include note with
   
 Example:

    
    /yfapi?action=addNote&email=you@abcdef.com&password=yourpass&fundSymbol=^EXIT&notes=Hello

    returns (if successful):

    <xml>
      <status>OK</status>
    </xml>