Constants API

Dictionaries and technical constants that the other APIs refer to by id.

The Constants API returns the Cutwise dictionaries (cut shapes, grades, colors) and the technical constants of the Optical Performance Scores. Diamonds API v3 refers to dictionary entries by their id, so a v3 client reads this API to turn ids into names.

Get the constants

  • Method and path: GET https://api.cutwise.com/v2/constants
  • Auth: none
  • Request: no parameters
  • Response: JSON object with the dictionaries and the scoring constants
GET https://api.cutwise.com/v2/constants

Response:

{
  "ver": "4.1.0",
  "dict": {
    "cutShape": [
      {
        "id": 2,
        "title": "Round"
      },
      {
        "id": 4,
        "title": "Princess"
      },
      ...
    ],
    "color": [
      {
        "id": 15,
        "title": "D",
        "short": "D",
        "position": 10
      },
      {
        "id": 16,
        "title": "E",
        "short": "E",
        "position": 20
      },
      ...
    ],
    "clarity": [
      {
        "id": 1,
        "title": "FL",
        "short": "FL",
        "position": 10
      },
      {
        "id": 2,
        "title": "IF",
        "short": "IF",
        "position": 20
      },
      ...
    ],
    "cutQuality": [
      {
        "id": 1,
        "title": "Excellent",
        "short": "EX",
        "position": 10
      },
      {
        "id": 2,
        "title": "Very Good",
        "short": "VG",
        "position": 20
      },
      ...
    ],
    "polish": [
      {
        "id": 1,
        "title": "Excellent",
        "short": "EX",
        "position": 10
      },
      {
        "id": 2,
        "title": "Very Good",
        "short": "VG",
        "position": 20
      },
      ...
    ],
    "symmetry": [
      {
        "id": 1,
        "title": "Excellent",
        "short": "EX",
        "position": 10
      },
      {
        "id": 2,
        "title": "Very Good",
        "short": "VG",
        "position": 20
      },
      ...
    ],
    "fluorIntensity": [
      {
        "id": 1,
        "title": "None",
        "short": "NON",
        "position": 10
      },
      {
        "id": 2,
        "title": "Faint",
        "short": "FNT",
        "position": 20
      },
      ...
    ],
    "fluorColor": [
      {
        "id": 7,
        "title": "None",
        "short": "N",
        "position": 0
      },
      {
        "id": 1,
        "title": "Blue",
        "short": "B",
        "position": 10
      },
      ...
    ],
    "fancyGrade": [
      {
        "id": 8,
        "title": "Faint",
        "short": "Faint",
        "abbreviation": "FT",
        "position": 10
      },
      {
        "id": 9,
        "title": "Very Light",
        "short": "V.Light",
        "abbreviation": "VL",
        "position": 20
      },
      ...
    ],
    "colorHue": [
      {
        "id": 11,
        "title": "Yellow",
        "short": "Y",
        "position": 10,
        "children": [
          {
            "id": 30,
            "title": "Green-Yellow",
            "short": "GY",
            "position": 8
          },
          ...
        ]
      },
      {
        "id": 20,
        "title": "Red",
        "short": "R",
        "position": 40,
        "children": []
      },
      ...
    ],
    "colorModifier": [
      {
        "id": 1,
        "title": "Brownish",
        "short": "br",
        "position": 10
      },
      {
        "id": 3,
        "title": "Brown",
        "short": "Br",
        "position": 20
      },
      ...
    ]
  },
  "scoring": {
    "fluorescence": {
      "ver": "5.4.2018-06-29-770653064"
    },
    "fire": {
      "grades": [0.3, 0.5, 0.7, 0.85, 1, 1.3],
      "ver": "fire-2018-01-26-6525426815546393815"
    },
    "brightness": {
      "grades": [0.5, 0.7, 0.85, 0.95, 1.03, 1.3],
      "ver": "5.4.2018-06-29-3890169345"
    },
    "symmetry": {
      "grades": [2, 4, 6, 7, 8, 9],
      "ver": "1.3.0"
    },
    "integral": {
      "grades": [0.51, 0.69, 0.83, 0.93, 1.02, 1.27],
      "ver": "1.1.0"
    }
  }
}

Fields

In the table, res is the root object of the response.

Field Description
res.ver Current version of the Cutwise Platform API. It follows Semantic Versioning 2.0.
res.dict Cutwise dictionaries, described in the rows below.
res.dict.cutShape Top-level cut shapes. For related shapes, use the CutShape API: GET https://api.cutwise.com/v2/cutshapes returns the list, GET https://api.cutwise.com/v2/cutshapes/87 returns one shape.
res.dict.color Color grades for colorless diamonds, as a flat list.
res.dict.clarity Clarity grades, as a flat list.
res.dict.cutQuality Cut quality grades, as a flat list.
res.dict.polish Polish grades, as a flat list.
res.dict.symmetry Symmetry grades, as a flat list.
res.dict.fluorIntensity Fluorescence intensity grades, as a flat list.
res.dict.fluorColor Fluorescence colors, as a flat list.
res.dict.fancyGrade Color grades for fancy colored diamonds.
res.dict.colorHue Color hues of fancy colored diamonds, as a tree. A hue can have child hues in children.
res.dict.colorModifier Color modifiers, as a flat list.
res.scoring Technical constants of the Cutwise Optical Performance Scores. See Optical Performance Scores.

Caching

Cache the constants on the client side. The simplest rule is to reload them when the Cutwise Platform version changes, even when only the patch number changes. Every API response carries the current Cutwise Platform version in the X-App-Version HTTP header.

Support for the If-Modified-Since header is on the roadmap.

Related pages