Developer Documentation

Public API

Name: Caratpillar Diamond Price Data API
Creator: Caratpillar
License: https://creativecommons.org/licenses/by/4.0/

Free access to Caratpillar's diamond price data, Diamond Price Index, and market signals. No authentication required. CC-BY 4.0 license.

Rate limit

100 req/day per IP

Auth

None required

Format

JSON

License

CC-BY 4.0

Base URL

https://www.caratpillar.com

All endpoints return JSON · CORS enabled (all origins) · Updated every Monday 06:00 UTC

◆ Attribution Required (CC-BY 4.0)

When using this data, include attribution: "Data: Caratpillar.com" with a link to caratpillar.com. This is the only requirement.

Endpoints

GET/api/market

Full market dataset — all metrics in one request.

Parameters

Name	Type	Default	Description
`metric`	string	`all`	One of: all, dpi, ratio, inventory, ttb, prices, signals

Example Request

GET https://www.caratpillar.com/api/market?metric=all

Example Response

{
  "dpi": [{ "recorded_at": "2026-05-12", "dpi_natural": 1024, "dpi_lab": 387, ... }],
  "ratio": [{ "recorded_at": "2026-05-12", "lab_pct_of_natural": 11.8 }],
  "ttb": { "natural": { "score": 7, "tier": "good", "summary": "..." }, "lab": { ... } },
  "meta": { "source": "Caratpillar", "updatedEvery": "Monday 06:00 UTC", "license": "CC-BY-4.0" }
}

GET/api/market?metric=dpi

Diamond Price Index — weekly composite index for natural and lab-grown markets.

Parameters

Name	Type	Default	Description
`weeks`	integer	`12`	Number of weeks of history (max 52)

Example Request

GET https://www.caratpillar.com/api/market?metric=dpi&weeks=52

Example Response

{
  "dpi": [
    {
      "recorded_at": "2026-05-12",
      "dpi_natural": 1024,
      "dpi_lab": 387,
      "dpi_combined": 797,
      "dpi_natural_pct_chg": 1.8,
      "dpi_lab_pct_chg": -4.2
    },
    ...
  ]
}

GET/api/market?metric=prices

Weekly price history for a specific diamond specification.

Parameters

Name	Type	Default	Description
`type`	string	`natural`	"natural" or "lab"
`carat`	number	`1.00`	Carat weight. Tracked: 0.50, 0.70, 1.00, 1.50, 2.00, 3.00
`color`	string	`G`	GIA color grade: D–J
`clarity`	string	`VS2`	GIA clarity grade: IF, VVS1, VVS2, VS1, VS2, SI1, SI2
`weeks`	integer	`12`	Weeks of history (max 52)

Example Request

GET https://www.caratpillar.com/api/market?metric=prices&type=natural&carat=1.00&color=G&clarity=VS2&weeks=24

Example Response

{
  "prices": {
    "spec": { "type": "natural", "carat": 1.00, "color": "G", "clarity": "VS2" },
    "data": [
      { "recorded_at": "2026-05-12", "retailer": "bluenile", "price_usd": 4200 },
      { "recorded_at": "2026-05-12", "retailer": "rarecarat", "price_usd": 3880 },
      ...
    ],
    "meta": {
      "source": "Caratpillar weekly affiliate feed aggregation",
      "license": "CC-BY-4.0 — Attribution required: Caratpillar.com",
      "rateLimit": "100 requests/day per IP"
    }
  }
}

GET/api/market?metric=ttb

Time-to-Buy Score — composite market timing signal (1–10, 10 = best time to buy).

Example Request

GET https://www.caratpillar.com/api/market?metric=ttb

Example Response

{
  "ttb": {
    "natural": {
      "score": 7,
      "trendScore": 8,
      "seasonalScore": 6,
      "tier": "good",
      "summary": "Prices are trending down and seasonal demand is low — a favorable buying window."
    },
    "lab": {
      "score": 8,
      "tier": "good",
      "summary": "Lab-grown prices continue their structural decline."
    },
    "generatedAt": "2026-05-19T10:30:00Z"
  }
}

GET/api/prices-history

Simplified price history endpoint for embeds and widgets.

Parameters

Name	Type	Default	Description
`type`	string	`natural`	"natural" or "lab"
`carat`	number	`1.00`	Carat weight
`color`	string	`G`	Color grade
`clarity`	string	`VS2`	Clarity grade
`weeks`	integer	`12`	Weeks of history

Example Request

GET https://www.caratpillar.com/api/prices-history?type=lab&carat=1.00&color=G&clarity=VS2&weeks=12

Example Response

{
  "dates": ["2026-02-24", "2026-03-03", ..., "2026-05-12"],
  "series": {
    "bluenile":       [490, 485, 480, ..., 465],
    "rarecarat":      [445, 440, 435, ..., 430],
    "cleanorigin":    [415, 412, 408, ..., 400],
    "whiteflash":     [560, 555, 550, ..., 540],
    "brilliantearth": [590, 585, 580, ..., 570]
  }
}

Retailers Tracked

Prices are sourced from affiliate product feeds and direct API calls. Updated every Monday.

Retailer	Region	Diamond Type
Blue Nile	🇺🇸 USA	Natural + Lab
Whiteflash	🇺🇸 USA	Natural
Rare Carat	🇺🇸 USA	Natural + Lab
Brilliant Earth	🇺🇸 USA	Natural + Lab
Ritani	🇺🇸 USA	Natural
Diamonds-USA	🇺🇸 USA	Natural
Brian Gavin	🇺🇸 USA	Natural
Clean Origin	🇺🇸 USA	Lab-grown only
BAUNAT	🇧🇪 Belgium	Natural

Error Codes

Code	Meaning	Action
200	Success	Data returned in response body
400	Bad Request	Check query parameter spelling and values
429	Rate Limited	Wait until midnight UTC for daily limit to reset
500	Server Error	Temporary issue — retry after 60 seconds
503	Service Unavailable	Scheduled maintenance or DB issue — check caratpillar.com/status

Questions or Partnerships

For API access above 100 requests/day, data partnerships, or press inquiries:

api@caratpillar.com →

Caratpillar API · Data under CC-BY 4.0 · Prices USD ex-VAT · Not financial advice