OpenFacet offers free, real-time access to natural GIA-certified round diamond prices via a structured JSON API. Data includes current DCX index, per-carat matrices, market depth across clarity/color bands, and fancy-shape L/W ratio adjustment models. Unlike closed or credentialed platforms, OpenFacet provides open, unauthenticated, and machine-ready data feeds without account setup or XML legacy formats.

The API supports valuation, algorithmic pricing, and liquidity modeling by exposing core components of OpenFacet’s transparent pricing methodology. All responses are JSON-formatted and timestamped in UTC.

If you prefer spreadsheet workflows, see CSV Data in Google Sheets & Excel for direct CSV imports and pricing formulas based on carat, color, and clarity.

Last updated: April 23, 2026

REST API Endpoints

Endpoints are served from: https://data.openfacet.net/.

GET /matrix.json – Price Matrices

Returns per-carat log price matrices across clarity and color, grouped by fixed carat bands.

Example: /matrix.json

Key Fields

l: Map of carat band → flat array of $\log(\text{per-carat price})$ values. Each array is of length rows × cols, where:
- rows = number of color grades (r)
- cols = number of clarity grades (c)
c: Clarity grade list (columns)
r: Color grade list (rows)
s: Shape [rows, cols] = [len(r), len(c)]

Price Calculation

To compute per-carat price:

$$ \text{price} = \exp(\log_\text{price}) $$

To interpolate $\log(\text{per-carat price})$ for non-discrete carat weights:

$$ \log_i = (1 - \lambda) \cdot \log(p_1) + \lambda \cdot \log(p_2) $$

Where:

$p_1, p_2$ are per-carat prices at carat bands $c_1, c_2$
$\lambda = \frac{c - c_1}{c_2 - c_1}$, with $c$ the target carat

After interpolation, apply Math.exp(log_i) to obtain the interpolated per-carat price.

GET /ratio_models.json – Fancy-Shape L/W Ratio Models

Returns the shape-specific length-to-width ratio adjustment models used for fancy-shape pricing. This endpoint does not replace the base matrix endpoints. Instead, it provides an additional multiplicative layer that is applied on top of a base per-carat price from matrix.json or the cushion matrix dataset when the selected shape is mapped to that source.

Example: /ratio_models.json

Purpose

For shapes such as oval, pear, radiant, emerald, marquise, heart, and cushion, pricing depends not only on carat, color, and clarity, but also on outline proportions. ratio_models.json exposes the calibration data behind that L/W ratio adjustment.

Structure

Top-level shape models are stored under:

shapes[shape_key]

Each shape entry may contain:

dataSource: base matrix family to apply first. Current consumers switch to matrix_cushion.json when this field is cushion; otherwise they use matrix.json.
valueMode: interpretation of the fitted ratio value.
- delta_pct → convert to multiplier as $1 + \frac{v}{100}$
- any other mode → convert to multiplier as $\frac{v}{100}$
slider: UI guidance for acceptable ratio input range
- min: minimum supported ratio
- center: default or neutral ratio
- max: maximum supported ratio
bands[]: carat-band-specific ratio models
- minCarat: inclusive lower bound
- maxCarat: inclusive upper bound when present; open-ended when omitted
- points[]: anchor points for interpolation
  - ratio: L/W ratio anchor
  - value: fitted value at that ratio anchor

Schematic Example

{
  "shapes": {
    "oval": {
      "dataSource": "round",
      "valueMode": "delta_pct",
      "slider": {
        "min": 1.20,
        "center": 1.45,
        "max": 1.75
      },
      "bands": [
        {
          "minCarat": 0.3,
          "maxCarat": 0.69,
          "points": [
            { "ratio": 1.25, "value": -3.2 },
            { "ratio": 1.40, "value": 0.0 },
            { "ratio": 1.55, "value": 2.1 }
          ]
        }
      ]
    }
  }
}

How to Apply It

Compute the base per-carat price from the appropriate matrix dataset.
Select the matching shape model under shapes.
Find the active entry in bands[] for the target carat.
Linearly interpolate the value between the two surrounding points[] by ratio.
Convert that interpolated value into a multiplier using valueMode.
Multiply the base per-carat price by that multiplier.

In compact form:

$$ P_{\text{final}} = P_{\text{base}} \cdot M(r) $$

