How to use an API with Apple Shortcuts

In this blog post, I’ll be showing you how to create an Apple Shortcut that can present information from an API. And the best part? It’s super simple with Shortcuts. Whether you’re a seasoned shortcut pro or a newcomer to the world of automation, this post will have something for you. I’ll be demoing two different APIs, each with their own unique set of data, so you can get a hang of representing information in slightly different ways. Let’s dive in!

Photo by ThisIsEngineering from Pexels

Cat Facts API

Everyone loves a good cat fact, and now you can have them easily accessible from a Shortcut.

For this quick tutorial we are going to use the api https://catfact.ninja/fact which returns data in the following JSON format.

{"fact":"A cat's normal pulse is 140-240 beats per minute","length":73}

If you are new to JSON this might look a little strange, but it is how most API will return data and with a little practice it’ll become super easy to read.

As there are a tonne of tutorials on the JSON structures. We’ll just cover the basics for what we need for this API. Basically {} is referred to as a Dictionary, and the information inside is built from Key Value Pairs (KVP). So if you see { "user": "bob", "age": 3 } , this is a dictionary with 2 KVPs, the first KVP has a key of “user” whose value is “bob” and the second KVP has a key of “age” with a value of 3.

We can display the cat facts like this to make it easier to read…

{
  "fact" : "A cat's normal pulse is 140-240 beats per minute",
  "length" : 73
}

Ok, so let’s create the Shortcut.

On your Mac (Monterey) start by opening the Shortcuts app

1. Click “+” to create a new Shortcut
2. Name the Shortcut “Awesome Cat Facts”
3. Add in the action “Get contents of URL” , amend the url to https://catfact.ninja/fact.
4. Add in the action “Get Dictionary from Input”. As this action is underneath “Get contents of URL” Apple will automatically figure out you want the dictionary from the URL and so insert “Content of URL” for you (thanks Apple)
5. Add in the action “Get Dictionary Value”. You will see the action change to “Get Value for key in Dictionary”, amend key to fact . The important bit here is that the word fact corresponds to the key part of Key Value Pair in the JSON from the API. So what this action will do is get the Value part from the key name, in this case “A cat’s normal pulse….”.
6. Finally, add the action “Show Result”. Again the Shortcuts app with automatically figure out you want to display the fact and auto insert “Show Dictionary Value”.

You should end up with a very simple Shortcut like so…

Which produces an output like..

Don’t forget to select Shortcut details in the left panel (see shortcut details above) so you can pin the Shortcut to the menu bar for quick cat facts access.

Bored API

For this example the API will return the following…

{
  "activity" : "Create an amazing shortcut",
  "type" : "relaxation",
  "participants" : 1,
  "price" : 0.1,
  "link" : "",
  "key" : "8827573",
  "accessibility" : 0.8
}

This time it would be good to show 2 values, the activity and type text.

On your Mac (Monterey) start by opening the Shortcuts app

1. Click “+” to create a new Shortcut
2. Name the Shortcut “Bored?”
3. Add in the action “Get contents of URL”, amend url to https://www.boredapi.com/api/activity
4. Add in the action “Get Dictionary from Input”.
5. Add in the action “Get Dictionary Value”. You will see the action change to “Get Value for key in Dictionary”, amend key to activity .
6. Add in the action “Set variable”. Change “Variable Name” to activityVar. This means that activityVar = Create an amazing shortcut .
7. Add in the action “Get Dictionary Value”, and amend the key to type .
8. Add action “Set variable”, change “Variable Name” to typeVar . This means that typeVar = relaxation
9. Add the action “Text”. Enter a sentence you want to display to the user. As you enter the text typeVar the system should allow you to switch that text for a variable object. That does not always work, so you can add a variable by right clicking in the text area and selecting “Insert variable” followed by “Select Variable” — you can then tap the variable you want to display. Do the same for the other variable activityVar .
10. Finally add in the Alert action and insert the Text object.

You should end up with something like…

Giving out an shortcut that shows…

If you found this blog post helpful, you’ll love the book packed with plenty of real-world examples and AI integration — dive deep into Shortcuts.

Interested in Shortcuts? you can find more information here.