Skip to main content

Using the QuickChart Word Cloud API

QuickChart provides an API that generates word clouds or tag clouds, visualizations that give prominence to words that appear frequently in a given text.

Getting started

The word cloud API endpoint is available at https://quickchart.io/wordcloud. Here's a simple example that is embedded on this page straight from the API:

To be or not to be, that is the question
To be or not to be, that is the question

The only required parameter of the word cloud API is text. Set it in your URL:

https://quickchart.io/wordcloud?text=To be or not to be, that is the question

API options

There are many ways to customize your word cloud. Here are all the options offered by the API:

ParameterDescriptionDefault
textText of the word cloud(required)
formatImage output format - svg or pngsvg
widthImage width600
heightImage height600
backgroundColorBackground color of image
(rgb, hsl, hex, or name value)
transparent
fontFamilyFont family to useserif
loadGoogleFontsGoogle Fonts to load
fontScaleSize of the largest font (roughly)25
scaleFrequency scaling method - linear, sqrt, or loglinear
paddingPadding between words, in pixels1
rotationMaximum angle of rotation for words20
maxNumWordsMaximum number of words to show.
Note that fewer may be shown depending on size.
200
minWordLengthMinimum character length of each word to include.1
caseForce words to this case - upper, lower, or nonelower
colorsList of colors for words in JSON format, assigned randomly.
e.g. ["red", "#00ff00", "rgba(0, 0, 255, 1.0)"]
random
removeStopwordsIf true, remove common words from the cloudfalse
languageTwo-letter language code of stopwords to removeen
useWordListIf true, treat text as a comma-separated list of words or phrases instead of trying to split the text on our sidefalse

Examples

Lincoln's speech

Let's do a word cloud of Lincoln's famous Gettysburg address:

It looks pretty great by default! All I did was put Lincoln's speech in the URL, https://quickchart.io/wordcloud?text=Four score and seven years ago...

Churchill's speech

Now, let's say we want to do a tag cloud of Churchill's famous "we shall fight on the beaches" Dunkirk speech. This is a long speech that is too big to fit in a URL, so we will instead use a POST request to send the data.

Because I'm doing this on the command line, I'll first create a file churchill.json with the following JSON contents:

{
"format": "png",
"width": 1000,
"height": 1000,
"fontFamily": "sans-serif",
"fontScale": 15,
"scale": "linear",
"text": "<churchill's full speech...>"
}

Then POST it to the API endpoint using curl:

curl -X POST -H 'Content-Type: application/json' https://quickchart.io/wordcloud -d @churchill.json -o churchill.png

This downloads churchill.png, which looks like this:

Even though I used the command line and curl, you can easily do this in any programming language. Just send an HTTP POST request in your language of choice.

A website

You can create a word cloud with any sort of content, including from a webpage. Here's a quick tutorial from the command line.

Let's make a word cloud of today's Wall Street Journal, because I want to see what my boss is reading.

We'll use the article-parser project to download and extract the text from the page and do the rest in Python, in order to make request building easier.

First, fetch the article content. This is simple enough as the article parser API does the amgic for us:

import requests

resp = requests.get('https://us-central1-technews-251304.cloudfunctions.net/article-parser?url=https://www.wsj.com')

article = resp.json()['data']['content']

Now, create a POST request to the word cloud API with the article content and write it to a file:

resp = requests.post('https://quickchart.io/wordcloud', json={
'format': 'png',
'width': 1000,
'height': 1000,
'fontScale': 15,
'scale': 'linear',
'removeStopwords': True,
'minWordLength': 4,
'text': article,
})

with open('newscloud.png', 'wb') as f:
f.write(resp.content)

Here is the output:

You can see some artifacts of the Google News webpage (like &amp and "http), but overall not bad for a very quick hack.

Using custom fonts

caution

⚠️ This section applies to SVG format images only!

A few basic font families such as sans, sans-serif, and monospace are available by default.

If you wish to use more exotic fonts, use the loadGoogleFonts parameter to instruct the renderer to make Google Fonts available in your word cloud.

For example, the following payload will use the Roboto font:

{
"loadGoogleFonts": "Roboto",
"fontFamily": "Roboto",

"format": "png",
"width": 1000,
"height": 1000,
"fontScale": 15,
"scale": "linear",
"text": "..."
}

You may also specify font weights, such as Roboto:300.

Conclusion

QuickChart's word cloud API is one of the most flexible web services out there that can allow you to create word clouds programmatically without any dependencies. What will you build? Feel free to reach out to reach out with questions, feature requests, or to share interesting word clouds!


Ian Webster

About the author

Ian Webster is a software engineer and former Googler based in San Mateo, California. He has helped Google, NASA, and governments around the world improve their data pipelines and visualizations. In 2018, Ian created QuickChart, a collection of open-source APIs that support data visualization efforts.

Email · LinkedIn · Twitter