How to use APIs with Node-RED: OpenWeatherMap Example

[Music] in this video i'll be taking a start to finish look at how to use application programming interfaces or apis with node-red apis are really common and extremely powerful way of communicating with different devices and services this includes all of our groov series devices and many more cloud services than i could possibly list today i'm going to be looking at how to use node-red running on this groov rio to control an outdoor light it'll turn on when the sun sets and turn back off when the sun rises i'll be simulating that outdoor light with this red stack light since it's a simple digital output example i'll be getting the weather data from an api service called open weather map and even though specifically i'm going to be looking at a weather service today the process that i go through to figure out how to use the api what the endpoints are and what the process is with node-red that's all going to be pretty similar across many different apis that are available especially ones that use json formatting which we'll take a look at a little bit later on in the video however rather than starting right away with the node red flow we're actually going to be taking a look at the api itself and then work our way forwards until we're ready to come into node-red so let's dive right in i'll start by opening a new tab and go to the weather services page at openweathermap.org here you can see we have this landing page that shows us some basic weather data for some location and you can just get your weather data from right here but we want to automate this so to use the api i will have to sign in just come up to the top right select sign in and log in if you don't already have an account it's really easy to make a free one just click create an account fill out this form and click create an account you will have to do email confirmation open up your email and confirm that you've got access to it before you can log in but once you've done that you'll be able to get right in i already have an account so i'll log in right away once you're logged in you'll land on this page right here it shows you the different services that they have available which it's pretty rich but we're going to start with this api link up here at the top of the site just select that and you'll see all the different endpoints that you have available today we're just going to be focusing on this current weather data since we just need the sunrise and sunset for today but you also might be interested in this one call api over here on the right of special interest is this daily forecast for seven days if you didn't just want to know some current information and you wanted to actually create a weather dashboard this would be really good information because you can see seven days ahead for now let's just click this api doc link under current weather data and see what we have available you can get your weather for pretty much any location on earth and you can do that by the city name the city id geographical coordinates like latitude and longitude or the zip code today just to keep things simple we'll do it by city name and right away we can see what the api call is going to look like and what parameters we can change in that call let's copy this to our clipboard and bring open a text editor so we can get started here i'm just going to keep things simple today and use notepad here in notepad i'll just paste in my string and we'll see what we can change the two required parameters you can see here q the city name is required and the app id is also required let's start with the city name i will need to replace both of the curly brackets on either side of this as well as the city name inside of it and i'm going to type in temecula since that's where i'm at in the opto headquarters i'll also need to provide my api key we'll see why this is important in a moment for now let's just go and get that you can see it lists and tells us exactly where to get that it's just under the api key tab but you can also find that anytime by just clicking the drop down next to your username and opening api keys i'll open that in a new tab because we will want to come back here and we'll see that i have a default api key already set up for me this is generated as soon as i create my account i can temporarily disable this or change the name of it for example i could name it something different like node-red and click save and you also have the option to create new keys for example i could have an alternate key for other purposes when i click generate you can see that drops down as well and that gives me the option to delete keys it's pretty common that you can't delete your only key when you only have one that's that's pretty common with apis but now that i have two i may share this alternate key with other people and if i decide i want to cut them off i can just go ahead and click that x here we'll see why you might want to cut people off in a moment for now let's just grab this entire key copy it to our clipboard and replace that api key here in our text editor now that's really the minimum we need to do we have our two required fields so we can actually already go ahead and see weather data let's go ahead and make that request i'll copy this whole string to my keyboard and i don't even need to take it into node-red or some api service like postman i can do this right here in my browser since this is just an http request let's open a new tab paste that in and see what we get right away you can see i get this nicely formatted data you may not see this though if i click view source this is more likely what you will see in your browser the reason i saw it nicely formatted is i have a browser extension called pretty print that shows it in a nicely formatted format here you can see the json formatting in its raw just a big long string this is what your computer consumes but it's really easy to parse and break it down for the individual information because json uses these curly brackets to define different objects you can see one at the start and one at the end then you have a sub-object here another sub-object here and so on you can see that it's a very structured data format so that's pretty much the point of javascript object notation or json for now let's take a look at this nicely formatted version we can see here we have this cohort these are our coordinates the latitude and longitude for the city we entered we have this weather object that has a id associated with the current conditions main description of what the weather is it's a clear sky today and a more detailed description saying clear sky you also have an icon that's associated with different icons that you can get from open weather map we won't look at that today but it's another good feature and you can also see the main information here but something a little odd here is that it says it's 285.67 degrees but that's certainly not degrees celsius or fahrenheit it's actually in degrees kelvin because we didn't define what units we wanted we left it as the default the same goes for wind 0.45 what in this case it's kilometers but you can actually define that and you do that with the other parameters that you have available to you specifically the units the units defines the units of measurement it defaults to standard which is kelvin and kilometers per hour but you can change it to metric which would be degrees celsius and kilometers per hour and today i'm going to be choosing imperial because that's going to give me degrees fahrenheit and miles per hour so let's add this extra parameter to our string here all you have to do is put in an ampersand type units equals and then whatever you want your units to be in this case imperial i'll change this and do the call again when i paste that in right away there we go we can see it's my temperature is 54.54 degrees and it's currently 1.01 miles per hour i could do this conversion in node-red on the other side but this just changes that and takes that step away one important thing is i've already made two calls to my api and it's really important that you keep track of that if you come back to your product page or to your home page you can select billing plans here and see why it's important that you keep track of your keys and keep track of how many times you're visiting the api here you can see on this free plan that i got by default i can do no more than 60 calls per minute and this is over my entire account not per key so for example if i distribute my two keys and do the same flow with those two keys i am limited to 30 calls per minute if i have three keys and they're all using the same flow i'm limited to 20 calls per minute it's account wide not per key if you need to do more than that you can do paid plans depending on your needs and this may come with additional apn points or different features this is a really common way for apis to handle how often they let you use their service they simply can't provide an infinite number of calls to an infinite number of people that's just simply not sustainable so the api key is not only a way to prove that you have a verified account with this api service it's also a way for them to track your usage so just keep that in mind when you distribute your keys if your key is leaked and people start using it more than you want and you're you're getting blocked you're not getting the responses you want that would be a good reason for you to either temporarily disable or entirely delete your key just be aware that when you do delete your key there is no way to regenerate it anywhere that you do want to use that key you're going to have to go back in and replace it with a new one that you've generated just something to be mindful of and this applies to pretty much every api out there since we do have my data we know what we're looking at and down here we can see we have our sunrise timestamp and our sunset timestamp so the data we want is in this object and we do have other data in the format we want should we so desire quickly before we bring that into node-red let's look at the other options for example this mode option defaults to json formatting which is is what we want to use today json works really well with node-red so the fact that's a default is a good thing however you may want to use xml or html for some reason so you would just set ampersand mode equal xml or html depending on your application then of course you can change your language if you are in a non-english speaking country or serving your data to a non-english speaking country so now that we've seen all of the different parameters we have available we've built a working http endpoint we can go ahead and start using this in node-red i'll copy this to my clipboard and go back to my node-red flow to start i'll be dragging in a simple inject node that will inject my timestamp under message.payload equals the current timestamp what you use to inject really doesn't matter for weather specifically i will have it set to repeat so that i can check the current sunrise and sunset every single day or as often as i want you could for example update your weather forecast page every half an hour or every hour however if i was using some other api i may want it to be triggered by a button press or something coming from a database even the important thing is that you have something to get the flow running in this case we'll be using an inject the next thing we need to do is get our http data from the api to do that we'll use an http request node i'll just drag that into my flow and double click it to configure it i do want to get this weather data although there are many apis including the ones that our groov rio uses that would be able to take a post or a put command for example i could use the api to toggle the stack light on and off for now i just want to get my weather data so that's right that's a good default but i do need to paste in my url one thing to note about the url is that my city right here temecula and my api id are fixed in this configuration anyone that has access to my node-red editor is going to be able to see this information the same goes for anyone that has a backup of this import so if someone has a backup of myflow they can see this as well if you want to keep this more secure or you want to dynamically change your city or api id you can do that if you select the help tab over here on the right you can see that it will take the input message.url so you would just leave this url blank build your string separately hand that in over message.url and you can change it freely for now we'll leave it as this static string but just know that you don't have to have it static you can set it dynamically because i'm using my api id my api key to authenticate this connection and confirm that i can visit this site we don't need to worry about enable secure connection or authentication or anything else here we'll come back to these other options in a moment for now let's just test this out i'll click done and i do want to see my weather data somewhere so i'll drag in a debug node although my data is going to be returned on message.payload i want to see everything that comes out of this node so i'll double click my debug node and change my output to display the complete message object this means i won't just get message.payload i'll get message.topic the message id and anything else that the http request node provides so i'll click that select done and wire these together i'll manually inject my timestamp on message.payload that'll go into http request and then i'll see everything in the debug pane over here on the right now i just select deploy to save the changes i made and view my debug pane there's nothing here yet because we haven't injected but as soon as i do it'll reach out make the request and here we go we've got our message id right here and our payload topic and status code and headers the headers aren't really important they're just part of the http request and the response url is just the url that responded to our request you'll notice though that the payload isn't that nicely formatted javascript that you can see in my browser here it's broken down into each of the objects really nicely and it's very readable it's actually that raw string that you might see in your browser the reason is is because it hasn't interpreted this string as json because we told the http request node just to return a utf8 string you can convert any string into json if it's a valid json string by just using the json parser here under parsers i could drag that in drop it between these two nodes and that would do the conversion for me but what's cool is the http request node has that built in under return i just select that drop down and it can return a parse json object right here within the node i'll select that click done collapse this object and deploy because i did make a change now when i inject we'll see this drop down here and my payload is now an object not just a string when i drop that down we can see all of our data here in this nicely formatted object we have our weather object here that has that nice conditions information we have our wind information in miles per hour and of course under sis we have the ever important sunrise and sunset if you're having trouble drilling down and how to actually get this sunrise you have some really nifty tools over here on the right the furthest right icon will pin that open so i can pin my sunrise in sunset and then when i inject again i don't have to drill down and select them again they'll automatically be open to message.payload.cis and you can see your sunrise and sunset highlighted right there if i wanted to copy this timestamp right here i you would use the next one over that copies it to my clipboard and then of particular interest is this third one from the right and that copies the path to this particular property if i select that we can actually drag in a completely new node to view just that property let's do that now i'll double click this and i'll instead of outputting message.payload i will paste in that specific path and you can see its message message is the complete object that node red hands from node to node it's dot payload that's a sub object of message then we have the sub object sys and finally the sub property sunrise that's this timestamp here and you'll notice unlike numbers for example 55.6 if i click that nothing happens but if i click the timestamp the node-red debug pane actually detects that it's a time stamp and we can see it in a more human readable format we can see here that the sun rises at 6 53 and it sets at 453 so that's a really nifty feature of node red now that i know i have my sunrise in sunset we actually want to do some data here so let's temporarily disable this node we'll move that down because we'll want to use it a little bit later and we'll make a copy of this so that we can see sunset i just select the node press ctrl c and ctrl v to paste it and we'll set this to sunset now that i have my two pieces of data we will need to compare it to the current time to see if our current time falls between sunrise and sunset meaning it's daytime and we need to turn off the light or if it falls outside of those times thus it's the light needs to be turned on because it's night time in order to do that we will need to get the current time and there's a few different ways to do that but since i'm injecting the time stamp up here at the top why don't we just carry that through and use it at the end of our flow but you'll notice that we injected our timestamp under message.payload if i double click this you can see my message.payload is equal to the timestamp and that's the current timestamp but that didn't survive through this http request node you can see here my output says that my payload is an object and the timestamp is nowhere to be seen the reason for this is that the http request node puts its response on message.payload and that's a problem we're overriding our timestamp but there's an easy work around we just simply put it on a different message property you can see that our topic which is an empty string did survive so let's just move the timestamp from message.payload to message.timestamp to confirm that we'll we'll uh we'll wire that message node back in click deploy clean up our debug plane by hitting this trashcan here and inject once more we will have to enable that node we don't need to deploy for just enabling a node like that we can see here we do have message.timestamp it did survive through and we can see currently it is 1035 and that does fall between the two sunrise and sunset times we just got so we're good to go we know that we have our current time we have our sunrise and we have our sun set one thing you should note though is that not all apis and not all systems use exactly the same format of data you'll notice for sunrise and sunset these are 10 digit long numbers whereas our timestamp from node red is actually 13 digits that's because open weather map provides the data using just second accuracy that's why we have ten digits we have three more digits from node red because it's using millisecond accuracy so these last four three two those numbers are just too much data we don't need those three we need to drop those off because this 13 digit number is always going to be bigger than both of these 10 digit numbers so we basically need to divide this by a thousand to drop off those three extra decimal places for that extra accuracy that node write provides this is really easy to do though we'll just use a simple expression in a change node i'll just drag one in from the function section of the node palette on the left wire that in and double click it to configure it here i don't want to be modifying my message.payload since that holds all of my weather data i want to be modifying my message.timestamp and what i want to do is simply divide it by a thousand i could do this in a function node but there's this feature here where i could set it to an expression within this uh change node so i'll select expression and i'll type in message.timestamp and i'll just divide it by 1000. it's that easy to just modify it and set your timestamp to be the timestamp divided by 1000 i'll click done and wire in this message node to confirm that it's actually working because i did make some changes here i will have to deploy again and select inject you can see now i do have 10 digits here with three decimal places so those 10 digits will fall within these two numbers so we're good to go regarding our format it's important to look at your data in the debug pane before actually putting it into application because it's easy for two different services to provide different for example let me you may have kilometers versus miles you may have degrees celsius versus degrees fahrenheit or in this case seconds versus milliseconds so just take a moment to look at your data before you start actually using your uh your data so now with that done we need to do some simple logic to see if this falls between these numbers or outside of them to determine day time or night time and we will be using that to manage this stack light that you see here on my left let's have a look at that stack light in a moment for now let's work on the logic to do the logic i will be using a switch node this just lets me as the description shows when i hover over it it'll let me route messages based on their property values or sequence position so in this case i want to be comparing the timestamp to sunrise and sunset and decide whether i'm turning something on or off i'll just double click it and make sure that i'm comparing my timestamp property you have a lot of options for comparisons within the switch node if you just select this drop down you can see you have equals not equals less than greater than greater than or equal to and so on the one of the special interest here is the in-between option here we can see if message.timestamp is in between static numbers or in our case message properties just select the drop-down click message and we can put in our sunrise and sunset again i'll use this copy path link over here the furthest to the left icon in the debug pane and paste that in i'll need to do the same for this next one message dot and put in sunset with both of those set i know that if message.timestamp is in between sunrise and sunset it's daytime and it'll get a message out of output 1. now i want to know when it's not in between those two values to do that i can just add another condition this will give me another output and i'll just set this to otherwise right here at the bottom otherwise just mean if you checked the first condition in the second condition and however many conditions you have and it didn't match any of those i still want some output and in this case that output is going to mean it's night time so if it's in between those it's daytime otherwise it's night time to help keep track of what output is doing what you can come over here to the appearance tab over here on the right select that and name your outputs to be a bit more specific for example daytime is when we'll be turning off the light and night time is what we'll be turning on the light so now when i click done i can just hover over the output ports and you'll see there it says day on the top output and night on the second output so now my message is going to come through make that comparison and route my message based on whether it's daytime or night time now it's time to actually turn the light on or off so to do that i could use an http request node but with groov devices there's an easier way we have a node package called groov io that lets you control your i o just using these simple nodes if you don't have these installed or configured or you don't know how to use them go ahead and check the description we have a video that goes completely over how to use those i'll just drag them in since this is a video focused on the api not the groove nodes so i'll just go ahead and use them since i already have them installed and configured this first one is the daytime configuration so i'll need to set it to toggle the light off during the daytime i'll double click it to configure it and use the localhost device configuration i already have set up you may not be toggling something that's connected to a groov device just use whatever is appropriate for your application in this case i am toggling a groove output that's a digital output chain channel state you could be changing many things for example you could be using an analog channel value to control temperature or something like that in this case it's a simple on off light we'll leave it at digital output channel state i do need to know the module index and channel index however so let's open our groovemanage to find out where that is i'll just come to my groove manage page and select i o channels here you can see i have my red stack light right here on digital output number two and it is going to be on module zero you can confirm that up here in the in the url because it is a groov rio it only has that one module so now that i know that it's on digital output 2 on module 0 i can go ahead and toggle it on and as soon as i click that there we go you can see the outside light turn on because it's daytime it shouldn't be on so when i run my flow it will turn it off knowing that it's daytime let's go and get that set up i'll put my module index of 0 my channel index of 2 and i will be turning this to the static value of false or off because i want this one to be turning off when it's daytime so turn light off is what i'm going to name this node i'll go ahead and click done and you can see my node is configured that red triangle has gone away i'll make a copy of this by clicking and pressing ctrl c and control v and we'll just change this to input true because this is when we're going to be turning the light on and we're going to be doing that when we get routed out the night output and that's it that's all we need to do now we'll be injecting making the http request to find our sunrise and sunset time making sure that our timestamp is the correct format using seconds not milliseconds make a decision as to whether it falls in between the sunrise and sunset time and then toggling our light accordingly i'll clean up my debug pane and deploy so that we can see this working we'll see it runs through grabs the data with a http request once i hit inject and there we go the light turned off right away we can confirm this again by coming back to our channel toggling the light off and let's change this to be a regular inject i don't want to be sitting here clicking inject every single time i want to check sunrise or sunset so i'll set it to repeat on an interval this interval is really important to keep track of for example if i were to set it once every second i can only use this one place for my particular api account before i start burning out the number of uses i'm permitted with my free account so one second really is overkill for this demo i'm going to choose something short like 15 seconds but for something like sunrise and sunset you could check it every 15 minutes if you wanted to that would be a really great way to do this or you could check it once a day save the sunrise and sunset values and then just check your current time every 15 seconds what would probably be more realistic is to use 15 minutes in this particular flow that way within 15 minutes of the sun rising you know your light is going to be turned off and within 15 minutes of the sun setting you know your light is going to be turned back on i'm just choosing 15 seconds to make this demo a little quicker with that done i'll clean up my debug pane hit deploy and take my hands away now within 15 seconds it's going to deploy its message make the request to get sunrise and sunset it'll convert the timestamp to the correct format and do the switch for me all completely automatically this is the beauty of apis specifically when it's running on an automation device like the groov rio there you can see the light turned off all on its own now this was just a generic example to show you how to use an api you start with the api the documentation that's provided to you see what your url needs to look like perhaps test it out in your browser and then finally bring it into node-red to confirm your data and actually do some basic control hopefully this example helped and if you have any questions feel feel free to leave a comment here or in our forums at forums.opto22.com we'll have a link for that in the description below thanks for watching you

Channel: Opto Video

Views: 45,329

Keywords: automation, opto 22, opto, opto22, automatizacion y control industrial, groov, groov EPIC, groov RIO, opto 22 groov, IoT, IIoT, Opto programming

Id: dZiqRg0o01E

Length: 28min 5sec (1685 seconds)

Published: Thu Jan 27 2022