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

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:

Parameter Description Default
text Text of the word cloud (required)
format Image output format - svg or png svg
width Image width 600
height Image height 600
backgroundColor Background color of image
(rgb, hsl, hex, or name value)
transparent
fontFamily Font family to use serif
fontScale Size of the largest font (roughly) 25
scale Frequency scaling method - linear, sqrt, or log linear
padding Padding between words, in pixels 1
rotation Maximum angle of rotation for words 20
maxNumWords Maximum number of words to show.
Note that fewer may be shown depending on size.
200
minWordLength Minimum character length of each word to include. 1
case Force words to this case - upper, lower, or none lower
colors List of colors for words in JSON format, assigned randomly.
e.g. [“red”, “#00ff00”, “rgba(0, 0, 255, 1.0)”]
random
removeStopwords If true, remove common words from the cloud false
language Two-letter language code of stopwords to remove en

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.

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