How do I use the cURL command in a Bash Script?

Using the cURL command in a Bash script can be useful, but why?

We live in the era of APIs…

…you ask for data and you get it back…

But how can you know if your API request is successful?

HTTP response codes are able to tell you that, for example, a successful request is identified by a 2xx code.

A 200 response is a very common 2xx response code you receive when you request data from an API and the API successfully returns data back.

In this tutorial, I want to show you how you can use Bash and cURL to call an API and confirm if the call is successful by reading the HTTP response code.

To follow this tutorial you will need basic knowledge of the Linux command-line.

What is cURL?

This is a tool to request data from a server or to transfer data to a server, using multiple protocols and the protocol we are interested in is HTTP (or HTTPS if you connect to an API protected by SSL).

The cURL command can be used in Linux in many different ways (e.g. to download files).

We will use cURL to retrieve weather information for London via the Open Weather API.

The sample API URL we want to call is:

https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22

Let’s execute the cURL command in the terminal:

curl "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22"

The response we get from the given URL is in JSON format:

{"coord":{"lon":-0.13,"lat":51.51},"weather":[{"id":300,"main":"Drizzle","description":"light intensity drizzle","icon":"09d"}],"base":"stations","main":{"temp":280.32,"pressure":1012,"humidity":81,"temp_min":279.15,"temp_max":281.15},"visibility":10000,"wind":{"speed":4.1,"deg":80},"clouds":{"all":90},"dt":1485789600,"sys":{"type":1,"id":5091,"message":0.0103,"country":"GB","sunrise":1485762037,"sunset":1485794875},"id":2643743,"name":"London","cod":200}

JSON (JavaScript Object Notation) is with XML the most common data format used by APIs to exchange data.

As you can see the response contains data about pressure, humidity, temperature, etc…

The HTTP Response Code

As I said before we want to understand if a call made via cURL is successful.

For that, we have to analyze the HTTP response code we receive when our request is submitted.

Which syntax shall we use?

The cURL –write-out flag can be used to write the HTTP response code to the shell:

curl --write-out "%{http_code}\n" "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22" 

And the response is:

{"coord":{"lon":-0.13,"lat":51.51},"weather":[{"id":300,"main":"Drizzle","description":"light intensity drizzle","icon":"09d"}],"base":"stations","main":{"temp":280.32,"pressure":1012,"humidity":81,"temp_min":279.15,"temp_max":281.15},"visibility":10000,"wind":{"speed":4.1,"deg":80},"clouds":{"all":90},"dt":1485789600,"sys":{"type":1,"id":5091,"message":0.0103,"country":"GB","sunrise":1485762037,"sunset":1485794875},"id":2643743,"name":"London","cod":200}200

You can see that curl displays the HTTP response code at the end of the response, so we are getting near to what we want.

But, how can we remove the JSON data from the response?

We can use the –output flag that allows writing the output of the cURL command to a file instead of stdout. So let’s write the output to a file called output.txt

curl --write-out "%{http_code}\n" "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22" --output output.txt

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                  Dload  Upload   Total   Spent    Left  Speed
100   459    0   459    0     0   2521      0 --:--:-- --:--:-- --:--:--  2550

200 

A lot better, but we also see details about the transfer rate we are not interested in right now.

And what if we want to use the –output flag to avoid showing the JSON response but at the same time we don’t want to create the file output.txt?

How would you do it?

The last thing we want is not to show the transfer report for cURL that was present in the previous output.

To do that we can pass the –silent flag in the command line (keep the same filename).

curl --write-out "%{http_code}\n" "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22" --output output.txt --silent
200

And voilà, we just got the HTTP response code.

It’s a 200 that represents a successful request.

An alternative to the –silent flag is the short version -s. Also, if you want to know other flags supported by curl you can use the -h flag.

curl -h

Using cURL in a Bash Script

Let’s write a Bash script called http_response.sh that writes the output of the cURL command to a variable and then prints the value of the variable to the shell:

#!/bin/bash
   
HTTP_CODE=$(curl --write-out "%{http_code}\n" "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22" --output output.txt --silent)
echo $HTTP_CODE 

When we run the script we get the HTTP response code back:

localhost$ ./http_response.sh 
200 

Conclusion

In this article you have learned how to:

• Use the cURL command to retrieve data from an API (or from any URL in general)
• Print the HTTP response code
• Integrate cURL into a basic Bash script that can be enhanced based on your requirements.

Does it make sense?

Also, if you want to automate multiple calls to an API via curl in your Bash shell scripts you will have to use a while loop.

At the same time, you will also find it helpful to know about the Bash sleep command that allows controlling the number of calls performed against an API in a certain period of time.

Let me know if you have any questions 🙂

And if you want to learn more about curl, here you can find out how to download files using curl.

---

Related FREE Course: Decipher Bash Scripting