Documentation

This documentation has been set out to make it very easy to understand even if you are not a programmer. It is very simple to use this RESTful API. (You can find the legacy "Instructions" here)

Getting Live Access to the API

You can test the API for free during development using the API key "tryfree", "trydonation" or "trypremium" for the relevant subscription. When you are ready to go live, please visit the pricing page. After you sign-up for free or pay you will receive an email at your subscribed (Paypal) email address containing important information. Use the key you receive in the email to access the real-time API.

NOTE: You can top-up the hits in your premium account at any time by purchasing more using the same paypal account (email).

Back to Top

Quick Start Guide

Always access the API with a HTTP request as follows:

URL — https://api.freegoldprice.org/request.cfm
METHOD — GET
PARAMETERS [REQUIRED]:
key — The key you received when you paid.
action — One of the actions set out below.

HINT: Use "tryfree", "trydonation" or "trypremium" as the key for testing.
EXAMPLE: https://api.freegoldprice.org/request.cfm?key=trydonation&action=GSJ

Back to Top

Managing Your Account

You can manage your account through a simple secure web page. Use your browser to access the API:

URL — https://api.freegoldprice.org/request.cfm
METHOD — GET
PARAMETERS [REQUIRED]:
key — The key you received when you paid.
AND ANY ONE OF:
action — "account" (access this action with a browser)
action — "accountstatusx" (receive an XML account status report)
action — "accountstatusj" (receive a JSON account status report)

EXAMPLE: https://api.freegoldprice.org/request.cfm?key=[key]&action=account

KEY RECOVERY
PARAMETERS [REQUIRED]:
key — Your subscribed (Paypal) email address
action — "recover"

EXAMPLE: https://api.freegoldprice.org/request.cfm?key=someone@email.com&action=recover

Back to Top

Request Logs

A log file of all your API requests is available (purged weekly at approximately midnight Saturday UCT):

EXAMPLE: https://api.freegoldprice.org/Logs/[key].txt

Back to Top

System Status

To poll the API to know if the markets are closed, use these links:

JSON: https://api.freegoldprice.org/status.json
XML:   https://api.freegoldprice.org/status.xml

CODES EXPLAINED
0 = Prices not updating, market is closed or other error
1 = Prices are updating, no known issues

TIMES EXPLAINED
"time" = The time of the last status change
"updated" = The time of the most recent update to the status file

Back to Top

JSON Price Requests

Each request during market open hours consumes one hit.
Only one action allowed per request.
Requests while the market is closed receive the closing price and no hit is consumed.

ACTION SWITCHES EXPLAINED (Prices per troy ounce unless the "M" switch is included)
GS = Gold & Silver
PP= Platinum & Palladium
J = JSON
X = XML
M = Grams (metric)

NOTE: Prices are offered in ounces or grams for your convenience. If you need both it is not necessary to download an extra file, calculate the other in your application. (1 troy ounce = 31.1034768 grams exactly).

URL — https://api.freegoldprice.org/request.cfm
METHOD — GET
PARAMETERS [REQUIRED]:
key — The key you received when you paid.
AND ANY ONE OF:
action — "GSJ"
action — "PPJ" (Premium only)
action — "GSJM" (Premium only)
action — "PPJM" (Premium only)

EXAMPLE: https://api.freegoldprice.org/request.cfm?key=[key]&action=GSJ

Back to Top

XML Price Requests

Each request during market open hours consumes one hit.
Only one action allowed per request.
Requests while the market is closed receive the closing price and no hit is consumed.

ACTION SWITCHES EXPLAINED (Prices per troy ounce unless the "M" switch is included)
GS = Gold & Silver
PP= Platinum & Palladium
J = JSON
X = XML
M = Grams (metric)

NOTE: Prices are offered in ounces or grams for your convenience. If you need both it is not necessary to download an extra file, calculate the other in your application. (1 troy ounce = 31.1034768 grams exactly).

URL — https://api.freegoldprice.org/request.cfm
METHOD — GET
PARAMETERS [REQUIRED]:
key — The key you received when you paid.
AND ANY ONE OF:
action — "GSX"
action — "PPX" (Premium only)
action — "GSXM" (Premium only)
action — "PPXM" (Premium only)

EXAMPLE: https://api.freegoldprice.org/request.cfm?key=[key]&action=GSX

Back to Top

Tips & Tricks

  • Don't hit the XML or JSON file more frequently than approximately one minute intervals because our Gold and Silver prices update every 30 to 40 seconds depending on network latency.
  • If you have multiple users who need to access the Gold and Silver prices randomly, save the XML or JSON page on your site/server and direct the users there so they don't use up the hit credits.
  • If you only use the Gold and Silver prices for your business during business hours, stop the downloads at night.(The API does not consume hits when the market is closed, but the spot markets are open 23 hours a day.)
  • To convert: 1 Troy Ounce = 31.1034768 Grams (exactly)
  • If you want to show the latest price on your web site, don't use a "cron job" or "scheduled task" to dowload the prices unless you are creating charts or need the historical data. Rather cache the price and update it each time the page is loaded, but not more often than every minute or two. This way you only use hits when a visitor is viewing your site.

Back to Top