1 00:00:07,850 --> 00:00:14,115 Welcome back. Let's take a look at another REST API, iTunes. 2 00:00:14,115 --> 00:00:16,830 iTunes is Apple's media store. 3 00:00:16,830 --> 00:00:20,940 The REST API lets us make queries asking what's in the store. 4 00:00:20,940 --> 00:00:24,225 So, this page is their documentation. 5 00:00:24,225 --> 00:00:27,400 There's a base URL, 6 00:00:31,520 --> 00:00:36,850 which goes up through search, so https://itunes.apple.com/search. 7 00:00:40,520 --> 00:00:43,700 Then, as we've seen before, the query parameters, 8 00:00:43,700 --> 00:00:48,260 there is a question mark and then some key value pairs. 9 00:00:48,260 --> 00:00:52,775 What are the keys and values that iTunes understands, 10 00:00:52,775 --> 00:00:54,905 for those query parameters? 11 00:00:54,905 --> 00:00:57,900 Let's scroll down and we'll see. 12 00:00:58,580 --> 00:01:02,435 We've got a whole table of them, there's a bunch. 13 00:01:02,435 --> 00:01:05,285 In the left column, are the key names, 14 00:01:05,285 --> 00:01:10,880 things like term, country, media or entity. 15 00:01:10,880 --> 00:01:12,440 In the right column, 16 00:01:12,440 --> 00:01:16,420 there's some information about what are the allowable values. 17 00:01:16,420 --> 00:01:20,000 So, the term that's going to be what we're searching for, 18 00:01:20,000 --> 00:01:23,225 and you can put any text string in there, 19 00:01:23,225 --> 00:01:29,750 but for media, there's only certain allowable values like movie or podcasts or music. 20 00:01:29,750 --> 00:01:33,380 So in our URL, when we make a request to iTunes, 21 00:01:33,380 --> 00:01:37,350 we're going to have something like media equals podcast. 22 00:01:37,690 --> 00:01:46,460 The other two columns tell us whether we are required to include this query parameter. 23 00:01:46,460 --> 00:01:49,760 Yes, you have to include term and you have to include country, 24 00:01:49,760 --> 00:01:52,130 but the other ones are optional. 25 00:01:52,130 --> 00:01:56,830 Then, there's just a description that gives you some hints about what you getting. 26 00:01:56,830 --> 00:02:00,200 So, let's try to figure out what we would pass in for 27 00:02:00,200 --> 00:02:03,890 the params dictionary when we make a call to request.get. 28 00:02:03,890 --> 00:02:06,320 I'm going to go back to Runestone and we'll come 29 00:02:06,320 --> 00:02:09,660 back and look at this documentation as we need it. 30 00:02:09,670 --> 00:02:13,895 In the textbook, we've got a couple of exercises. 31 00:02:13,895 --> 00:02:17,850 Suppose we are trying to look for podcasts originating in Ann Arbor, 32 00:02:17,850 --> 00:02:22,210 and we're going to pass in a params dictionary to request that get. 33 00:02:22,210 --> 00:02:28,580 What value should we put here as the value associated with term? 34 00:02:28,580 --> 00:02:30,680 So, this is the thing we're searching for. 35 00:02:30,680 --> 00:02:36,005 So, since we've said we're looking for podcasts that mention Ann Arbor, 36 00:02:36,005 --> 00:02:38,500 then we put in Ann Arbor in here, 37 00:02:38,500 --> 00:02:40,575 and check me and it says, 38 00:02:40,575 --> 00:02:42,135 "Oh, don't forget the quotes. 39 00:02:42,135 --> 00:02:44,260 It needs to be a string." 40 00:02:45,200 --> 00:02:49,550 We're going to be putting a value here and it's got to be a string. 41 00:02:49,550 --> 00:02:53,400 So, let's put that value in quotes. 42 00:02:54,650 --> 00:02:57,350 When it gets encoded into the URL, 43 00:02:57,350 --> 00:02:58,980 it won't have the quotes around it. 44 00:02:58,980 --> 00:03:02,330 But in order to be a value in this params dictionary, 45 00:03:02,330 --> 00:03:03,905 it does need the quotes. 46 00:03:03,905 --> 00:03:06,965 That's all good. 47 00:03:06,965 --> 00:03:10,780 So, let's look at our next question. 48 00:03:11,300 --> 00:03:13,740 There's another parameter. 49 00:03:13,740 --> 00:03:16,035 If we're searching for podcasts, 50 00:03:16,035 --> 00:03:21,894 we're going to have to give another query parameter whose value is going to be podcast, 51 00:03:21,894 --> 00:03:23,970 which query parameter is it? 52 00:03:23,970 --> 00:03:26,110 Well, you could try to guess, 53 00:03:26,110 --> 00:03:31,835 and perhaps you remember the documentation page but let's go look. 54 00:03:31,835 --> 00:03:37,355 It turns out, we can say podcast for the query parameter media. 55 00:03:37,355 --> 00:03:39,335 If we scroll down a little farther, 56 00:03:39,335 --> 00:03:42,665 it turns out we also can say entity equals podcast. 57 00:03:42,665 --> 00:03:45,965 If we say media equals podcast, 58 00:03:45,965 --> 00:03:49,615 then we'll be doing a little bit broader search. 59 00:03:49,615 --> 00:03:52,370 We can do a slightly narrower search, 60 00:03:52,370 --> 00:03:55,370 where we say entity equals podcast and that will be 61 00:03:55,370 --> 00:04:00,680 limited to searching for Ann Arbor in the podcast title, 62 00:04:00,680 --> 00:04:06,950 excluding looking for it where Ann Arbor as part of the author. 63 00:04:07,590 --> 00:04:11,005 So, we could say either media or entity. 64 00:04:11,005 --> 00:04:16,680 We've actually set this up so that it will accept either media and says, 65 00:04:16,680 --> 00:04:18,285 yes you can use that. 66 00:04:18,285 --> 00:04:21,090 But in our code below, we're going to use entity. 67 00:04:21,090 --> 00:04:24,255 So, entity is also okay. 68 00:04:24,255 --> 00:04:27,750 So, here's a request that we can make. 69 00:04:27,750 --> 00:04:32,140 We're using requests with caching rather than requests just to 70 00:04:32,140 --> 00:04:36,280 make sure that if there's any problems getting to iTunes on a particular day, 71 00:04:36,280 --> 00:04:38,675 that it'll still work. 72 00:04:38,675 --> 00:04:43,960 We're passing in, term Ann Arbor and entity podcast. 73 00:04:44,150 --> 00:04:48,470 It'll take us a minute and we'll get a result. 74 00:04:48,630 --> 00:04:51,565 It found it in the permanent cache. 75 00:04:51,565 --> 00:04:55,740 Now, we haven't chosen to do anything with this, 76 00:04:55,750 --> 00:04:59,269 but I could also, for example, 77 00:04:59,269 --> 00:05:07,230 print what the full URL was that was created, 78 00:05:11,750 --> 00:05:15,180 and that's this URL. 79 00:05:15,180 --> 00:05:17,240 Now because we use caching, 80 00:05:17,240 --> 00:05:19,240 it didn't actually go and make the request 81 00:05:19,240 --> 00:05:23,480 itunes.apple.com but this is the request it would've made. 82 00:05:23,480 --> 00:05:25,830 It got the saved results, 83 00:05:25,830 --> 00:05:29,010 the cached results for that URL. 84 00:05:29,010 --> 00:05:32,074 Now, at this point, I've loaded 85 00:05:32,074 --> 00:05:34,805 the response text into 86 00:05:34,805 --> 00:05:39,160 a Python object and I had saved that in the variable called py data. 87 00:05:39,160 --> 00:05:44,480 At this point, we would have to go through our usual understand, extract, 88 00:05:44,480 --> 00:05:51,210 repeat process to pull out the data that we want from whatever is in py data. 89 00:05:51,220 --> 00:05:55,910 I'm going to skip ahead because I've already done 90 00:05:55,910 --> 00:06:02,040 that process of doing the understand extract and repeat and this is what I got to. 91 00:06:02,680 --> 00:06:09,030 So, I found that the top-level object was a dictionary. 92 00:06:09,030 --> 00:06:11,920 It had a key called results, 93 00:06:11,920 --> 00:06:17,370 and I've extracted the value associated with results. 94 00:06:17,500 --> 00:06:20,965 That value is a list. 95 00:06:20,965 --> 00:06:22,960 It's a list of dictionaries, 96 00:06:22,960 --> 00:06:26,120 one dictionary for each podcast result. 97 00:06:26,120 --> 00:06:31,100 Each of those podcasts is a dictionary that has a key called track name, 98 00:06:31,100 --> 00:06:33,725 and I've extracted the track name. 99 00:06:33,725 --> 00:06:35,405 So, when I run this, 100 00:06:35,405 --> 00:06:39,800 I will get the names of podcasts that have the word 101 00:06:39,800 --> 00:06:46,560 and I'll print them. 102 00:06:46,560 --> 00:06:49,040 So, it's telling us that it founded in permanent cache and 103 00:06:49,040 --> 00:06:53,100 then on each line we have one track name. 104 00:06:53,140 --> 00:06:57,470 As you can see, there's one from the Ann Arbor District Library. 105 00:06:57,470 --> 00:07:00,855 The award winning Ann Arbor District Library, I should say. 106 00:07:00,855 --> 00:07:03,020 We love our library in Ann Arbor, 107 00:07:03,020 --> 00:07:06,125 and we love libraries in general at the School of Information, 108 00:07:06,125 --> 00:07:09,230 and there's a bunch of podcasts from churches. 109 00:07:09,230 --> 00:07:11,780 You can see the Harvest Mission Community Church, 110 00:07:11,780 --> 00:07:14,840 Grace Bible Church and so on. 111 00:07:14,840 --> 00:07:19,505 Actually, there's a few more podcasts from the Ann Arbor District Library. 112 00:07:19,505 --> 00:07:24,050 So, that's an example of deciphering the iTunes API documentation, 113 00:07:24,050 --> 00:07:27,345 and using it to construct REST API queries. 114 00:07:27,345 --> 00:07:29,680 We'll see you next time.