# Get Latest Prices

Returns the most recent prices for all or specific commodities.

GET /v1/prices/latest

# Request

# Headers

Header	Required	Description
`Authorization`	Yes	Token YOUR_API_KEY
`Accept`	No	`application/json` (default)
`Accept-Encoding`	No	`gzip` for compressed responses

# Query Parameters

Parameter	Type	Required	Description	Example
`by_code`	string	No	Single commodity code per request	`WTI_USD`, `BRENT_CRUDE_USD`
`currency`	string	No	Convert prices to specified currency	`EUR`, `GBP`, `JPY`
`fields`	string	No	Specific fields to return	`price,timestamp,change_24h`

# Response

# Success Response (200 OK)

# Error Responses

# 400 Bad Request - Invalid Commodity

{
  "status": "error",
  "error": {
    "code": "INVALID_COMMODITY",
    "message": "Invalid commodity code: INVALID",
    "details": {
      "invalid_codes": ["INVALID"],
      "valid_codes": ["WTI_USD", "BRENT_CRUDE_USD", "NATURAL_GAS_USD", "GOLD_USD", "COAL_USD"]
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11

# 401 Unauthorized - Invalid API Key

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}

1
2
3
4
5
6
7

# 429 Too Many Requests - Rate Limit

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "reset_at": "2025-07-18T11:00:00Z"
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12

# Code Examples

# Response Fields

Field	Type	Description
`name`	string	Full commodity name
`price`	number	Current price
`currency`	string	Price currency (default: USD)
`unit`	string	Price unit (barrel, mmbtu, etc.)
`timestamp`	string	ISO 8601 timestamp of price update
`change_24h`	number	Absolute price change in last 24 hours
`change_percent_24h`	number	Percentage change in last 24 hours
`day_high`	number	Highest price today
`day_low`	number	Lowest price today
`week_high`	number	Highest price this week
`week_low`	number	Lowest price this week
`market_status`	string	Market status (open/closed)

# Best Practices

# 1. Cache Responses

Prices update every 5 minutes. Implement caching to reduce API calls:

const cache = new Map();
const CACHE_DURATION = 5 * 60 * 1000; // 5 minutes

async function getCachedPrices(commodities) {
  const key = commodities.join(',');
  const cached = cache.get(key);
  
  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
    return cached.data;
  }
  
  const fresh = await fetchPrices(commodities);
  cache.set(key, { data: fresh, timestamp: Date.now() });
  return fresh;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 2. Request Only What You Need

# Good - specific commodity
GET /v1/prices/latest?by_code=WTI_USD

# Avoid - all commodities when you only need two
GET /v1/prices/latest

1
2
3
4
5

# 3. Handle Errors Gracefully

def get_prices_with_retry(commodities, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, params=params)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                # Rate limited - wait and retry
                retry_after = int(e.response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
            elif attempt == max_retries - 1:
                raise
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 4. Use Field Selection

Reduce bandwidth by requesting only necessary fields:

# Mobile app - minimal data
GET /v1/prices/latest?fields=price,change_percent_24h

# Dashboard - comprehensive data
GET /v1/prices/latest?fields=price,timestamp,change_24h,day_high,day_low