1
00:00:08,010 --> 00:00:12,310
Welcome back. Remember this URL that we used

2
00:00:12,310 --> 00:00:16,840
before to find out what words rhyme with funny?

3
00:00:16,840 --> 00:00:21,010
It's got the base part,

4
00:00:21,010 --> 00:00:22,745
and then a question mark,

5
00:00:22,745 --> 00:00:24,660
and then key equals value.

6
00:00:24,660 --> 00:00:29,095
Well, how did we know what to put into that base part?

7
00:00:29,095 --> 00:00:36,295
How did we know to use R-E-L_R-H-Y in order to ask for things that rhyme?

8
00:00:36,295 --> 00:00:41,170
The answer is you use the documentation for the API.

9
00:00:41,170 --> 00:00:44,815
So, let's take a look at the documentation of that API.

10
00:00:44,815 --> 00:00:50,150
Then we'll see, they have lots of things in here.

11
00:00:50,630 --> 00:00:53,535
So, in this documentation,

12
00:00:53,535 --> 00:01:00,575
they tell us that the main URL is going to be api.datamuse.com,

13
00:01:00,575 --> 00:01:03,745
and then they tell us some things that might go after that.

14
00:01:03,745 --> 00:01:05,645
You might have /words?

15
00:01:05,645 --> 00:01:08,805
something, or we'll see a little later on,

16
00:01:08,805 --> 00:01:10,295
that there's some other things,

17
00:01:10,295 --> 00:01:14,095
there's one other endpoint besides words.

18
00:01:14,095 --> 00:01:17,845
We'll describe /words as being what endpoint,

19
00:01:17,845 --> 00:01:21,820
and then the things after the question mark as being query parameters.

20
00:01:21,820 --> 00:01:24,025
So, you can ask for ml,

21
00:01:24,025 --> 00:01:27,410
and give a value ringing in the ears.

22
00:01:27,510 --> 00:01:30,270
So, in their documentation, they tell you,

23
00:01:30,270 --> 00:01:35,345
if you want to find out words with a meaning that's similar to ringing in the ears,

24
00:01:35,345 --> 00:01:39,455
you would give the query over on the right-hand side.

25
00:01:39,455 --> 00:01:44,240
We can scroll down and see some other things that you can do,

26
00:01:44,240 --> 00:01:48,195
lots of opportunities, lots of different things you can do,

27
00:01:48,195 --> 00:01:51,920
and here's that rel_rhy that I found.

28
00:01:51,920 --> 00:01:54,650
That's for words that rhyme with forgetful.

29
00:01:54,650 --> 00:01:59,000
Now, they've started by giving us a bunch of examples,

30
00:01:59,000 --> 00:02:00,685
but then, down below,

31
00:02:00,685 --> 00:02:02,780
they'll give you even more detail.

32
00:02:02,780 --> 00:02:10,205
So, they're saying, you can access most things at datamuse.com/words.

33
00:02:10,205 --> 00:02:12,655
So, that's going to end up being our base URL.

34
00:02:12,655 --> 00:02:13,850
Then we have to figure out,

35
00:02:13,850 --> 00:02:17,360
what are we going to put into that params dictionary?

36
00:02:17,360 --> 00:02:20,840
We can use the examples above,

37
00:02:20,840 --> 00:02:24,530
or we can try to look at some of the things

38
00:02:24,530 --> 00:02:27,849
below that are giving more detailed information.

39
00:02:27,849 --> 00:02:31,605
So, we can have the key be ml,

40
00:02:31,605 --> 00:02:34,815
we could have a key sl for sounds like,

41
00:02:34,815 --> 00:02:38,190
or there's a whole set of R-E-L_ things.

42
00:02:38,190 --> 00:02:43,080
There's R-E-L_J-J-A or R-E-L_T-R-G,

43
00:02:43,080 --> 00:02:48,520
or R-E-L_R-H-Y for rhymes with.

44
00:02:48,560 --> 00:02:52,400
So, that's how I figured out what some of

45
00:02:52,400 --> 00:02:56,060
the possible keys could be in my params dictionary.

46
00:02:56,060 --> 00:02:57,725
Then for the value,

47
00:02:57,725 --> 00:03:01,790
I really got it from my examples where I said, "Oh,

48
00:03:01,790 --> 00:03:05,490
well the value is just the word that I'm trying to pass as an input,

49
00:03:05,490 --> 00:03:11,190
I'm trying to get things that rhyme with forgetful or things that rhyme with funny."

50
00:03:11,440 --> 00:03:18,880
So, that's telling me what kind of queries I can give to this REST API,

51
00:03:18,880 --> 00:03:24,755
and at the bottom they'll tell me a little bit more about interpreting the results.

52
00:03:24,755 --> 00:03:29,840
So, I've passed over the other endpoint /sug,

53
00:03:29,840 --> 00:03:34,960
and I found something about what the responses will look like.

54
00:03:34,960 --> 00:03:36,170
It's going to be a list,

55
00:03:36,170 --> 00:03:38,210
that's what the square brackets tell me,

56
00:03:38,210 --> 00:03:41,000
and they tell me it's always going to be

57
00:03:41,000 --> 00:03:43,690
in the JSON format which you've been seeing already,

58
00:03:43,690 --> 00:03:45,300
and it's a list of dictionaries.

59
00:03:45,300 --> 00:03:48,800
Each dictionary is telling us information about one of

60
00:03:48,800 --> 00:03:52,700
the words that is related to our query.

61
00:03:52,700 --> 00:03:55,370
If our query was four words that rhyme with funny,

