Sign in with Google

**Gold Rate API** Documentation

Your comprehensive guide to integrating real-time and historical precious metals data.

Getting Started

Welcome to the **Gold Rate API** documentation! This guide will help you quickly integrate our API into your applications to access real-time and historical precious metals data. If you don't have an API key yet, you can get one for free on our pricing page.

All API requests are made over HTTPS to ensure secure data transmission.

Authentication

API Key

To access the **Gold Rate API**, you need to include your unique API access key with every request. Your API key should be passed as a query parameter named access_key.

GET https://api.goldapi.net/v1/price/XAU?access_key=YOUR_API_KEY

Important: Keep your API key secure and do not expose it in client-side code where it can be easily accessed.

Real-time Data Endpoint

The real-time endpoint provides the current spot price for gold, silver, platinum, and palladium against various currencies.

Endpoint URL

GET https://api.goldapi.net/v1/price/METAL_CODE/CURRENCY_CODE?access_key=YOUR_API_KEY

Parameters

  • METAL_CODE (required): The precious metal symbol (e.g., XAU for Gold, XAG for Silver, XPT for Platinum, XPD for Palladium).
  • CURRENCY_CODE (required): The 3-letter currency code (e.g., USD, EUR, JPY). You can find a list of supported currencies here (link to an imagined currency list).

Example Request (Gold in USD)

GET https://api.goldapi.net/v1/price/XAU/USD?access_key=YOUR_API_KEY

Example Response

{
    "metal": "XAU",
    "currency": "USD",
    "price": 2350.75,
    "ch": 15.20,
    "chp": 0.65,
    "ask": 2351.00,
    "bid": 2350.50,
    "high": 2355.90,
    "low": 2330.10,
    "open": 2335.55,
    "timestamp": 1678886400,
    "date": "2025-03-15"
}

Historical Data Endpoint

Access historical spot prices for any supported metal and currency on a specific date.

Endpoint URL

GET https://api.goldapi.net/v1/historical/METAL_CODE/CURRENCY_CODE/YYYY-MM-DD?access_key=YOUR_API_KEY

Parameters

  • METAL_CODE (required): (e.g., XAU, XAG)
  • CURRENCY_CODE (required): (e.g., USD, EUR)
  • YYYY-MM-DD (required): The desired date in YYYY-MM-DD format.

Example Request (Silver in EUR on 2024-01-10)

GET https://api.goldapi.net/v1/historical/XAG/EUR/2024-01-10?access_key=YOUR_API_KEY

Example Response

{
    "metal": "XAG",
    "currency": "EUR",
    "date": "2024-01-10",
    "price": 21.50,
    "high": 21.75,
    "low": 21.20,
    "open": 21.30
}

Currency Conversion

Our API can also provide direct currency conversions based on the latest precious metals rates.

Endpoint URL

GET https://api.goldapi.net/v1/convert/AMOUNT/FROM_CURRENCY/TO_CURRENCY?access_key=YOUR_API_KEY

Parameters

  • AMOUNT (required): The amount to convert.
  • FROM_CURRENCY (required): The source currency (e.g., USD).
  • TO_CURRENCY (required): The target currency (e.g., JPY).

Example Request (Convert 100 USD to JPY via Gold)

GET https://api.goldapi.net/v1/convert/100/USD/JPY?access_key=YOUR_API_KEY

Example Response

{
    "from": "USD",
    "to": "JPY",
    "amount": 100,
    "converted_amount": 15500.25,
    "rate": 155.0025,
    "timestamp": 1678886400
}

Rate Limits

To ensure fair usage and service stability, **Gold Rate API** implements rate limits based on your subscription plan:

  • Free Tier: 1,000 requests per month.
  • Developer Pro: 100,000 requests per month.
  • Enterprise: Custom limits, please contact us for details.

Exceeding your rate limit will result in a 429 Too Many Requests error. Please design your applications to handle this by implementing retries with exponential backoff.

Error Handling

The **Gold Rate API** uses standard HTTP status codes to indicate the success or failure of an API request. Errors are returned in JSON format with a clear error message.