Where $M(r)$ is the interpolated L/W ratio multiplier for the chosen shape and carat band.

Out-of-Range Handling

Consumers should avoid unconstrained extrapolation. When a ratio falls outside the modeled anchor range for a band, the practical implementation clamps to the nearest supported endpoint and may treat the result as more preference-driven than tightly market-calibrated.

GET /index.json – Composite Index & Basket

Returns the current Diamond Composite Index (DCX) and a representative basket of actively traded specifications.

Example: /index.json

Sample Response

{
  "dcx": 3568.6,
  "specs": [
    {
      "carat": 0.5,
      "clarity": "SI1",
      "color": "H",
      "cut": "Excellent",
      "log": 7.428,
      "per_carat": 1682.38,
      "price": 841.19,
      "weight": 0.22
    },
    ...
  ],
  "trend": 0.13,
  "ts": "2025-05-19T13:26:49Z"
}

Fields

dcx: Composite per-carat price in USD.
specs[]: Sample stones with:
- price: Total price in USD
- per_carat: USD per carat
- log: $\log(\text{price})$ for interpolation
- weight: Basket contribution
trend: 24h change in dcx, in percent (e.g. 0.13 = +0.13%)
ts: Timestamp in ISO 8601 format

GET /depth.json – Market Depth

Reports inventory depth across dimensions of carat, color, and clarity. Useful for liquidity-aware models or filtering.

Example: /depth.json

Structure

clarity[carat][clarity]: Listings count per clarity grade at given carat
color[carat][color]: Listings count per color grade at given carat
colclar[color][clarity]: Total listings for each color × clarity pair
ts: Snapshot timestamp

Example

"1.0": {
  "VS2": 1232
}

There are 1232 listings for 1.0ct VS2 diamonds at the snapshot time.

MCP Server

The same diamond pricing data is also exposed via a Model Context Protocol (MCP)–compliant remote server at: https://mcp.openfacet.net/ for AI agents and LLM applications.

This remote MCP endpoint provides programmatic access to:

Interpolated diamond prices (get_diamond_price) – Real-time pricing with interpolation across carat, color, and clarity
DCX index values (get_dcx_index) – Composite market trends and 24h changes
Market depth analytics (get_market_depth) – Inventory counts and liquidity data

Example

Requesting a diamond price quote for a 1.23ct G VS2 round diamond:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_diamond_price",
    "arguments": {
      "carat": 1.23,
      "color": "G",
      "clarity": "VS2"
    }
  }
}

Response:

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"💎 **Diamond Price Quote**\n\n**Specifications:**\n• Carat: 1.23ct\n• Color: G\n• Clarity: VS2\n• Shape: round\n\n**Pricing:**\n• Per Carat: $4,490\n• Total Price: $5,522.7\n\n*Prices from OpenFacet.net API*"}],"_meta":{"timestamp":"2025-07-09T03:22:28.407Z","source":"OpenFacet.net API"}}

The server is unauthenticated and supports automatic discovery via standard tools/list calls. Responses follow MCP 2025-06-18 specification and use JSON-RPC 2.0 with structured content format.

For developers integrating with AI systems, the MCP server provides the same underlying data as the REST endpoints above, but with built-in interpolation and a protocol designed for LLM tool use.

Data Freshness

Snapshots are updated periodically, typically once per 24h. Check the ts field in each response to ensure data recency. MCP tool responses are based on the same underlying snapshot datasets.

For methodology details, see the OpenFacet & DCX Methodology page.

Disclaimer: The Diamond Composite Index (DCX) is a model-based benchmark constructed from public retail listings. It does not represent executable prices or financial advice. All data is filtered, interpolated, and smoothed for index use. Use at your own discretion. GIA is a registered trademark of the Gemological Institute of America. This site is not affiliated with, endorsed by, or associated with GIA.

Real-Time Diamond Pricing API

REST API Endpoints

GET /matrix.json – Price Matrices

Key Fields

Price Calculation

GET /ratio_models.json – Fancy-Shape L/W Ratio Models

Purpose

Structure

Schematic Example

How to Apply It

Out-of-Range Handling

GET /index.json – Composite Index & Basket

Sample Response

Fields

GET /depth.json – Market Depth

Structure

Example

MCP Server

Example

Data Freshness