62
00:03:55,370 --> 00:03:57,710
then we would get each word that is

63
00:03:57,710 --> 00:04:01,505
a good rhyme for funny would have one dictionary in this list.

64
00:04:01,505 --> 00:04:04,370
So, this is a relatively simple API,

65
00:04:04,370 --> 00:04:06,130
and the documentation is pretty clear.

66
00:04:06,130 --> 00:04:09,220
You can figure out pretty well, how to use it.

67
00:04:09,220 --> 00:04:15,380
Another thing I want to show you with this API is just a nice practice

68
00:04:15,380 --> 00:04:18,050
if know you're going to make a bunch of calls to

69
00:04:18,050 --> 00:04:21,650
this API to get a bunch of rhyming words,

70
00:04:21,650 --> 00:04:26,865
maybe you're using this as an aid to your next rap hit,

71
00:04:26,865 --> 00:04:30,735
you might make a lot of calls to get_rhymes.

72
00:04:30,735 --> 00:04:36,000
So, I've defined a little function here that I can call multiple times.

73
00:04:36,000 --> 00:04:39,410
So, I can call get_rhymes on a word,

74
00:04:39,410 --> 00:04:43,010
and I'll get back a list of some other words.

75
00:04:43,010 --> 00:04:47,600
So, with funny, I'm getting back three things,

76
00:04:47,600 --> 00:04:51,300
and I can get_rhymes on something else.

77
00:04:54,460 --> 00:04:58,230
I want to get_rhymes with dash,

78
00:04:58,230 --> 00:05:00,390
I get cache, flash, and crash.

79
00:05:00,390 --> 00:05:03,525
Now, how did I implement this get_rhymes?

80
00:05:03,525 --> 00:05:09,330
Well, get_rhymes is going to take as an input a word like funny, or dash.

81
00:05:09,330 --> 00:05:12,625
So, that's going to be bound to my word parameter,

82
00:05:12,625 --> 00:05:17,480
and it's going to return a list of three rhyming words.

83
00:05:17,480 --> 00:05:21,770
But you saw that what we actually get back is not a list of words,

84
00:05:21,770 --> 00:05:24,665
it's a list of dictionaries with information.

85
00:05:24,665 --> 00:05:28,175
Each dictionary has information about one rhyming word.

86
00:05:28,175 --> 00:05:31,195
So, the base URL is always the same,

87
00:05:31,195 --> 00:05:34,445
I'm going to create a blank parameters dictionary.

88
00:05:34,445 --> 00:05:39,605
Then I'm going to fill in rel_rhy should equal word,

89
00:05:39,605 --> 00:05:42,200
and max should be three.

90
00:05:42,200 --> 00:05:45,670
We were asking it to only give us three results back.

91
00:05:45,670 --> 00:05:50,910
Then I call requests.get passing in that params dictionary.

92
00:05:50,910 --> 00:05:53,755
I get a response object.

93
00:05:53,755 --> 00:05:59,530
I turn that into a Python object by calling the JSON method on it,

94
00:05:59,530 --> 00:06:04,400
and now, I'm going to use a list comprehension which you learned about recently.

95
00:06:04,400 --> 00:06:11,125
We're iterating through each of the list of dictionaries.

96
00:06:11,125 --> 00:06:13,065
For each of those dictionaries,

97
00:06:13,065 --> 00:06:16,380
we're just extracting the word.

98
00:06:16,380 --> 00:06:20,855
So, that produces a list like this,

99
00:06:20,855 --> 00:06:24,505
and then I'm just returning it.

100
00:06:24,505 --> 00:06:27,520
I just noticed that on line 13,

101
00:06:27,520 --> 00:06:31,085
I have another return statement where it's returning something different,

102
00:06:31,085 --> 00:06:35,135
but of course, once we execute the return on line 12,

103
00:06:35,135 --> 00:06:37,735
we won't ever do line 13.

104
00:06:37,735 --> 00:06:40,850
That's left over from a previous version I was

105
00:06:40,850 --> 00:06:44,310
trying to do of this where instead of extracting just the words,

106
00:06:44,310 --> 00:06:47,120
I was returning the whole dictionaries.

107
00:06:47,120 --> 00:06:50,550
In fact, it might be instructive to look at that.

108
00:06:50,720 --> 00:06:53,485
Let's comment out line 12,

109
00:06:53,485 --> 00:06:56,465
and see what happens if we return the dictionaries rather than

110
00:06:56,465 --> 00:07:00,920
extracting just the words from those dictionaries.

111
00:07:00,920 --> 00:07:05,240
So, now we get a list of the three dictionaries.

112
00:07:05,240 --> 00:07:08,030
Instead of just getting money, honey, and sunny,

113
00:07:08,030 --> 00:07:15,000
we're getting this whole dictionary instead of just the word money.

114
00:07:15,830 --> 00:07:19,130
So, this is the kind of thing that's pretty helpful if you

115
00:07:19,130 --> 00:07:21,680
know that you're going to do the same thing,

116
00:07:21,680 --> 00:07:24,740
make a bunch of requests to the same API,

117
00:07:24,740 --> 00:07:27,590
just passing a little different parameter each time,

118
00:07:27,590 --> 00:07:29,570
you might want to make a little function out of it like I did

119
00:07:29,570 --> 00:07:32,140
here on lines four through 13.

120
00:07:32,140 --> 00:07:36,830
That's an introduction to reading the documentation for REST API,

121
00:07:36,830 --> 00:07:41,180
and also to making a function to repeatedly make similar kinds

122
00:07:41,180 --> 00:07:46,440
of requests to a single API. We'll see you next time.