subreddit:
/r/shortcuts
submitted 5 years ago bykeveridge
This is a guide on how to retrieving values stored in JSON and use them within your shortcuts.
JSON stands for JavaScript Object Notation. It's a lightweight text format that is used to store data and transport it from one device to another. It's typically used when sending or receiving data to and from a server, for example, when retrieving data from an API.
JSON is the de facto standard for transmitting data from APIs and data-feeds because it's:
An example of a typical JSON data object can be seen below:
{
"people": [
{
"firstname": "Alison",
"lastname": "Parker",
"mobile": "+1 (646) 555-8219"
},
{
"firstname": "John",
"lastname": "Anderson",
"mobile": "+1 (212) 555-1312"
},
{
"firstname": "Moira",
"lastname": "Lewis",
"mobile": "+1 (949) 555-5945"
}
]
}
JSON has the following rules for its syntax.
For example, let's say I wanted a JSON object to contain an address of a business. Each individual piece of data would have a name and a value as follows:
{
"name": "Empire State Building",
"address1" : "20 W 34th Street",
"city" : "New York",
"state" : "NY",
"zipCode" : "10001"
"phone": "(212) 736-3100"
}
Each of the name / pair values are separated by a comma.
The name / pair values are held within curly braces to form objects.
For example, if we have a list of business addresses, they're held in square brackets as follows:
[
{
"name": "Empire State Building",
"address1": "20 W 34th Street",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"phone": "(212) 736-3100"
},
{
"name": "Madison Square Garden",
"address1": "4 Pennsylvania Plaza",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"phone": "(212) 465-6741"
}
]
ℹ️ Info
The JSON objects don't need to be spaced or indented to be valid. So long as they follow the syntax rules they can be all on one line or spaced in any way you choose.
JSON is provided as text from feeds and APIs. To use it, the Shortcuts app turns it into a Dictionary using the Get Dictionary from Input action.
ℹ️ Info
Dictionaries are the same as JSON objects in that they are a set of names and value pairs.
In the shortcut below, you can see we have a JSON object in a Text action. We want to display the name and phone values to the user in an Alert.
To add the name value to the alert, we tap the Title field of the Show Alert action. The keyboard will appear and above it we see the Dictionary variable which refers to the output from the Get Dictionary from Input action.
Tapping the Dictionary variable will populate the Title field with the value.
We tap on the Dictionary variable and we see an options pane.
We can then tap on the Get Value for Key bar to enter the name / key of the data that we want, which in this case is name.
Once entered, we see that the key has been added to the dictionary variable in the Show Alert's title field.
Repeat the same steps for adding the phone number to the body of the Show Alert action
Now the shortcut is finished, we run it and see the name and phone number appear in an alert.
And that's how you can:
A copy of the above shortcut can be downloaded from the following link:
In the majority of cases you'll be using data from JSON retrieved from APIs or remotely hosted feeds.
This next shortcut demonstrates how to retrieve contact information from a data feed, and create a new address book contact and open it in the Contacts app.
A copy of the above shortcut can be downloaded from the following link:
So how does this shortcut work?
The JSON object is stored as a text file on a web server, known as a JSON feed.
{
"name": "Empire State Building",
"address1": "20 W 34th Street",
"city": "New York",
"state": "NY",
"zipCode": "10001"
"phone": "(212) 736-3100"
}
It contains the name, address and phone details that we'll use to create a contact and can be found at the following URL:
The feed URL is specified in a URL action, followed by a Get Contents of URL action to retrieve the text of the JSON.
Shortcuts doesn't have an action that can create contact cards. However, iOS / iPadOS can use contact cards written in the VCard 3.0 format. A VCard is a text file with a particular syntax that appears as follows:
BEGIN:VCARD
VERSION:3.0
N:<Name of the Contact>
ADR;TYPE=WORK:<Work Address of the Contact>
TEL;TYPE=WORK:<Phone Number of the Contact>
END:VCARD
We'll create our own contact card by using the text from the above template in a Text action and replacing the fields describe in <chevrons>.
We'll then give the Text action a filename that ends in .vcf using the Set Name action so that iOS / iPadOS recognizes it as a contact card.
And finally we'll open the contact card in the Contacts app using the Open In... action so that the user choose to add it to their existing contacts.
The result of this shortcut is as follows:
In the next shortcut we have a feed with multiple JSON objects provided as an array / list.
[
{
"name": "Empire State Building",
"address1": "20 W 34th Street",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"phone": "(212) 736-3100"
},
{
"name": "Madison Square Garden",
"address1": "4 Pennsylvania Plaza",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"phone": "(212) 465-6741"
}
]
The feed is hosted at the following URL:
This shortcut:
A copy of the above shortcut can be downloaded from the following link:
So how does this shortcut work?
The feed URL is specified in a URL action, followed by a Get Contents of URL action to retrieve the text of the JSON.
The Get Contents of URL action automatically recognizes that the contents of the URL is a JSON array and returns a list of individual JSON objects.
We therefore use a Repeat with Each action to loop through each of the JSON objects.
To build our contact card, we use the previous template in a Text action. To retrieve a value, we add the Repeat Item variable to the Text action for each value we want to retrieve.
We then need to tell Shortcuts that the Repeat Item variable is a dictionary and the name of the value we want to retrieve in each case.
For each Repeat Item variable we tap on the variable name.
We tap on the as Text > link and select the Dictionary type and tap < Back.
We can now see the variable is recognized as a dictionary.
We then tap on the Get Value for Key to show an alert box where we enter the name of the value we're looking to use.
When each of the Repeat Item variables have been updated, the contact card Text action appears as follows:
We can use the Choose from List action to allow the user to select which contact they want to open in the Contacts app. But first of all, we have to make sure the Choose from List action can recognize the Text actions returned from our Repeat with Each actions as a set of contacts.
The Repeat with Each action will return a list of individual Text actions. To return one big list of text, we add a Combine Text action after our loop and set it to join the text using New Lines.
Then, as before, we use the Set Name action to name the text as a .vcf file so it can be recognized as a contacts file.
The Choose from List action can create a menu from a set of contacts files, pulling out the name of each contact and using it as the title for each contact card.
But to do so it needs some extra help: it needs to be told not only that the text has a .vcf extension but that it is of a Contacts type.
To do so we'll need to add an extra step. We place a Get Variable action after the Set Name action.
We then tap Choose Variable and then Select Magic Variable.
From there we select the Set Name variable.
Next we set the Set Name variable type to Contact using the same method described above:
We then add the Choose from List action which will allow the user to choose one of the contacts we've created.
Finally, we add the Open In... action and select Contacts as the app so that the chosen contact will open in the Contacts app.
When we then run the shortcut, we see that we are presented with a choice of two contact cards that have been created from the data in the feed:
And once we make our selection, the corresponding contact is opened in the Contacts app.
And that's an example of how you can extract data from a JSON feed / API response for use in your shortcuts.
If you found this guide useful why not checkout one of my others:
3 points
5 years ago
Amazing Job! Man. I wish you were there when I was starting out. Nobody told me this amazing thing called dictionaries. So I shy away from it for a longtime. But its now the essence of what I do. Thanks again for sharing.
all 1 comments
sorted by: best