Developer Documentation - Calculators

As a software or web site developer tasked with integrating CalcXML's calculator engines with your desktop or web applications, you need to have at your fingertips all the right documentation to get your job done quickly and accurately. Well, you've come to the right place!

Below you'll find links to all the documents, API documentation, and samples that are needed to make the integration a simple one. As always, we are interested in your feedback, so if you encounter problems or have suggestions on how we could improve the integration experience, please let us know.

You can integrate with CalcXML's calculators in several different ways:

• Hyperlinks which you place on your web site
• Embedded Using Javascript (AJAX)
• Web Services - REST calls where you create and host the calculator input and result pages

CalcXML calculators are available as hyperlinks which you place on your web site. When clicked, these calculator hyperlinks can open in:

• A new popup window
• A standard iframe
• An auto-sizing iframe
• A shadow box
• An embedded div

You can see examples of these different implementation options by looking at our Customer Success page.

You can control the look-and-feel of the calculator input and result pages using a css stylesheet file. We provide our base stylesheet and you can modify it as much as you like. Once you are happy with it, we'll load it up on our servers and use it for all of your hyperlinked calculators. You can also host the stylesheet on your own servers if desired and make changes to it whenever needed without having to get our support team involved. NOTE: Our support team typically gets stylesheet changes done within a 24-hour period. You can also have your company logo appear on the calculator pages.

• Anything related to style in the css file. (Colors, fonts, alignment, buttons, etc.)
• Most of the text on the calculator input page, including the calculator title, introductory paragraph(s), field labels, and disclaimer.
• The images used for the submit, help and other buttons. NOTE: Images are not required for some buttons as they can be controlled via styling in the css file.
• The default values that appear in the input fields when the calculator page first displays. This is done using query string parameters passed in on the URL like this: https://www.calcxml.com/calculators/be-a-millionaire?currentAge=22 or this: https://www.calcxml.com/calculators/loan-payment-calculator?interestRate=4.37%25
• The width of the chart that is returned as part of the results. This can be handy if you need a smaller chart. This is done using query string parameters passed in on the URL like this: https://www.calcxml.com/calculators/be-a-millionaire?chartWidth=300. Click the Submit button on the page that is displayed to see the chart. NOTE: Chart height is set automatically by the system and cannot be overridden.
• Whether the values entered into the calculator get stored as cookies on the user's computer. When enabled, this will prepopulate the calculator with the last used data when the user opens the calculator page again. NOTE: This requires that the user have cookies enable.
• Whether http or https links are used.
• A banner across the bottom of the calculator page promoting anything you'd like. Examples would be:
  • a hyperlinked image
  • a small iframe which contains content from your site
  • marketing text
  • any html
• Reset and Edit buttons can be shown if desired. Reset sets all input field values to our standard default values. Edit returns the user to the top of the page to allow editing of the input values.
• Whether the charts are flash-based or image-based (gif/jpg). This is done using a query string parameter passed in on the URL like this. Valid values are "flash" and "image": https://www.calcxml.com/calculators/be-a-millionaire?chartLibrary=image
• Recommendations, or "calls to action", can be defined and displayed on the results page on a per-calculator basis. Along with this functionality comes the ability to specify the criteria for each recommendation. The criteria are based on the user's input values.

The embedded calculator works by making an AJAX call, which then loads the desired calculator into a <div>. To place an embedded calculator on your site, add the embed code where you want the calculator to appear. Here is a sample of the embed code:

<script type='text/javascript' src='https://code.jquery.com/jquery-3.4.1.min.js' type='text/javascript'></script>
<script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js' type='text/javascript'></script>
<script type='text/javascript' src='https://www.calcxml.com/scripts/tipped/comboTipped.js' type='text/javascript'></script>
<script type='text/javascript' src='http://cdnjs.cloudflare.com/ajax/libs/jquery-ajaxtransport-xdomainrequest/1.0.2/jquery.xdomainrequest.min.js'></script>
<script type='text/javascript' src='https://www.calcxml.com/scripts/loadCalc.js?calcTarget=sav01&embed=2&skn=62'></script>
<div id='calc' style='padding-top: 10px;'></div>

The real strength of CalcXML's calculators is the fact that they are available as web services, giving you complete control over every aspect of the user interface. You create and host the calculator input and result pages. If desired, you can store user entered data, gather traffic statistics, gather lead generation data, or whatever else you like. You are in control.

You will need an IT staff in order to integrate using our web services, but rest assured, the integration is still quite simple for those familiar with web services. The documentation that follows will give you everything you need to have a successful web service integration.

REST Web Services

CalcXML's calculators are divided up into 13 categories. Each calculator has unique input parameters. This web-based API documentation lets you see the details behind every calculator, providing helpful documentation and links to all relevant schemas for each calculator.

REST API documentation - Each calculator is represented in the API documents. Sample URL, requests and parameters are shown. Both JSON and XML are supported data transfer options.

CalcXML calculators can be used in any country and language. By passing in a country code and language, you tell the CalcXML calculator engine how to format the monetary amounts which will be returned. The Flash and image charts that are created are also formatted appropriately, including chart title and axis labels.

This functionality is available when integrating via web services as well as when integrating via hyperlinks. As described above, web services gives you the ability to create and host the calculator pages while hyperlinks provides a quicker time to market.

Language Codes Use the ISO 639-1 alpha-2 codes.
Country Codes Use the ISO 3166-1 alpha-2 codes.