All right. 1
So now that we've gotten an in-depth understanding of Swift protocols and delegates, it's time to work 2
on the heart of the problem of this Clima app which is to work with APIs, so that we can fetch live weather 3
data from across the internet. 4
Firstly, what is an API? 5
Well, it stands for Application Programming Interface. And the official definition is that you can consider 6
it as a set of commands functions, protocols, and objects. And APIs can be used to create software or to 7
interact with an external system. 8
And the beauty of an API is that it provides developers with standard commands for performing common 9
operations so they don't have to write the code from scratch. 10
Now, we've already been using APIs when we've been creating iOS apps, we've been using the APIs that 11
Apple has created. 12
And these are types of APIs that you would use to create software, 13
right? 14
So whenever we went to the docs, we've been getting hold of the API reference. And when we're working 15
with these classes that Apple has created, for example, the AVAudioPlayer, then these are the standard 16
commands for performing common operations, such as playing a sound. 17
Now, in addition to the API that are used to create software, 18
there are also APIs which are used to interact with an external system. 19
So, for example, if you've ever seen in the Tinder app where they have this section called Shared Friends 20
or Shared Interests, where do they get this data from. 21
Well, when you log into Tinder using your Facebook account, Tinder actually ask Facebook for this data 22
so that they can populate it into their app. 23
So effectively, you can consider an API as simply just a contract. 24
It's the contract between the developer and the API provider. 25
So for example, when we're building our weather app, because we need to populate our app with live weather 26
data for all locations across the world, we're going to be using OpenWeather Maps API that they provide. 27
And in this case, by using the API, we're effectively entering in a contract where we say that we'll use 28
the methods that you provide and we'll abide by the rules that you set out in your API docs. And in return, 29
you'll promise to keep all of your requirements the same so that our app doesn't crash because you've 30
changed something. 31
So in this case, we have our app and we have the API provider. And what our app is going to do is it's 32
going to use the API. 33
And when the user types in a city name in our app, we're going to pass that city name to OpenWeather 34
using the API that they have set out for formatting this request, and then OpenWeather in response is 35
going to send us the live weather data, so that we can use it in our app. 36
So if you head over to openweathermap.org/api, you can take a look at the documentation for 37
the API that they provide. 38
So you can get things such as the current weather data, the hourly forecast, the 16 day / daily forecast, 39
and a whole bunch of other things as well. 40
Now, because they are responsible for hosting the data, keeping it updated, they have to make sure that 41
people don't abuse this service. 42
So very often these open APIs will ask you to sign up for an API key, and that key is going to uniquely 43
identify you as a developer. 44
So the first thing that we need to do to work with the API is if it requires an API key, such as 45
OpenWeather Map, then we have to sign up. And it's completely free and they don't need any credit card details. 46
They just want you to create a new account there. Once you signed up, then you should be able to see a 47
page that looks like this. And you should head over to this section called API keys. And here you should 48
be able to see your custom API key that will allow you to use this API service. 49
Go ahead and copy your API key and keep it somewhere safe. 50
And now we're going to see how we can use this API service. So the data that I want is the current weather 51
data. 52
So I'm going to go ahead and click here to take a look at the documentation. 53
You can see that you can get the current weather data for a location by the city name, by the city ID, 54
by geographic coordinates with latitude and longitude, by ZIP code, and a whole bunch of other things 55
that you can read about. 56
Now, in our case, we want to get the weather for a particular city name. 57
So if we go ahead and take a look at their example API calls, you can see that the city name comes after 58
this parameter called queue, and then you also have to supply what's called an app ID, and this is your 59
API key that we got just now. 60
So let's try and structure this API call using our own API key. 61
So first things first, let's go ahead and copy this API call. 62
So it's api.openweathermap.org/data/2.5/weather, and then we have a question 63
mark, 64
and the question mark denotes the beginning of the queries. 65
So these are the queries that you're sending to open weather map. 66
And it's a bit like the inputs to our Swift functions. 67
We have to have a name or a parameter name. 68
So in this case "q" denotes the city name. 69
And then we have an equal sign and then we pass in the name of the city that we want to check the weather 70
for. 71
So let's go ahead and copy this and we're going to paste it into our browser. And I'm going to delete 72
the part where it says city name in brackets because I'm actually going to put the actual name of the 73
city that I'm interested in. 74
So London. Now that I've got my query as London, if I go ahead and hit enter, 75
you'll see I get an error. And it says, "Invalid API key. Please see this address for more information." 76
So once we take a look at this address, you'll see that the problem is because I haven't added in my 77
API key. So I've registered it, 78
I've copied it, but I now have to put it into my query. Ss you can see in the sample query, 79
there is a parameter name called "appid," and after the equals sign, you have to put in your app ID 80
that you got by registering with OpenWeather Map. 81
Let's head over to our URL and let's start off our list of parameters or inputs with the question 82
mark, 83
and then let's add the name of the parameter which is appid all in lowercase, and then equal sign, and then 84
we're going to paste in the appid that we got from OpenWeather Map under the API key section. And 85
then after that, we're going to tag on another parameter or another input. 86
So we're going to use the ampersand to signify that we're done with this app ID parameter input and 87
we're now going to add the "q" parameter which is going to denote the city name. And after the equals sign, 88
I'm going to put in the name the city that I'm interested in which is London. 89
And now if I hit enter, you'll see that I'm getting live data as of this moment right now, 90
what is the weather in London. So cloudy, 91
as usual. Now, if you're not getting this data back, it might be because your app ID or your API key 92
hasn't yet been activated. 93
It usually takes them a couple of hours to do this. 94
So it might be worth coming back and trying it the next day. 95
But for me, it often takes about five to ten minutes before they actually activate my key so it might 96
be worth getting a cup of tea and coming back to try it again later. 97
Now, the second thing you might be wondering is when you're seeing this data come back, you probably won't 98
be seeing it in this pretty sort of tree structure instead. 99
You'd probably be looking at the data that's coming back that looks like this. 100
Now, in order to get it turn into a tree structure which is much easier for us to be able to see and 101
understand as humans, then I recommend getting this free Chrome extension called JSON View Awesome. 102
And once you install it and activate it, then it will automatically detect when you're getting JSON 103
formatted data and it will formatted correctly for you. 104
So now that we've seen that we can structure our API call by adding our different parameters after the 105
URL separated by ampersands, and with the sort of key value kind of format where we have the name of 106
the parameter, an equal sign, and the value that we're sending over to the API provider. 107
So as a challenge, I want you to take a look at the API docs for getting the current weather data. Because 108
you might notice that in the data that we're getting back, the temperature for London is 109
293. 110
So don't worry, I'm not actually burning right now. 111
This is not the temperature in Celsius or Fahrenheit, it's actually in Kelvins which is the scientific 112
unit of measure for temperature. In order to convert it into a number that we actually can understand, 113
OpenWeather Map provides a parameter called units and you can set it to be imperial or metric. 114
So go ahead and update your URL, your API call, so that you have the temperature getting back in either 115
metric, Celsius, or imperial, which is Fahrenheit, depending on whichever one you find easier to understand. 116
All right. 117
So all we have to do to tag on another parameter is to add another ampersand. 118
And in this case, the name of the parameter is units. 119
And remember that when you're adding these parameter names because this is effectively our contract, 120
the API that we're using to get data from OpenWeather Map, you have to make sure that you're spelling 121
it exactly the way that is prescribed by them. 122
Otherwise, they won't know what you're talking about. 123
So the units, in my case, is going to be equal to metric. 124
I can understand Fahrenheit. 125
But now once I put that in, I can see that in London, it's about 9.9 seven degrees, 126
and that feels just about right. At the moment, we're making this request through our browser. 127
How can we do the same thing but from our app? 128
Well, let's get back to our project. 129
And in the model folder, I'm going to create a new file which I'm going to call the WeatherManager. 130
So it's going to be a new Swift file and I'm going to name the file WeatherManager. And inside this 131
brand new file, 132
we're going to create a struct which is called WeatherManager. And one of the first properties we're 133
going to create in our WeatherManager is going to be the weatherURL. 134
And in my case, I'm simply going to copy exactly what I have in my browser at the moment and I'm going 135
to paste it in here as a string. 136
Now, the part of this URL that is going to change is going to be this London input because I'm 137
going to use different cities depending on whatever the user typed in. 138
So notice how you can actually arrange each of these parameters in the URL in any order you like. 139
You can have units equals metric, then q equals London, that works, or you could even have the appid 140
right at the end, like so, 141
and it would work. 142
It doesn't actually care about the order. It looks for the keys and gets the values. 143
So in our case, I'm actually going to get rid of this and "&a=london" because I'm going to add that 144
programmatically a little bit later on using what the user typed into the UITextField. So I can create 145
a method in my WeatherManager called fetchWeather, and this takes an input which is going to be the 146
cityName. 147
And that's, of course, going to be a string data type. And then inside this method, I'm going to create 148
the URL string and it's going to be a combination of the base string which is the weatherURL 149
we've got up here. And then at the very end, I'm going to tag on another ampersand, the "q," which is 150
the parameter name, the equal sign, 151
and then in the string interpolation, I'm going to insert the cityName. So now I should be able to go 152
into my WeatherViewController and create a new weatherManager, and set it equal to a new WeatherManager struct, 153
and initialize it with a set of parentheses. 154
And when my textFieldDidEndEditing and before I reset the FextFields.text, I'm going to use the 155
text in the text field. So I'm going to write let city = searchTextField.text. 156
And because this property is an optional and I want to actually pass over to my WeatherManager a definite 157
string, instead of an optional string, I'm going to use an "if let" to optionally unwrap 158
my searchTextField.text property. 159
So now my city property is a proper string and I can use it when I call where the weatherManger.fetchWeather 160
and the cityName is this city that the user has entered. 161
So now if you want to assure yourself that everything is working, you can actually create a print statement 162
that prints out the URL string. And when you run the app 163
and you type in a city name and hit either the search button or the go button, you should see the final 164
URL that's been formatted together. So you see this entire weatherURL up to here, 165
metric, 166
and then we tag on the "&q=Paris" And just as a safety check, we can copy this and paste it into 167
our browser and check to make sure that it actually works. 168
Now, all that's left to do is to go across the internet from our app and fetch the actual data back. 169
And that is something called networking which is what we're going to talk about in the next lesson. 170
So I'll see you there.