Home Tools Styles Free Trial Login

GRT Calculator API Documentation

Want to add Golden Ratio Typography to your next project?

You could use the GRT Calculator determine your typographic variables, but what if you ever decide to change your font, font size, or content width?

This could potentially affect all sizing and spacing in your design—not good, as this implies a lot of work to adjust everything to accommodate your new settings!

If you want your project’s typography to be adaptable, you’ll need a dynamic solution that changes according to your current typographic settings.

Fortunately, the GRT Calculator includes a handy API you can use to add truly dynamic typography to any project!

API Basics

  • Location: https://grtcalculator.com/api/
  • Accepted variables:
    • font — font name
    • size — primary font size
    • width — content width
  • Response format: JSON

The API does not require you to supply all three variables; in other words, only one variable needs to be present for a successful API call.

Calling the API

There are a variety of ways to make basic API calls, and the method you choose will depend entirely on your codebase.

For example, if you’re using JavaScript, you’ll probably want to use the Fetch API.

If you’re using PHP, you might opt for a cURL request instead.

But no matter which call method you choose, your GRT Calculator API requests must be URL-encoded, which will look something like this:

https://grtcalculator.com/api/?font=IBM+Plex+Sans&size=18&width=672

You can determine the precise font names from the dropdown selector in the GRT Calculator.

Please note: If the font is a Google Font, do not include the trailing (G) in the font name, or else the API call will not work!

In the sample API call above, IBM Plex Sans is indeed a Google Font, and you can see how I’ve omitted the trailing (G) to create a proper API call.

Also note: Spaces in font names must be replaced with + to create a proper API call.

API Response Data

Just like the Calculator, the API delivers a response based on your input data. The only difference is that the API response is an array in JSON format.

Depending on the input variables, the API response will contain the following data:

  • status — success or failure
  • font — the font used for GRT calculations
  • phi — the value of the golden ratio, in case you need to use it in any subsequent calculations
  • grt-given — GRT optimizations based on the input size and width if both are provided
  • grt-size — GRT optimizations based on the input size (in other words, this is “perfect” GRT based on font and size, regardless of whether or not you supplied a width)
  • grt-width — GRT optimizations based on the input width (“perfect” GRT for font within the current width, regardless of the input size)

And each GRT optimization—grt-given, grt-size, and grt-width—is an array containing the following data:

  • size — the font size used for this particular optimization (may not match your input size)
  • height — the line height associated with the size above
  • width — the content width used for this particular optimization (may not match your input width)
  • cpl — the expected average number of characters per line for this particular optimization
  • scale-font-size — the typographic scale for this particular optimization
    • f1 — largest size
    • f2 — second largest size
    • f3 — third largest size
    • f4 — fourth largest size
    • f5 — primary font size, corresponds to size for this particular optimization
    • f6 — smallest font size
  • scale-line-height — line heights corresponding to the font sizes in scale-font-size for this particular optimization
    • f1 — line height for font size f1
    • f2 — line height for font size f2
    • f3 — line height for font size f3
    • f4 — line height for font size f4
    • f5 — line height for font size f5, corresponds to height for this particular optimization
    • f6 — line height for font size f6
  • scale — convenient typographic scale reference including all relevant values in one place:
    • f1 — array of size, height, height-em, size-rem, and height-rem for size f1
    • f2 — array of size, height, height-em, size-rem, and height-rem for size f2
    • f3 — array of size, height, height-em, size-rem, and height-rem for size f3
    • f4 — array of size, height, height-em, size-rem, and height-rem for size f4
    • f5 — array of size, height, height-em, size-rem, and height-rem for size f5
    • f6 — array of size, height, height-em, size-rem, and height-rem for size f6
  • spacing — spacing units based on the line height of the primary text for this particular optimization (height)
    • x1 — largest unit of spacing
    • x2 — primary spacing unit, corresponds to height for this particular optimziation
    • x3 — third largest unit of spacing
    • x4 — fourth largest unit of spacing
    • x5 — fifth largest unit of spacing
    • x6 — largest unit of spacing
  • spacing-rem — spacing units expressed in rem instead of pixels
    • x1 — largest unit of spacing
    • x2 — primary spacing unit, corresponds to height for this particular optimziation
    • x3 — third largest unit of spacing
    • x4 — fourth largest unit of spacing
    • x5 — fifth largest unit of spacing
    • x6 — largest unit of spacing

Here is a sample JSON response from the example API call above (with IBM Plex Sans at 17px and 672px wide):

