Instructor: Now, whenever we start using a new API,
the most important thing is to read the documentation.
I know it's really tempting to skip over the instructions
and just get right into it.
I'm also the sort of person who buys a lawnmower
and throws away the instruction manual,
and then two days later something breaks
and I just want to hurt myself
because it would be so much easier
if I had actually read the instruction manual.
But in this case, it is really important.
So let's head over to openweathermap.org together
and let's go to the API section
to see the API documentation.
As you can see,
this API provider actually has several products.
So you could look at the current weather data,
the hourly forecast, the One Call API, the daily forecast,
and a whole bunch of other things.
So each of these have their own endpoints.
And if we take a look at the API doc,
you can see this first one,
the API is api.openweathermap.org/data/2.5/weather.
That's the endpoint.
Whereas the hourly forecast
is pro.openweathermap.org/data/2.5/ forecast/hourly.
So depending on what it is that we need,
we can tap into each of these different APIs.
Let's start off with an easy one.
Let's try and get the current weather data
for the city that we're in.
You can see that this part is the endpoint,
so the URL that we're going to tap into.
And then we have some parameters.
The parameter where we can specify the city name is q.
So that's the name of the parameter
and then we have to provide a value.
Now, in addition, there's another parameter,
which we have to include with all of the API calls
to this particular service, and that is an appid.
We have to get hold of an API key
in order to use this service.
And they show you an example here.
If we click on this URL,
it takes us to samples.openweathermap.org.
And this is just some sample data
where they provided a sample appid.
Now, we can get our own appid for free
by simply signing up to this weather service.
And once you register and sign in,
this is the page that you see.
So we can now go into this section called API keys
and grab our API key here.
So you can create as many keys as you want,
and you can provide a name
that's associated with the final usage for that key.
So I've named it Python.
And now I'm going to copy this API key
and I'm gonna place it into my project.
So I've started a new project called rain_alert,
and inside the main.py, I'm going to create a API key,
and I'm going to save that key that I copied
into a set of double quotes as a string.
Now, once I've got my API key,
I can actually test out this API call.
So I can replace this part with my city name,
which is London, and then I can add my country afterwards
just to make sure that it goes to London, U.K.,
and not London, Ontario, or somewhere else.
And then finally, I'm gonna paste in the API key
that I copied over just now.
And now, when I hit Enter,
and as long as my API key is valid,
I should get a result in the format of my weather data.
Now, I want you to make sure that your API key works as well
by using the same method,
But remember that you have to get hold of your own API key
by signing up to OpenWeatherMap if you want this to work.
Make sure that you replace this part with your own API key.
Otherwise, it's not gonna work.
Now that we've seen that this particular API call
actually works,
let's see what happens if we provide the wrong API key.
So if I just make up an API key and hit Enter,
you can see we get a code back,
which is an HTTP code called 401.
And we can also get a message,
telling us that that's an invalid API key
and we can go to this URL for more info.
Now, remember, in previous lessons,
I mentioned that HTTP status codes
are the codes that we get back
when we try to talk to another server.
So in this case, we got the 401 code back,
which means unauthorized.
And when you get this code back
and you're working with an API,
it usually means that your API key
or your way of authorizing with the API key
is somehow not working.
So that is the thing that you should examine.
We can see that for this particular API provider,
we have to authenticate ourselves with their server
by providing the API key as a parameter.
So now I want to give you a challenge.
I want you to go to OpenWeatherMaps API docs
for their five day weather forecast.
The five day weather forecast
will give you the weather forecast every three hours
based on the location that you provide.
What OpenWeatherMap means by a three-hour forecast
is that they will give you eight weather forecasts per day.
The earliest forecast would be at 3:00 AM,
the next at 6:00 AM, and the one after that is for 9:00 AM,
then one at midday, and so on until midnight.
My challenge to you is to make an API request from PyCharm
using the five day weather forecast
and locate the weather forecast
in the JSON response that you get back.
Now I could tell you exactly what to do,
but it's really good to get some practice
reading API documentation
because after all, in the future,
you're gonna be using loads of different APIs,
and they all have different ways
of working with their services.
Have a look at this page.
I'll link to it in the course resources,
and I want you to implement this API call
by providing a latitude and latitude
of where you currently are,
and make sure that you add your personal appid
by getting hold of your API key.
Now, remember, you can get
your current latitude and longitude
just by going to latlong.net, and then typing a place name,
and then clicking Find.
Don't worry if it tells you a bot is detected,
just go back to the website after a little while
and try again.
At some point,
it should show you your latitude and longitude,
which you can then plug in as a parameter
to this particular API call.
So if you manage to work through all the lessons yesterday,
then this should be a piece of cake for you.
Pause the video and give that a go.
All right, so if that was hard at all,
make sure that you've not skipped yesterday's lessons
because I go through in detail how to hit up a API endpoint,
how to provide parameters,
and how to essentially complete this challenge.
But hopefully you managed all right,
and you're just here to check the solution.
As always, we're gonna start off
by importing our requests package.
Remember that if you are creating this file from scratch
and you haven't downloaded it from a zip file,
then you'll have to install this module manually.
So if you click on it in PyCharm,
you get a little red light bulb.
And then when you click on the down arrow,
you can install that package, simple.
Now, once you've got requests installed,
we can use the GET method to pass in our endpoint.
Now the OpenWeatherMap endpoint
is the one that we see in the API docs.
So it's everything up to
but not including the question mark.
So all of this.
And we can paste that in and save it as a string.
That is what we wanna make our GET request to.
So OWM_Endpoint.
And in addition, we're going to provide some params.
So this is going to determine what kind of data we get back.
And in this case, it's going to be the weather
for a particular location that we're interested in.
Let's create our weather_params,
and this is going to be a dictionary.
And we have to follow the keys
that are provided in the API docs.
So the parameters that we can provide for this API are lats,
which is the latitude, lon, which is longitude.
And a lot of people make typos here
because they add a G. it's actually just L-O-N.
That's the name of the parameter key.
And finally, the appid, which is your API key
that you got earlier on.
In our case, we want to provide a lat, the latitude,
we wanna provide a lon, L-O-N, which is the longitude,
and we also want to provide our appid.
Now our appid is simple.
It's simply the API key that we got earlier on.
And again, just as a reminder, this key is not gonna work.
You'll have to register and get your own for it to work.
Now the latitude we're gonna figure out
by using latlong.net.
So I'm trying to get the weather
for where I currently reside, which is London.
So my latitude is this value and my longitude is this value.
Make sure that you copy everything,
including any negative signs like this.
So these are gonna go in as floating point numbers.
And now that we've completed our weather_params,
we're gonna pass it in to this method.
And now, we can save the output that comes from this
as the response.
And we can print the response.status_code
to see if it was successful.
So now let's go ahead and run our main.py.
And you can see the response code we get back is 200,
which means everything is A-OK.
Now, if you get a response code that's a 401,
that means your API key is probably not valid,
or you've misspelled the name of that key.
It should be appid, all in lowercase,
as they've shown us in their documentation.
If you did get 200 though,
that means everything was successful,
and we can now tap into the actual data.
So let's tap into the response.json
and let's print that out.
So there you have it.
We've got all of the data here
that came back from that API call.
And if you scroll,
there's actually quite a lot of data that's in there.
Now, in order to view this,
it's not very easy to look at it in the console.
So I'm going to triple-click on this
and copy all of that string.
And I'm going to view it in a online JSON viewer.
So I'll link to this as well,
but you wanna paste that JSON you got back
into this and you can see, wow, what a mess.
So much data.
But if you click on Viewer,
then you can see it has nicely formatted
all of that data for us.
So we can easily see the weather forecast
for the next five days.
The forecasts are every three hours,
starting from the time you made your request.
Since there are eight individual forecasts per day
for the whole five days,
you should get back a total of 40 forecasts.
At the bottom of the JSON,
you'll see a location name that's closest
to the latitude and longitude that you provided.
For my coordinates,
that's Abbey Wood in London, United Kingdom.
Going back to the top, I can look at the actual weather.
If I expand the first data point here,
you can see that it gives me a timestamp.
This timestamp format
is the number of seconds that have passed
since January 1, 1970,
which is not very human readable.
So OpenWeatherMap has given us a dt_txt field as well.
If you expand main, you'll see the temperature in Kelvins,
the pressure, the humidity, but also the actual weather.
As you can see from the square brackets,
the weather data comes in a list.
Looking inside, we see this list has a single entry.
Here is where we have our description
of the weather forecast.
It's telling us that the forecast is overcast clouds,
which is pretty normal, if you've ever been to London.
At least it's not raining.
We've now managed to use this OpenWeather app API,
authenticate ourselves with an API key,
and get the required data back from this service.
So in the next lesson,
we're gonna dig into the data that we got back,
and we're going to use it
to figure out whether if it's gonna rain today.
So for all of that and more,
I'll see you on the next lesson.