Level Of Difficulty: Intermediate
Welcome to this tutorial where you will learn how to make a request to an API inside Integromat and how to use the data retrieved inside your scenario.
The best way to showcase this is with a real API example. Let’s use newsapi.org ( which is an API you can use to retrieve news headlines with)
The data retrieved will be passed on to a Google Sheet. For every news headline, a new row will be created in the Spreadsheet using the Google Sheets > Add a Row module.
The News API website has are many URLs with different endpoints which you can customise depending on the data you want to retrieve.
Let’s make a request in order to obtain the latest Business news in the United States, with ‘us’ set as the country and ‘business’ set as the category.
For this example, the HTTP Request URL will be:
However, with these setup the country and category parameters would be static (would remain the same every time the scenario runs). In order to dynamically define these parameters in the scenario before making the request to the API, let’s use a Google Sheet.
As you can see this Spreadsheet is split up into two sheets. The first sheet contains the parameters that the request URL should contain and the second sheet is where the retrieved news Headlines will be stored.
Let’s enter ‘us’ under the country field and ‘business’ under the category field.
In order to retrieve this data in a scenario and be able to pass it to the HTTP request, a Google Sheet > Search Rows module is required. When the scenario executes, this module searches the ‘Parameters’ sheet and retrieves the first row of data, by default, since no other filtering options have been specified.
Now, let’s set up the HTTP request app which makes the request to the API.
You can leave the URL as it is if you are planning on making an API request with the exact same parameters every time. However, flexibility is always good so let’s make this URL dynamic by mapping the parameters based on the data obtained from the google sheet.
In the country parameter let’s map the country element retrieved from the google sheet and for the category parameter let’s map the category element from the google sheet.
Great! This is now a dynamic URL.
This means that every time this scenario executes, it retrieves the values in the google sheet and applies them to the URL. You can always change these values by changing the data in the google sheet, and therefore obtain different types of data from the API.
One more thing to note is that the URL contains an API key at the end. The News API website requires you to have an account in order to be able to make requests. Once an account is created you obtain a unique API key like this one, which you need to attach as a parameter to all your requests. In this case the API key was automatically added to the URL.
The next option to select is the request method. All the requests that can be made to this API are of type GET. This is because you are always trying to retrieve data.
Therefore let’s select GET as the request method.
Now, let’s introduce the Query String option. This option allows you to split up the API endpoint into smaller, more readable parts.
As you can see, the API endpoint in this example is split up into three parameters. Country, Category and API Key.
You can delete the URL parameters and recreate them the request URL using the Query String option.
The first parameter is the country so ‘country’ will be the name and as a value you can map the google sheets data field created earlier.
You can repeat the same process with the other two parameters, category and apiKey.
This is what your request should look like once the Query String option is fully setup.
Everything now looks much more organised, even though the functionality is still the same.
The last option that is very important to check when making a request to an API is the ‘parse response’ option.
This will automatically convert the data obtained from the API call, to a more ‘Integromat friendly’ format that can be mapped to subsequent modules.
Now, it is a good idea to run the first two modules at this point in order to make sure that everything works as expected, as well as retrieve some sample data that can be mapped to the Google Sheet module at the end.
Save the scenario, right click on the HTTP app and Run It Once.
Once the scenario executes successfully, you can click on the bubble icon above the HTTP request app to see the output data has been parsed and split into news articles where each article is a collection with all the information associated with it.
This data can now be mapped in another module.
Now it’s time to set up the fourth and final module of this scenario in order to organize and display the retrieved data in the Google Sheet.
Before doing that though, it is important to iterate through the array of articles that the HTTP app outputs in order to be able to create a new row on the spreadsheet for every article retrieved.
To do that, simply add the articles array as a value of the iterator module.
Now, in the ‘Google Sheets > Add a Row’ module, the sheet selected this time is ‘News Headlines’.
And then, every row on this sheet will contain all the different fields of data that each retrieved article has.
The first field is Country. The data for this field will be mapped from the first Google sheet module in the scenario. Same for Category. For all the other fields you can map the data from the iterator module.
Now that the scenario is fully configured, you can save it and execute it again. This time your Google Sheet should be filled with all the retrieved data from the News API.
As a final test, you can edit the Parameters sheet and change the category to technology.
If you execute the scenario again this time your News Headline sheet should contain more USA news articles, this time in the technology category.