{
    "status": "success",
    "font": "IBM Plex Sans",
    "phi": 1.618033988749895,
    "grt-given": {
        "size": 17,
        "height": 29,
        "width": 672,
        "cpl": 89,
        "scale-font-size": {
            "f1": 45,
            "f2": 35,
            "f3": 28,
            "f4": 22,
            "f5": 17,
            "f6": 13
        },
        "scale-line-height": {
            "f1": 70,
            "f2": 56,
            "f3": 45,
            "f4": 37,
            "f5": 29,
            "f6": 24
        },
        "scale": {
            "f1": {
                "size": 45,
                "height": 70,
                "height-em": 1.55556,
                "size-rem": 2.64706,
                "height-rem": 4.11765
            },
            "f2": {
                "size": 35,
                "height": 56,
                "height-em": 1.6,
                "size-rem": 2.05882,
                "height-rem": 3.29412
            },
            "f3": {
                "size": 28,
                "height": 45,
                "height-em": 1.60714,
                "size-rem": 1.64706,
                "height-rem": 2.64706
            },
            "f4": {
                "size": 22,
                "height": 37,
                "height-em": 1.68182,
                "size-rem": 1.29412,
                "height-rem": 2.17647
            },
            "f5": {
                "size": 17,
                "height": 29,
                "height-em": 1.70588,
                "size-rem": 1,
                "height-rem": 1.70588
            },
            "f6": {
                "size": 13,
                "height": 24,
                "height-em": 1.84615,
                "size-rem": 0.76471,
                "height-rem": 1.41176
            }
        },
        "spacing": {
            "x1": 47,
            "x2": 29,
            "x3": 18,
            "x4": 11,
            "x5": 7,
            "x6": 4
        },
        "spacing-rem": {
            "x1": 2.76471,
            "x2": 1.70588,
            "x3": 1.05882,
            "x4": 0.64706,
            "x5": 0.41176,
            "x6": 0.23529
        }
    },
    "grt-size": {
        "size": 17,
        "height": 29,
        "width": 578,
        "cpl": 76,
        "scale-font-size": {
            "f1": 45,
            "f2": 35,
            "f3": 28,
            "f4": 22,
            "f5": 17,
            "f6": 13
        },
        "scale-line-height": {
            "f1": 70,
            "f2": 55,
            "f3": 45,
            "f4": 36,
            "f5": 29,
            "f6": 23
        },
        "scale": {
            "f1": {
                "size": 45,
                "height": 70,
                "height-em": 1.55556,
                "size-rem": 2.64706,
                "height-rem": 4.11765
            },
            "f2": {
                "size": 35,
                "height": 55,
                "height-em": 1.57143,
                "size-rem": 2.05882,
                "height-rem": 3.23529
            },
            "f3": {
                "size": 28,
                "height": 45,
                "height-em": 1.60714,
                "size-rem": 1.64706,
                "height-rem": 2.64706
            },
            "f4": {
                "size": 22,
                "height": 36,
                "height-em": 1.63636,
                "size-rem": 1.29412,
                "height-rem": 2.11765
            },
            "f5": {
                "size": 17,
                "height": 29,
                "height-em": 1.70588,
                "size-rem": 1,
                "height-rem": 1.70588
            },
            "f6": {
                "size": 13,
                "height": 23,
                "height-em": 1.76923,
                "size-rem": 0.76471,
                "height-rem": 1.35294
            }
        },
        "spacing": {
            "x1": 47,
            "x2": 29,
            "x3": 18,
            "x4": 11,
            "x5": 7,
            "x6": 4
        },
        "spacing-rem": {
            "x1": 2.76471,
            "x2": 1.70588,
            "x3": 1.05882,
            "x4": 0.64706,
            "x5": 0.41176,
            "x6": 0.23529
        }
    },
    "grt-width": {
        "size": 20,
        "height": 34,
        "width": 672,
        "cpl": 75,
        "scale-font-size": {
            "f1": 52,
            "f2": 41,
            "f3": 32,
            "f4": 25,
            "f5": 20,
            "f6": 16
        },
        "scale-line-height": {
            "f1": 80,
            "f2": 64,
            "f3": 51,
            "f4": 41,
            "f5": 34,
            "f6": 28
        },
        "scale": {
            "f1": {
                "size": 52,
                "height": 80,
                "height-em": 1.53846,
                "size-rem": 2.6,
                "height-rem": 4
            },
            "f2": {
                "size": 41,
                "height": 64,
                "height-em": 1.56098,
                "size-rem": 2.05,
                "height-rem": 3.2
            },
            "f3": {
                "size": 32,
                "height": 51,
                "height-em": 1.59375,
                "size-rem": 1.6,
                "height-rem": 2.55
            },
            "f4": {
                "size": 25,
                "height": 41,
                "height-em": 1.64,
                "size-rem": 1.25,
                "height-rem": 2.05
            },
            "f5": {
                "size": 20,
                "height": 34,
                "height-em": 1.7,
                "size-rem": 1,
                "height-rem": 1.7
            },
            "f6": {
                "size": 16,
                "height": 28,
                "height-em": 1.75,
                "size-rem": 0.8,
                "height-rem": 1.4
            }
        },
        "spacing": {
            "x1": 55,
            "x2": 34,
            "x3": 21,
            "x4": 13,
            "x5": 8,
            "x6": 5
        },
        "spacing-rem": {
            "x1": 2.75,
            "x2": 1.7,
            "x3": 1.05,
            "x4": 0.65,
            "x5": 0.4,
            "x6": 0.25
        }
    }
}

Planning on using rem values?

If so, you’ll need to ensure the <body> tag of your HTML document is equipped with the following CSS:

body {
	font-size: size;
}

…where size is equal to the primary font size—in pixels!—used in your GRT calculations.

← Back to the Calculator