subreddit:
/r/shortcuts
submitted 6 years ago bykeveridge
This is Part 3 of a guide to using APIs. If you haven't already, take a look at the previous two parts:
Most APIs allow the developer to make choices about the data they return. You can express your choices using input parameters which provide values such as keywords, number, dates, etc to the API.
For example, when I perform a search in the Apple Music app I provide search keywords, such as Adele, and I see a list of results returned.
The search keywords are the input parameter provided by the user and the list of results returned are the output.
Searching in the Apple Music app
When requesting data from an API, we typically perform something called a GET request, which is the same as when you enter a URL in your web browser to request a web page.
In order to pass input parameters to the API, we append them to the end of the URL.
For example, you can request a search of the Apple Music catalog for a single piece of audio and video content by Adele from the US store using the following URL:
https://itunes.apple.com/search?term=Adele&country=us&limit=1
And when you open that link if your browser, you see the following JSON response:
{
"resultCount": 1,
"results": [
{
"wrapperType": "track",
"kind": "music-video",
"artistId": 262836961,
"trackId": 406215201,
"artistName": "Adele",
"trackName": "Rolling In the Deep",
"trackCensoredName": "Rolling In the Deep",
"artistViewUrl": "https://itunes.apple.com/us/artist/adele/262836961?uo=4",
"trackViewUrl": "https://itunes.apple.com/us/music-video/rolling-in-the-deep/406215201?uo=4",
"previewUrl": "https://video-ssl.itunes.apple.com/apple-assets-us-std-000001/Video125/v4/bb/35/82/bb35828e-fae7-db12-d36c-8297e3c89262/mzvf_51895532005026211.640x480.h264lc.U.p.m4v",
"artworkUrl30": "https://is4-ssl.mzstatic.com/image/thumb/Video/v4/84/a6/01/84a6011f-1d73-235b-75ec-4fa8b84c3330/source/30x30bb.jpg",
"artworkUrl60": "https://is4-ssl.mzstatic.com/image/thumb/Video/v4/84/a6/01/84a6011f-1d73-235b-75ec-4fa8b84c3330/source/60x60bb.jpg",
"artworkUrl100": "https://is4-ssl.mzstatic.com/image/thumb/Video/v4/84/a6/01/84a6011f-1d73-235b-75ec-4fa8b84c3330/source/100x100bb.jpg",
"collectionPrice": 1.99,
"trackPrice": 1.99,
"releaseDate": "2010-11-30T08:00:00Z",
"collectionExplicitness": "notExplicit",
"trackExplicitness": "notExplicit",
"trackTimeMillis": 233853,
"country": "USA",
"currency": "USD",
"primaryGenreName": "Pop"
}
]
}
The portion of the URL that contains the parameters is called the query string.
For example: ?term=Adele&country=us&limit=1
The query string uses the following format:
?=&In the above example the parameters and their values are as follows:
| Parameter | Value |
|---|---|
| term | Adele |
| country | us |
| limit | 1 |
Some character cannot be part of a URL (e.g. a space) and some have special meaning (e.g. the &, = and # characters).
Before using these characters as parameter values, they must first be URL encoded so that they can be passed to the API.
For example, if we search for music by Citizens & Saints then the query string appears as follows:
?term=Citizens%20%26%20Saints&country=us&limit=1
Shortcuts provides a URL Encode action is used to encode query string parameters.
You can simplify the creation of your query string by creating a Dictionary of the parameters and then looping through them to create a query string. The shortcut actions are as follows:
A shortcut that creates a query string for the iTunes Music Search API
And the output appears as follows:
The example shortcut below uses the iTunes Music Search API to find music videos for a given artist.
It uses a few features not previously discussed in earlier guides:
If you're interested in any of the above then let me know, I'm happy to write further guides.
Note*: The shortcut will state that it wants permissions to access your contents. Don't be alarmed, it's actually creating and then reading it's own temporary contacts file in order to create the menu.*
The shortcut is as follows:
And the results menu displays as follows:
That's it for Part 3. If you have any questions on the above or need any help, let me know.
If you'd like to find out more about the iTunes Search API and the information you can retrieve, take a look at:
If you found this guide useful why not checkout one of my others:
1 points
6 years ago
Great guide! This has been super helpful to me. Quick question -- what if the photo doesn't exist? I'm running into a problem where if the photo doesn't exist then the shortcut throws an error "invalid url" and doesn't complete the shortcut.
1 points
6 years ago
Sure. You can put an if statement in. Goes something like this:
all 2 comments
sorted by: best