Common Error Codes

  • 400 Bad Request: Missing or invalid parameters.
  • 401 Unauthorized: Invalid or missing API key.
  • 404 Not Found: Endpoint or resource not found.
  • 429 Too Many Requests: Rate limit exceeded.
  • 500 Internal Server Error: An unexpected error occurred on our side.

Example Error Response

{
    "code": 401,
    "message": "Invalid API Key. Please provide a valid access_key."
}

SDK Examples

To make integration even easier, we provide SDKs (Software Development Kits) for popular programming languages.

Python

Install the Python SDK:

pip install goldrateapi-python

Example usage:

import goldrateapi

client = goldrateapi.GoldRateAPIClient("YOUR_API_KEY")

try:
    # Get real-time gold price in USD
    gold_price = client.get_realtime_price("XAU", "USD")
    print(f"Current Gold Price: {gold_price['price']} USD")

    # Get historical silver price for a specific date
    silver_history = client.get_historical_price("XAG", "EUR", "2023-01-15")
    print(f"Silver Price on 2023-01-15: {silver_history['price']} EUR")

except goldrateapi.GoldRateAPIError as e:
    print(f"API Error: {e.message}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

JavaScript (Node.js/Browser)

Install the NPM package:

npm install goldrateapi-js

Example usage:

const GoldRateAPI = require('goldrateapi-js');

const client = new GoldRateAPI('YOUR_API_KEY');

async function fetchData() {
    try {
        // Get real-time palladium price in GBP
        const palladiumPrice = await client.getRealtimePrice('XPD', 'GBP');
        console.log(`Current Palladium Price: ${palladiumPrice.price} GBP`);

        // Convert 500 EUR to USD
        const conversion = await client.convert(500, 'EUR', 'USD');
        console.log(`500 EUR is ${conversion.converted_amount} USD`);

    } catch (error) {
        console.error('API Error:', error.message);
    }
}

fetchData();

PHP

Install via Composer:

composer require goldrateapi/php-sdk

Example usage:

<?php

require_once 'vendor/autoload.php';

use GoldRateAPI\Client;
use GoldRateAPI\Exception\GoldRateAPIException;

$client = new Client('YOUR_API_KEY');

try {
    // Get real-time platinum price in AUD
    $platinumPrice = $client->getRealtimePrice('XPT', 'AUD');
    echo "Current Platinum Price: " . $platinumPrice->price . " AUD\n";

    // Get historical gold price on a specific date
    $goldHistory = $client->getHistoricalPrice('XAU', 'CAD', '2022-11-20');
    echo "Gold Price on 2022-11-20: " . $goldHistory->price . " CAD\n";

} catch (GoldRateAPIException $e) {
    echo "API Error: " . $e->getMessage() . "\n";
} catch (Exception $e) {
    echo "An unexpected error occurred: " . $e->getMessage() . "\n";
}

?>

Frequently Asked Questions (FAQ)

General Questions

  • What is Gold Rate API?
    **Gold Rate API** provides real-time and historical precious metals data (gold, silver, platinum, palladium) to developers and businesses via a simple REST API.
  • What data sources do you use?
    We aggregate data from multiple reliable global exchanges and financial institutions to ensure high accuracy and uptime.
  • How often is the real-time data updated?
    Our real-time data is updated every 60 seconds for the most current prices.

Technical Questions

  • How do I get an API key?
    You can sign up for a free API key on our pricing page.
  • What authentication methods do you support?
    We use API key authentication, passed as an access_key query parameter.
  • What are the rate limits?
    Rate limits vary by plan: 1,000 requests/month for Free, 100,000 for Developer Pro, and custom limits for Enterprise. See Rate Limits section for more details.
  • Do you offer SDKs?
    Yes, we offer official SDKs for Python, JavaScript (Node.js/Browser), and PHP. See SDK Examples.

Billing & Account

  • How can I upgrade my plan?
    You can upgrade your plan directly from your account dashboard or by visiting our pricing page.
  • Do you offer refunds?
    Please refer to our Terms of Service for our refund policy.