WEBVTT
0
00:00.120 --> 00:03.930
We've seen how APIs can have endpoints and we said
1
00:03.930 --> 00:08.820
that's equivalent to the address of the place that you want to get some data
2
00:08.820 --> 00:10.860
from, or you want to communicate with.
3
00:11.430 --> 00:14.310
But APIs also have something called parameters.
4
00:14.760 --> 00:19.760
And this is a way that allows you to give an input when you are making your API
5
00:19.830 --> 00:23.310
request so that you can get different pieces of data back,
6
00:23.460 --> 00:28.140
depending on your input in the same way that we've given different inputs into
7
00:28.140 --> 00:31.170
the same function in order to get a different outcome.
8
00:32.040 --> 00:36.570
Coming back to our bank analogy, that's kinda similar to going to the bank
9
00:36.570 --> 00:40.740
and instead of just asking them for what are your opening hours,
10
00:40.800 --> 00:45.060
a sort of broad stroke question, you can also pass in a parameter.
11
00:45.480 --> 00:48.750
For example, you could say, well, what time do you close on Monday?
12
00:49.110 --> 00:51.720
Or what time do you close on Tuesday?
13
00:52.320 --> 00:56.010
And this allows you to get these specific piece of information that you're
14
00:56.010 --> 01:00.870
interested in depending on the input that you provided as a parameter.
15
01:01.980 --> 01:06.510
Now, not all APIs have parameters. Some are incredibly simple,
16
01:06.540 --> 01:08.700
like the ISS location API.
17
01:09.270 --> 01:12.240
But other ones allow you to provide parameters.
18
01:12.660 --> 01:17.660
And this is a sunrise and sunset API that gives you the time when the sun is
19
01:19.020 --> 01:21.630
gonna rise and set wherever you may be.
20
01:22.110 --> 01:27.110
So you have to obviously provide a location so that they can tell you when the
21
01:27.390 --> 01:30.480
sun is going to rise and set at your position.
22
01:31.080 --> 01:35.490
We can do that through two parameters, the latitude and the longitude.
23
01:36.030 --> 01:38.790
And you'll notice that in the API documentation,
24
01:39.090 --> 01:42.810
they will usually tell you how you should structure your parameter.
25
01:42.990 --> 01:44.160
So for example, here
26
01:44.160 --> 01:48.210
the latitude can be specified using a lat key,
27
01:48.630 --> 01:52.620
and the longitude is lng as the longitude.
28
01:53.100 --> 01:57.750
And they want those pieces of input as floating-point numbers. Now,
29
01:57.750 --> 02:02.750
you also see that some parameters are required and others are optional. Just as
30
02:03.840 --> 02:07.680
we can have optional and required parameters when we create functions,
31
02:07.950 --> 02:10.170
you have the same thing in APIs.
32
02:11.040 --> 02:14.550
The optional ones all have a default value.
33
02:15.180 --> 02:17.970
For example, the date you could provide,
34
02:18.030 --> 02:23.030
say you wanted to know the sunrise and sunset on a particular day in the future
35
02:23.130 --> 02:26.730
or in the past, but you can also leave it empty
36
02:27.090 --> 02:29.370
and it will default to the current date.
37
02:30.360 --> 02:34.680
Now the endpoint in this case is this particular URL,
38
02:35.100 --> 02:39.990
api.sunrise-sunset.org/json. But don't worry.
39
02:40.020 --> 02:44.580
I'll also link to this documentation in the course resources as well.
40
02:45.390 --> 02:47.370
Let's see how we can get this to work.
41
02:47.820 --> 02:52.820
I'm gonna comment out all of the things that were related to our ISS location,
42
02:53.610 --> 02:58.610
and I'm going to use this requests module in order to get the sunrise and sunset
43
02:59.560 --> 03:00.393
times
44
03:00.460 --> 03:04.150
because this is going to be really important when we're creating our final
45
03:04.150 --> 03:04.983
project
46
03:05.290 --> 03:10.290
because it's almost impossible to spot the ISS in the sky unless it's actually
47
03:11.260 --> 03:12.040
dark.
48
03:12.040 --> 03:15.940
So we need to know when the sun is going to go down and when the sun's going to
49
03:15.940 --> 03:18.040
come back up in order for us to know
50
03:18.100 --> 03:22.720
if the sky is actually dark enough for us to be able to spot the ISS
51
03:22.780 --> 03:27.040
traveling in the sky. Let's go ahead and set up another response
52
03:27.100 --> 03:29.650
which is going to be set up to a request.
53
03:30.040 --> 03:35.040
And this request is going to get some information from this particular endpoint.
54
03:35.710 --> 03:40.360
So let's copy that over and make sure that you leave out this final
55
03:40.600 --> 03:41.433
full stop.
56
03:41.530 --> 03:45.070
That's just a part of the sentence and not a part of the API endpoint.
57
03:45.970 --> 03:48.400
So it should look something like this.
58
03:49.180 --> 03:53.530
And then we're going to get our response to raise an exception if there was an
59
03:53.560 --> 03:58.300
error status code. So anything other than 200, basically. Now, if I run this
60
03:58.300 --> 04:01.600
as it is, you can see I already get an exception.
61
04:02.080 --> 04:04.630
And the exception is a 400
62
04:05.110 --> 04:08.500
which, if you remember, means bad request.
63
04:08.650 --> 04:13.650
This server cannot or will not process the request because of something that they
64
04:13.750 --> 04:17.200
think is your fault. In our case,
65
04:17.320 --> 04:22.320
the thing that we've done badly is we haven't provided the required parameters.
66
04:23.320 --> 04:26.440
So how is it supposed to tell us the sunrise and sunset times
67
04:26.830 --> 04:30.550
if we don't tell it our location? Let's fix this.
68
04:31.030 --> 04:36.030
Let's create a set of parameters and you can do this by simply creating a Python
69
04:38.170 --> 04:39.003
dictionary.
70
04:39.400 --> 04:44.400
Now the keys for the parameters must match the ones specified in the API
71
04:44.800 --> 04:45.760
documentation.
72
04:46.180 --> 04:49.960
So it's lat for latitude and lng for longitude.
73
04:50.560 --> 04:53.530
So let's create those keys as strings,
74
04:54.100 --> 04:58.420
and then we can provide our latitude and longitude.
75
04:59.830 --> 05:03.100
So how do we know what is our latitude and longitude? Well,
76
05:03.100 --> 05:05.680
we've got our good old friend latlong.net.
77
05:06.160 --> 05:11.110
So here I can type a particular place name. So right now I'm in London.
78
05:11.470 --> 05:16.470
And if I click find, it will find me on the map and it will tell me what is my
79
05:17.530 --> 05:19.720
latitude and what is my longitude.
80
05:20.140 --> 05:24.490
So let's copy these over and let's create them as constants.
81
05:24.730 --> 05:27.430
So I'm going to have a MY_LAT
82
05:28.180 --> 05:31.750
which is equal to this as a floating point number.
83
05:32.200 --> 05:34.180
And then my longitude--
84
05:35.200 --> 05:38.710
Remember to include any negative signs if you see it.
85
05:39.250 --> 05:42.850
That's actually a part of the latitude longitude encoding.
86
05:43.480 --> 05:47.890
So now I can set my lat key to the constant
87
05:47.920 --> 05:52.360
MY_LAT and the longitude key to the constant MY_LONG.
88
05:52.390 --> 05:56.410
So these are the values that I got from my latlong.net search and
89
05:57.200 --> 06:02.200
then I formatted all of this into a dictionary using the keys that were
90
06:02.360 --> 06:05.780
specified in the API documentation here.
91
06:06.470 --> 06:09.260
Those are the only two required parameters.
92
06:09.710 --> 06:14.710
So if we now add this in to our get requests under the argument called params,
93
06:17.060 --> 06:20.330
then we're now able to run this request again
94
06:20.660 --> 06:23.870
and you'll see that this time we don't get any exceptions.
95
06:24.200 --> 06:27.050
So we can assume that everything went swimmingly.
96
06:28.130 --> 06:32.570
The data that we get back is under the response.json.
97
06:32.930 --> 06:36.830
So let's go ahead and print out that data and see what we managed to get.
98
06:37.760 --> 06:42.760
We got a JSON as usual and the JSON contains the sunrise time and the sunset
99
06:43.700 --> 06:47.360
time, in addition to other things like when is the solar noon,
100
06:47.510 --> 06:51.890
how long is the day, what is the day length and so on and so forth.
101
06:52.280 --> 06:57.260
So you can see this one is a lot longer than what we had before. Now,
102
06:57.290 --> 07:02.090
the two pieces of information that we're interested in is just the sunrise and
103
07:02.090 --> 07:03.260
sunset times.
104
07:03.860 --> 07:08.210
If we want to view this JSON data in a nicely formatted way,
105
07:08.690 --> 07:13.690
then we can do that by putting the full request into the browser URL bar. And the
106
07:15.350 --> 07:18.950
way that you format parameters in a URL string
107
07:19.340 --> 07:22.640
looks something like this. In the sample requests,
108
07:22.670 --> 07:26.660
they've shown you that this part is the end point URL.
109
07:27.110 --> 07:31.100
And then afterwards you can add a question mark to denote that you're going to
110
07:31.100 --> 07:32.660
add some parameters.
111
07:33.200 --> 07:37.640
And then you add each parameter with the key equal sign and then the value
112
07:38.030 --> 07:42.950
and then you can tag on more parameters with the ampersand or the and symbol.
113
07:44.300 --> 07:47.570
So let's try putting this into our browser bar.
114
07:48.020 --> 07:51.290
So here's the latitude which we'll paste in here
115
07:51.620 --> 07:55.940
and here's the longitude which we'll paste in here.
116
07:57.530 --> 08:01.040
So now let's hit enter and you can see there our JSON Awesome
117
08:01.040 --> 08:05.750
Viewer which we installed at the beginning of today's lessons is now active
118
08:06.020 --> 08:10.760
and it's showing us all of this data in a much nicer format.
119
08:11.720 --> 08:16.720
So we can see that this sunrise time that we're interested in is the value for the
120
08:16.730 --> 08:21.260
key sunrise which is then inside of another key called results.
121
08:22.400 --> 08:26.900
So we can use these two keys to pull out these specific pieces of data that
122
08:26.900 --> 08:29.960
we're interested in. So we can get the sunrise
123
08:29.990 --> 08:34.070
which is equal to data, and then square brackets
124
08:34.130 --> 08:35.330
we put in the first key
125
08:35.440 --> 08:37.570
which is results
126
08:37.720 --> 08:40.960
with an s and then we can add the next key
127
08:40.990 --> 08:42.760
which is sunrise.
128
08:43.360 --> 08:47.290
And we can do the same thing for the sunset time.
129
08:48.910 --> 08:53.590
And now if we print out our sunrise or our sunset time,
130
08:53.860 --> 08:58.110
you can see its actually the exact piece of information that we're interested
131
08:58.110 --> 09:02.010
in. Notice how this data is formatted
132
09:02.520 --> 09:06.480
and it's giving us the time in a 12-hour format.
133
09:06.810 --> 09:09.960
So it's going to have AM or PM tagged on at the end.
134
09:10.650 --> 09:15.650
Now what we want to do is we want to be able to get the current time so we can
135
09:16.590 --> 09:21.590
use the datetime module. From the datetime module, we'll import the date
136
09:23.040 --> 09:24.000
time in class.
137
09:24.480 --> 09:29.480
And then we can get the time now by tapping into that class and then calling the
138
09:31.290 --> 09:32.310
now method.
139
09:33.000 --> 09:38.000
But you'll notice that the format of time now is very different from our sunrise
140
09:38.940 --> 09:42.060
and sunset time. Our sunrise and sunset time
141
09:42.090 --> 09:44.370
are in the 12 hour format
142
09:44.700 --> 09:49.500
whereas the time that we're getting back from datetime is in a 24-hour clock
143
09:49.710 --> 09:50.543
format.
144
09:51.150 --> 09:55.860
So how can we change this data that we're getting back from the sunrise and
145
09:55.860 --> 09:58.950
sunset API? Well, back to the API
146
09:58.950 --> 10:03.360
we go. Notice in one of the parameters, there is a parameter called
147
10:03.630 --> 10:06.810
formatted which is an optional parameter,
148
10:07.260 --> 10:10.770
but it can be turned off or on.
149
10:11.310 --> 10:12.540
On is by default,
150
10:12.660 --> 10:17.660
which means it's going to format it in a particular way with the 12-hour clock.
151
10:18.330 --> 10:20.940
But if you switch off the formatting,
152
10:21.330 --> 10:26.330
then it will give you the Unix time in this particular format and this will be a
153
10:28.470 --> 10:33.270
24-hour clock. So here's your challenge.
154
10:33.690 --> 10:38.690
Go ahead and change the parameters that you have and make sure that the data
155
10:39.510 --> 10:44.070
that we get back is not formatted, so it's set to zero.
156
10:44.610 --> 10:49.350
Pause the video and complete this challenge. Alright,
157
10:49.590 --> 10:54.590
all we have to do is to add one more parameter to this dictionary and the
158
10:54.630 --> 10:59.630
parameter must have a key that matches the one specified in the documentation,
159
11:00.480 --> 11:05.070
so I'm just going to copy that over, and then we're going to set this to 0
160
11:05.100 --> 11:08.790
for off. So now if we rerun our code,
161
11:08.970 --> 11:13.050
you can see the data we're getting back is now in Unix time
162
11:13.260 --> 11:16.320
which is a 12-hour format time.
163
11:16.920 --> 11:19.620
So currently where I am in London
164
11:20.070 --> 11:25.050
the sunrise time is actually quite early, it's at four o'clock in the morning.
165
11:25.590 --> 11:28.500
So notice how the first part is the date
166
11:28.830 --> 11:32.220
and then we have a T and then after that we've got the time.
167
11:33.420 --> 11:38.070
What we want to be able to do is to compare this part from our sunrise
168
11:38.070 --> 11:42.750
sunset API against this part from our datetime API.
169
11:43.170 --> 11:47.730
So how can we just isolate the hour number from each of these?
170
11:48.930 --> 11:52.500
Well, we can use a Python method called split,
171
11:53.320 --> 11:55.030
and you've seen this before.
172
11:55.360 --> 12:00.360
Basically you have to provide a separator and it will split a string by that
173
12:01.960 --> 12:06.760
separator creating a list. So if you click on this, try this yourself,
174
12:07.030 --> 12:12.030
you can see that this string becomes this list by splitting that string with the
175
12:13.630 --> 12:17.080
pound sign separator. Now, in our case,
176
12:17.110 --> 12:21.550
the separator that we want to separate by is firstly,
177
12:21.610 --> 12:23.620
to split it by this T,
178
12:24.220 --> 12:29.220
which is going to give us this part as the first item in the list and this part
179
12:29.770 --> 12:31.330
as the second item in the list.
180
12:31.900 --> 12:36.900
And then we can take the second part and then split it by the colon and then we can
181
12:37.150 --> 12:41.080
get this first part of the list. So here's how we would do it.
182
12:41.590 --> 12:44.650
So we can say sunrise.split
183
12:45.340 --> 12:49.270
and then the separator we want to use was that capital T.
184
12:49.930 --> 12:51.340
Now if I hit print,
185
12:51.370 --> 12:56.370
you can see we've got a list that is now separated with two things on either
186
12:57.040 --> 13:01.360
side of the T. So let me just comment out the time now
187
13:01.660 --> 13:05.320
and we've got the sunrise and the sunrise split next to each other.
188
13:05.770 --> 13:07.300
So that T is removed
189
13:07.450 --> 13:11.770
and the two things on either side have become two items in our list.
190
13:12.460 --> 13:14.740
Now we want to split this part further.
191
13:15.130 --> 13:19.330
We can get this item by tapping into the item at index one,
192
13:19.360 --> 13:20.193
so 0, 1,
193
13:20.740 --> 13:25.480
and then we can split this even further by tagging on another split function.
194
13:26.200 --> 13:31.120
Here, we can split it by the colon. So let's go ahead
195
13:31.120 --> 13:32.980
and provide that as the input.
196
13:33.610 --> 13:38.610
And now you can see the result we get back is this. We've split the part that
197
13:40.330 --> 13:44.560
comes after the T by the colon and we've got 04,
198
13:44.560 --> 13:47.860
03, 32+00, and then 00.
199
13:48.310 --> 13:50.200
This is clearly the item we want
200
13:50.230 --> 13:53.890
so all we have to do is just to add a zero at the end.
201
13:54.490 --> 13:56.650
And now we've got the actual
202
13:56.740 --> 14:01.420
hour in the 24-hour clock formatted from our sunrise time.
203
14:02.260 --> 14:03.700
You could in fact,
204
14:03.760 --> 14:08.760
just simply take all of this part after the sunrise and tag it onto the end of
205
14:08.950 --> 14:13.950
this line and also this line so that we actually get the sunrise and sunset
206
14:14.350 --> 14:19.000
times in terms of the 24-hour clock, like this.
207
14:20.380 --> 14:25.380
Now we're perfectly poised to start comparing it against the time that we're
208
14:26.230 --> 14:27.310
getting right now.
209
14:27.970 --> 14:32.740
So we can take our time now and tap into the actual hour,
210
14:33.310 --> 14:37.300
and you can see now that we've got our sunrise, which is this first number,
211
14:37.630 --> 14:39.730
sunset, which is the second number,
212
14:40.120 --> 14:45.120
and the third number is the current clock time in terms of the 24-hour clock.
213
14:46.540 --> 14:49.810
So in order to figure out whether if it is day or night,
214
14:50.110 --> 14:54.200
all we have to do is compare this number against these other two.
215
14:55.160 --> 14:56.360
Now in the next lesson,
216
14:56.390 --> 15:00.920
we're going to finish off this project and put everything together in order to
217
15:00.920 --> 15:05.870
get an email when the ISS is passing overhead and it's currently nighttime.
218
15:06.320 --> 15:08.630
So for all of that and more, I'll see you there.