We've seen how APIs can have endpoints and we said
that's equivalent to the address of the place that you want to get some data
from, or you want to communicate with.
But APIs also have something called parameters.
And this is a way that allows you to give an input when you are making your API
request so that you can get different pieces of data back,
depending on your input in the same way that we've given different inputs into
the same function in order to get a different outcome.
Coming back to our bank analogy, that's kinda similar to going to the bank
and instead of just asking them for what are your opening hours,
a sort of broad stroke question, you can also pass in a parameter.
For example, you could say, well, what time do you close on Monday?
Or what time do you close on Tuesday?
And this allows you to get these specific piece of information that you're
interested in depending on the input that you provided as a parameter.
Now, not all APIs have parameters. Some are incredibly simple,
like the ISS location API.
But other ones allow you to provide parameters.
And this is a sunrise and sunset API that gives you the time when the sun is
gonna rise and set wherever you may be.
So you have to obviously provide a location so that they can tell you when the
sun is going to rise and set at your position.
We can do that through two parameters, the latitude and the longitude.
And you'll notice that in the API documentation,
they will usually tell you how you should structure your parameter.
So for example, here
the latitude can be specified using a lat key,
and the longitude is lng as the longitude.
And they want those pieces of input as floating-point numbers. Now,
you also see that some parameters are required and others are optional. Just as
we can have optional and required parameters when we create functions,
you have the same thing in APIs.
The optional ones all have a default value.
For example, the date you could provide,
say you wanted to know the sunrise and sunset on a particular day in the future
or in the past, but you can also leave it empty
and it will default to the current date.
Now the endpoint in this case is this particular URL,
api.sunrise-sunset.org/json. But don't worry.
I'll also link to this documentation in the course resources as well.
Let's see how we can get this to work.
I'm gonna comment out all of the things that were related to our ISS location,
and I'm going to use this requests module in order to get the sunrise and sunset
times
because this is going to be really important when we're creating our final
project
because it's almost impossible to spot the ISS in the sky unless it's actually
dark.
So we need to know when the sun is going to go down and when the sun's going to
come back up in order for us to know
if the sky is actually dark enough for us to be able to spot the ISS
traveling in the sky. Let's go ahead and set up another response
which is going to be set up to a request.
And this request is going to get some information from this particular endpoint.
So let's copy that over and make sure that you leave out this final
full stop.
That's just a part of the sentence and not a part of the API endpoint.
So it should look something like this.
And then we're going to get our response to raise an exception if there was an
error status code. So anything other than 200, basically. Now, if I run this
as it is, you can see I already get an exception.
And the exception is a 400
which, if you remember, means bad request.
This server cannot or will not process the request because of something that they
think is your fault. In our case,
the thing that we've done badly is we haven't provided the required parameters.
So how is it supposed to tell us the sunrise and sunset times
if we don't tell it our location? Let's fix this.
Let's create a set of parameters and you can do this by simply creating a Python
dictionary.
Now the keys for the parameters must match the ones specified in the API
documentation.
So it's lat for latitude and lng for longitude.
So let's create those keys as strings,
and then we can provide our latitude and longitude.
So how do we know what is our latitude and longitude? Well,
we've got our good old friend latlong.net.
So here I can type a particular place name. So right now I'm in London.
And if I click find, it will find me on the map and it will tell me what is my
latitude and what is my longitude.
So let's copy these over and let's create them as constants.
So I'm going to have a MY_LAT
which is equal to this as a floating point number.
And then my longitude--
Remember to include any negative signs if you see it.
That's actually a part of the latitude longitude encoding.
So now I can set my lat key to the constant
MY_LAT and the longitude key to the constant MY_LONG.
So these are the values that I got from my latlong.net search and
then I formatted all of this into a dictionary using the keys that were
specified in the API documentation here.
Those are the only two required parameters.
So if we now add this in to our get requests under the argument called params,
then we're now able to run this request again
and you'll see that this time we don't get any exceptions.
So we can assume that everything went swimmingly.
The data that we get back is under the response.json.
So let's go ahead and print out that data and see what we managed to get.
We got a JSON as usual and the JSON contains the sunrise time and the sunset
time, in addition to other things like when is the solar noon,
how long is the day, what is the day length and so on and so forth.
So you can see this one is a lot longer than what we had before. Now,
the two pieces of information that we're interested in is just the sunrise and
sunset times.
If we want to view this JSON data in a nicely formatted way,
then we can do that by putting the full request into the browser URL bar. And the
way that you format parameters in a URL string
looks something like this. In the sample requests,
they've shown you that this part is the end point URL.
And then afterwards you can add a question mark to denote that you're going to
add some parameters.
And then you add each parameter with the key equal sign and then the value
and then you can tag on more parameters with the ampersand or the and symbol.
So let's try putting this into our browser bar.
So here's the latitude which we'll paste in here
and here's the longitude which we'll paste in here.
So now let's hit enter and you can see there our JSON Awesome
Viewer which we installed at the beginning of today's lessons is now active
and it's showing us all of this data in a much nicer format.
So we can see that this sunrise time that we're interested in is the value for the
key sunrise which is then inside of another key called results.
So we can use these two keys to pull out these specific pieces of data that
we're interested in. So we can get the sunrise
which is equal to data, and then square brackets
we put in the first key
which is results
with an s and then we can add the next key
which is sunrise.
And we can do the same thing for the sunset time.
And now if we print out our sunrise or our sunset time,
you can see its actually the exact piece of information that we're interested
in. Notice how this data is formatted
and it's giving us the time in a 12-hour format.
So it's going to have AM or PM tagged on at the end.
Now what we want to do is we want to be able to get the current time so we can
use the datetime module. From the datetime module, we'll import the date
time in class.
And then we can get the time now by tapping into that class and then calling the
now method.
But you'll notice that the format of time now is very different from our sunrise
and sunset time. Our sunrise and sunset time
are in the 12 hour format
whereas the time that we're getting back from datetime is in a 24-hour clock
format.
So how can we change this data that we're getting back from the sunrise and
sunset API? Well, back to the API
we go. Notice in one of the parameters, there is a parameter called
formatted which is an optional parameter,
but it can be turned off or on.
On is by default,
which means it's going to format it in a particular way with the 12-hour clock.
But if you switch off the formatting,
then it will give you the Unix time in this particular format and this will be a
24-hour clock. So here's your challenge.
Go ahead and change the parameters that you have and make sure that the data
that we get back is not formatted, so it's set to zero.
Pause the video and complete this challenge. Alright,
all we have to do is to add one more parameter to this dictionary and the
parameter must have a key that matches the one specified in the documentation,
so I'm just going to copy that over, and then we're going to set this to 0
for off. So now if we rerun our code,
you can see the data we're getting back is now in Unix time
which is a 12-hour format time.
So currently where I am in London
the sunrise time is actually quite early, it's at four o'clock in the morning.
So notice how the first part is the date
and then we have a T and then after that we've got the time.
What we want to be able to do is to compare this part from our sunrise
sunset API against this part from our datetime API.
So how can we just isolate the hour number from each of these?
Well, we can use a Python method called split,
and you've seen this before.
Basically you have to provide a separator and it will split a string by that
separator creating a list. So if you click on this, try this yourself,
you can see that this string becomes this list by splitting that string with the
pound sign separator. Now, in our case,
the separator that we want to separate by is firstly,
to split it by this T,
which is going to give us this part as the first item in the list and this part
as the second item in the list.
And then we can take the second part and then split it by the colon and then we can
get this first part of the list. So here's how we would do it.
So we can say sunrise.split
and then the separator we want to use was that capital T.
Now if I hit print,
you can see we've got a list that is now separated with two things on either
side of the T. So let me just comment out the time now
and we've got the sunrise and the sunrise split next to each other.
So that T is removed
and the two things on either side have become two items in our list.
Now we want to split this part further.
We can get this item by tapping into the item at index one,
so 0, 1,
and then we can split this even further by tagging on another split function.
Here, we can split it by the colon. So let's go ahead
and provide that as the input.
And now you can see the result we get back is this. We've split the part that
comes after the T by the colon and we've got 04,
03, 32+00, and then 00.
This is clearly the item we want
so all we have to do is just to add a zero at the end.
And now we've got the actual
hour in the 24-hour clock formatted from our sunrise time.
You could in fact,
just simply take all of this part after the sunrise and tag it onto the end of
this line and also this line so that we actually get the sunrise and sunset
times in terms of the 24-hour clock, like this.
Now we're perfectly poised to start comparing it against the time that we're
getting right now.
So we can take our time now and tap into the actual hour,
and you can see now that we've got our sunrise, which is this first number,
sunset, which is the second number,
and the third number is the current clock time in terms of the 24-hour clock.
So in order to figure out whether if it is day or night,
all we have to do is compare this number against these other two.
Now in the next lesson,
we're going to finish off this project and put everything together in order to
get an email when the ISS is passing overhead and it's currently nighttime.
So for all of that and more, I'll see you there.