1 00:00:00,120 --> 00:00:03,930 We've seen how APIs can have endpoints and we said 2 00:00:03,930 --> 00:00:08,820 that's equivalent to the address of the place that you want to get some data 3 00:00:08,820 --> 00:00:10,860 from, or you want to communicate with. 4 00:00:11,430 --> 00:00:14,310 But APIs also have something called parameters. 5 00:00:14,760 --> 00:00:19,760 And this is a way that allows you to give an input when you are making your API 6 00:00:19,830 --> 00:00:23,310 request so that you can get different pieces of data back, 7 00:00:23,460 --> 00:00:28,140 depending on your input in the same way that we've given different inputs into 8 00:00:28,140 --> 00:00:31,170 the same function in order to get a different outcome. 9 00:00:32,040 --> 00:00:36,570 Coming back to our bank analogy, that's kinda similar to going to the bank 10 00:00:36,570 --> 00:00:40,740 and instead of just asking them for what are your opening hours, 11 00:00:40,800 --> 00:00:45,060 a sort of broad stroke question, you can also pass in a parameter. 12 00:00:45,480 --> 00:00:48,750 For example, you could say, well, what time do you close on Monday? 13 00:00:49,110 --> 00:00:51,720 Or what time do you close on Tuesday? 14 00:00:52,320 --> 00:00:56,010 And this allows you to get these specific piece of information that you're 15 00:00:56,010 --> 00:01:00,870 interested in depending on the input that you provided as a parameter. 16 00:01:01,980 --> 00:01:06,510 Now, not all APIs have parameters. Some are incredibly simple, 17 00:01:06,540 --> 00:01:08,700 like the ISS location API. 18 00:01:09,270 --> 00:01:12,240 But other ones allow you to provide parameters. 19 00:01:12,660 --> 00:01:17,660 And this is a sunrise and sunset API that gives you the time when the sun is 20 00:01:19,020 --> 00:01:21,630 gonna rise and set wherever you may be. 21 00:01:22,110 --> 00:01:27,110 So you have to obviously provide a location so that they can tell you when the 22 00:01:27,390 --> 00:01:30,480 sun is going to rise and set at your position. 23 00:01:31,080 --> 00:01:35,490 We can do that through two parameters, the latitude and the longitude. 24 00:01:36,030 --> 00:01:38,790 And you'll notice that in the API documentation, 25 00:01:39,090 --> 00:01:42,810 they will usually tell you how you should structure your parameter. 26 00:01:42,990 --> 00:01:44,160 So for example, here 27 00:01:44,160 --> 00:01:48,210 the latitude can be specified using a lat key, 28 00:01:48,630 --> 00:01:52,620 and the longitude is lng as the longitude. 29 00:01:53,100 --> 00:01:57,750 And they want those pieces of input as floating-point numbers. Now, 30 00:01:57,750 --> 00:02:02,750 you also see that some parameters are required and others are optional. Just as 31 00:02:03,840 --> 00:02:07,680 we can have optional and required parameters when we create functions, 32 00:02:07,950 --> 00:02:10,169 you have the same thing in APIs. 33 00:02:11,039 --> 00:02:14,550 The optional ones all have a default value. 34 00:02:15,180 --> 00:02:17,970 For example, the date you could provide, 35 00:02:18,030 --> 00:02:23,030 say you wanted to know the sunrise and sunset on a particular day in the future 36 00:02:23,130 --> 00:02:26,730 or in the past, but you can also leave it empty 37 00:02:27,090 --> 00:02:29,370 and it will default to the current date. 38 00:02:30,360 --> 00:02:34,680 Now the endpoint in this case is this particular URL, 39 00:02:35,100 --> 00:02:39,990 api.sunrise-sunset.org/json. But don't worry. 40 00:02:40,020 --> 00:02:44,580 I'll also link to this documentation in the course resources as well. 41 00:02:45,390 --> 00:02:47,370 Let's see how we can get this to work. 42 00:02:47,820 --> 00:02:52,820 I'm gonna comment out all of the things that were related to our ISS location, 43 00:02:53,610 --> 00:02:58,610 and I'm going to use this requests module in order to get the sunrise and sunset 44 00:02:59,560 --> 00:03:00,393 times 45 00:03:00,460 --> 00:03:04,150 because this is going to be really important when we're creating our final 46 00:03:04,150 --> 00:03:04,983 project 47 00:03:05,290 --> 00:03:10,290 because it's almost impossible to spot the ISS in the sky unless it's actually 48 00:03:11,260 --> 00:03:12,040 dark. 49 00:03:12,040 --> 00:03:15,940 So we need to know when the sun is going to go down and when the sun's going to 50 00:03:15,940 --> 00:03:18,040 come back up in order for us to know 51 00:03:18,100 --> 00:03:22,720 if the sky is actually dark enough for us to be able to spot the ISS 52 00:03:22,780 --> 00:03:27,040 traveling in the sky. Let's go ahead and set up another response 53 00:03:27,100 --> 00:03:29,650 which is going to be set up to a request. 54 00:03:30,040 --> 00:03:35,040 And this request is going to get some information from this particular endpoint. 55 00:03:35,710 --> 00:03:40,360 So let's copy that over and make sure that you leave out this final 56 00:03:40,600 --> 00:03:41,433 full stop. 57 00:03:41,530 --> 00:03:45,070 That's just a part of the sentence and not a part of the API endpoint. 58 00:03:45,970 --> 00:03:48,400 So it should look something like this. 59 00:03:49,180 --> 00:03:53,530 And then we're going to get our response to raise an exception if there was an 60 00:03:53,560 --> 00:03:58,300 error status code. So anything other than 200, basically. Now, if I run this 61 00:03:58,300 --> 00:04:01,600 as it is, you can see I already get an exception. 62 00:04:02,080 --> 00:04:04,630 And the exception is a 400 63 00:04:05,110 --> 00:04:08,500 which, if you remember, means bad request. 64 00:04:08,650 --> 00:04:13,650 This server cannot or will not process the request because of something that they 65 00:04:13,750 --> 00:04:17,200 think is your fault. In our case, 66 00:04:17,320 --> 00:04:22,320 the thing that we've done badly is we haven't provided the required parameters. 67 00:04:23,320 --> 00:04:26,440 So how is it supposed to tell us the sunrise and sunset times 68 00:04:26,830 --> 00:04:30,550 if we don't tell it our location? Let's fix this. 69 00:04:31,030 --> 00:04:36,030 Let's create a set of parameters and you can do this by simply creating a Python 70 00:04:38,170 --> 00:04:39,003 dictionary. 71 00:04:39,400 --> 00:04:44,400 Now the keys for the parameters must match the ones specified in the API 72 00:04:44,800 --> 00:04:45,760 documentation. 73 00:04:46,180 --> 00:04:49,960 So it's lat for latitude and lng for longitude. 74 00:04:50,560 --> 00:04:53,530 So let's create those keys as strings, 75 00:04:54,100 --> 00:04:58,420 and then we can provide our latitude and longitude. 76 00:04:59,830 --> 00:05:03,100 So how do we know what is our latitude and longitude? Well, 77 00:05:03,100 --> 00:05:05,680 we've got our good old friend latlong.net. 78 00:05:06,160 --> 00:05:11,110 So here I can type a particular place name. So right now I'm in London. 79 00:05:11,470 --> 00:05:16,470 And if I click find, it will find me on the map and it will tell me what is my 80 00:05:17,530 --> 00:05:19,720 latitude and what is my longitude. 81 00:05:20,140 --> 00:05:24,490 So let's copy these over and let's create them as constants. 82 00:05:24,730 --> 00:05:27,430 So I'm going to have a MY_LAT 83 00:05:28,180 --> 00:05:31,750 which is equal to this as a floating point number. 84 00:05:32,200 --> 00:05:34,180 And then my longitude-- 85 00:05:35,200 --> 00:05:38,710 Remember to include any negative signs if you see it. 86 00:05:39,250 --> 00:05:42,850 That's actually a part of the latitude longitude encoding. 87 00:05:43,480 --> 00:05:47,890 So now I can set my lat key to the constant 88 00:05:47,920 --> 00:05:52,360 MY_LAT and the longitude key to the constant MY_LONG. 89 00:05:52,390 --> 00:05:56,410 So these are the values that I got from my latlong.net search and 90 00:05:57,200 --> 00:06:02,200 then I formatted all of this into a dictionary using the keys that were 91 00:06:02,360 --> 00:06:05,780 specified in the API documentation here. 92 00:06:06,470 --> 00:06:09,260 Those are the only two required parameters. 93 00:06:09,710 --> 00:06:14,710 So if we now add this in to our get requests under the argument called params, 94 00:06:17,060 --> 00:06:20,330 then we're now able to run this request again 95 00:06:20,660 --> 00:06:23,870 and you'll see that this time we don't get any exceptions. 96 00:06:24,200 --> 00:06:27,050 So we can assume that everything went swimmingly. 97 00:06:28,130 --> 00:06:32,570 The data that we get back is under the response.json. 98 00:06:32,930 --> 00:06:36,830 So let's go ahead and print out that data and see what we managed to get. 99 00:06:37,760 --> 00:06:42,760 We got a JSON as usual and the JSON contains the sunrise time and the sunset 100 00:06:43,700 --> 00:06:47,360 time, in addition to other things like when is the solar noon, 101 00:06:47,510 --> 00:06:51,890 how long is the day, what is the day length and so on and so forth. 102 00:06:52,280 --> 00:06:57,260 So you can see this one is a lot longer than what we had before. Now, 103 00:06:57,290 --> 00:07:02,090 the two pieces of information that we're interested in is just the sunrise and 104 00:07:02,090 --> 00:07:03,260 sunset times. 105 00:07:03,860 --> 00:07:08,210 If we want to view this JSON data in a nicely formatted way, 106 00:07:08,690 --> 00:07:13,690 then we can do that by putting the full request into the browser URL bar. And the 107 00:07:15,350 --> 00:07:18,950 way that you format parameters in a URL string 108 00:07:19,340 --> 00:07:22,640 looks something like this. In the sample requests, 109 00:07:22,670 --> 00:07:26,660 they've shown you that this part is the end point URL. 110 00:07:27,110 --> 00:07:31,100 And then afterwards you can add a question mark to denote that you're going to 111 00:07:31,100 --> 00:07:32,660 add some parameters. 112 00:07:33,200 --> 00:07:37,640 And then you add each parameter with the key equal sign and then the value 113 00:07:38,030 --> 00:07:42,950 and then you can tag on more parameters with the ampersand or the and symbol. 114 00:07:44,300 --> 00:07:47,570 So let's try putting this into our browser bar. 115 00:07:48,020 --> 00:07:51,290 So here's the latitude which we'll paste in here 116 00:07:51,620 --> 00:07:55,940 and here's the longitude which we'll paste in here. 117 00:07:57,530 --> 00:08:01,040 So now let's hit enter and you can see there our JSON Awesome 118 00:08:01,040 --> 00:08:05,750 Viewer which we installed at the beginning of today's lessons is now active 119 00:08:06,020 --> 00:08:10,760 and it's showing us all of this data in a much nicer format. 120 00:08:11,720 --> 00:08:16,720 So we can see that this sunrise time that we're interested in is the value for the 121 00:08:16,730 --> 00:08:21,260 key sunrise which is then inside of another key called results. 122 00:08:22,400 --> 00:08:26,900 So we can use these two keys to pull out these specific pieces of data that 123 00:08:26,900 --> 00:08:29,960 we're interested in. So we can get the sunrise 124 00:08:29,990 --> 00:08:34,070 which is equal to data, and then square brackets 125 00:08:34,130 --> 00:08:35,330 we put in the first key 126 00:08:35,440 --> 00:08:37,570 which is results 127 00:08:37,720 --> 00:08:40,960 with an s and then we can add the next key 128 00:08:40,990 --> 00:08:42,760 which is sunrise. 129 00:08:43,360 --> 00:08:47,290 And we can do the same thing for the sunset time. 130 00:08:48,910 --> 00:08:53,590 And now if we print out our sunrise or our sunset time, 131 00:08:53,860 --> 00:08:58,110 you can see its actually the exact piece of information that we're interested 132 00:08:58,110 --> 00:09:02,010 in. Notice how this data is formatted 133 00:09:02,520 --> 00:09:06,480 and it's giving us the time in a 12-hour format. 134 00:09:06,810 --> 00:09:09,960 So it's going to have AM or PM tagged on at the end. 135 00:09:10,650 --> 00:09:15,650 Now what we want to do is we want to be able to get the current time so we can 136 00:09:16,590 --> 00:09:21,590 use the datetime module. From the datetime module, we'll import the date 137 00:09:23,040 --> 00:09:24,000 time in class. 138 00:09:24,480 --> 00:09:29,480 And then we can get the time now by tapping into that class and then calling the 139 00:09:31,290 --> 00:09:32,310 now method. 140 00:09:33,000 --> 00:09:38,000 But you'll notice that the format of time now is very different from our sunrise 141 00:09:38,940 --> 00:09:42,060 and sunset time. Our sunrise and sunset time 142 00:09:42,090 --> 00:09:44,370 are in the 12 hour format 143 00:09:44,700 --> 00:09:49,500 whereas the time that we're getting back from datetime is in a 24-hour clock 144 00:09:49,710 --> 00:09:50,543 format. 145 00:09:51,150 --> 00:09:55,860 So how can we change this data that we're getting back from the sunrise and 146 00:09:55,860 --> 00:09:58,950 sunset API? Well, back to the API 147 00:09:58,950 --> 00:10:03,360 we go. Notice in one of the parameters, there is a parameter called 148 00:10:03,630 --> 00:10:06,810 formatted which is an optional parameter, 149 00:10:07,260 --> 00:10:10,770 but it can be turned off or on. 150 00:10:11,310 --> 00:10:12,540 On is by default, 151 00:10:12,660 --> 00:10:17,660 which means it's going to format it in a particular way with the 12-hour clock. 152 00:10:18,330 --> 00:10:20,940 But if you switch off the formatting, 153 00:10:21,330 --> 00:10:26,330 then it will give you the Unix time in this particular format and this will be a 154 00:10:28,470 --> 00:10:33,270 24-hour clock. So here's your challenge. 155 00:10:33,690 --> 00:10:38,690 Go ahead and change the parameters that you have and make sure that the data 156 00:10:39,510 --> 00:10:44,070 that we get back is not formatted, so it's set to zero. 157 00:10:44,610 --> 00:10:49,350 Pause the video and complete this challenge. Alright, 158 00:10:49,590 --> 00:10:54,590 all we have to do is to add one more parameter to this dictionary and the 159 00:10:54,630 --> 00:10:59,630 parameter must have a key that matches the one specified in the documentation, 160 00:11:00,480 --> 00:11:05,070 so I'm just going to copy that over, and then we're going to set this to 0 161 00:11:05,100 --> 00:11:08,790 for off. So now if we rerun our code, 162 00:11:08,970 --> 00:11:13,050 you can see the data we're getting back is now in Unix time 163 00:11:13,260 --> 00:11:16,320 which is a 12-hour format time. 164 00:11:16,920 --> 00:11:19,620 So currently where I am in London 165 00:11:20,070 --> 00:11:25,050 the sunrise time is actually quite early, it's at four o'clock in the morning. 166 00:11:25,590 --> 00:11:28,500 So notice how the first part is the date 167 00:11:28,830 --> 00:11:32,220 and then we have a T and then after that we've got the time. 168 00:11:33,420 --> 00:11:38,070 What we want to be able to do is to compare this part from our sunrise 169 00:11:38,070 --> 00:11:42,750 sunset API against this part from our datetime API. 170 00:11:43,170 --> 00:11:47,730 So how can we just isolate the hour number from each of these? 171 00:11:48,930 --> 00:11:52,500 Well, we can use a Python method called split, 172 00:11:53,320 --> 00:11:55,030 and you've seen this before. 173 00:11:55,360 --> 00:12:00,360 Basically you have to provide a separator and it will split a string by that 174 00:12:01,960 --> 00:12:06,760 separator creating a list. So if you click on this, try this yourself, 175 00:12:07,030 --> 00:12:12,030 you can see that this string becomes this list by splitting that string with the 176 00:12:13,630 --> 00:12:17,080 pound sign separator. Now, in our case, 177 00:12:17,110 --> 00:12:21,550 the separator that we want to separate by is firstly, 178 00:12:21,610 --> 00:12:23,620 to split it by this T, 179 00:12:24,220 --> 00:12:29,220 which is going to give us this part as the first item in the list and this part 180 00:12:29,770 --> 00:12:31,330 as the second item in the list. 181 00:12:31,900 --> 00:12:36,900 And then we can take the second part and then split it by the colon and then we can 182 00:12:37,150 --> 00:12:41,080 get this first part of the list. So here's how we would do it. 183 00:12:41,590 --> 00:12:44,650 So we can say sunrise.split 184 00:12:45,340 --> 00:12:49,270 and then the separator we want to use was that capital T. 185 00:12:49,930 --> 00:12:51,340 Now if I hit print, 186 00:12:51,370 --> 00:12:56,370 you can see we've got a list that is now separated with two things on either 187 00:12:57,040 --> 00:13:01,360 side of the T. So let me just comment out the time now 188 00:13:01,660 --> 00:13:05,320 and we've got the sunrise and the sunrise split next to each other. 189 00:13:05,770 --> 00:13:07,300 So that T is removed 190 00:13:07,450 --> 00:13:11,770 and the two things on either side have become two items in our list. 191 00:13:12,460 --> 00:13:14,740 Now we want to split this part further. 192 00:13:15,130 --> 00:13:19,330 We can get this item by tapping into the item at index one, 193 00:13:19,360 --> 00:13:20,193 so 0, 1, 194 00:13:20,740 --> 00:13:25,480 and then we can split this even further by tagging on another split function. 195 00:13:26,200 --> 00:13:31,120 Here, we can split it by the colon. So let's go ahead 196 00:13:31,120 --> 00:13:32,980 and provide that as the input. 197 00:13:33,610 --> 00:13:38,610 And now you can see the result we get back is this. We've split the part that 198 00:13:40,330 --> 00:13:44,560 comes after the T by the colon and we've got 04, 199 00:13:44,560 --> 00:13:47,860 03, 32+00, and then 00. 200 00:13:48,310 --> 00:13:50,200 This is clearly the item we want 201 00:13:50,230 --> 00:13:53,890 so all we have to do is just to add a zero at the end. 202 00:13:54,490 --> 00:13:56,650 And now we've got the actual 203 00:13:56,740 --> 00:14:01,420 hour in the 24-hour clock formatted from our sunrise time. 204 00:14:02,260 --> 00:14:03,700 You could in fact, 205 00:14:03,760 --> 00:14:08,760 just simply take all of this part after the sunrise and tag it onto the end of 206 00:14:08,950 --> 00:14:13,950 this line and also this line so that we actually get the sunrise and sunset 207 00:14:14,350 --> 00:14:19,000 times in terms of the 24-hour clock, like this. 208 00:14:20,380 --> 00:14:25,380 Now we're perfectly poised to start comparing it against the time that we're 209 00:14:26,230 --> 00:14:27,310 getting right now. 210 00:14:27,970 --> 00:14:32,740 So we can take our time now and tap into the actual hour, 211 00:14:33,310 --> 00:14:37,300 and you can see now that we've got our sunrise, which is this first number, 212 00:14:37,630 --> 00:14:39,730 sunset, which is the second number, 213 00:14:40,120 --> 00:14:45,120 and the third number is the current clock time in terms of the 24-hour clock. 214 00:14:46,540 --> 00:14:49,810 So in order to figure out whether if it is day or night, 215 00:14:50,110 --> 00:14:54,200 all we have to do is compare this number against these other two. 216 00:14:55,160 --> 00:14:56,360 Now in the next lesson, 217 00:14:56,390 --> 00:15:00,920 we're going to finish off this project and put everything together in order to 218 00:15:00,920 --> 00:15:05,870 get an email when the ISS is passing overhead and it's currently nighttime. 219 00:15:06,320 --> 00:15:08,630 So for all of that and more, I'll see you there.