As you explore API documentation, you can’t help but bump into curl examples. For the uninitiated, these may look unfriendly and confusing. REST assured (that’s an API joke), it’s not as bad as it looks. Knowing the basics of curl will help you interact with APIs.
Linux Curl Command Linux curl command is used to download or upload data to a server via supported protocols such as HTTP, FTP, IMAP, SFTP, TFTP, IMAP, POP3, SCP, etc. It is a remote utility, so it works without user interaction. The data transfer from one place to another is one of the vital and most used tasks of a computer system. Curl.1 the man page NAME. The command is designed to work without user interaction. As you will see below, the number of features. The URL syntax is protocol-dependent. You'll find a detailed description in RFC 3986. You can specify any amount. The FTP protocol is a command and response protocol; the client sends a command and the server responds. If you use curl's -v option you will get to see all the commands and responses during a transfer. For an ordinary transfer, there are something like 5 to 8 commands necessary to send and as many responses to wait for and read.
One of the reasons that curl is intimidating is because it can be used a lot of different ways. It works with a bunch of data transfer protocols, but for APIs you’ll usually see it use HTTPS and HTTP. That’s the same way that web browsers exchange data. See, this isn’t so foreign after all.
Install curl (You May Already Have It)
You’ll find curl pre-installed on modern Mac OS. Windows 10 and others may also already have curl, depending on how your computer setup. A quick way to check is to open a command line prompt (also called your Terminal):
Curl Cmd
The curl command allows you to download as well as upload data using CLI (the command line) in Linux. This is its syntax: $ curl options URL options - The Curl options starting with one or two dashes.
curl -h
Or on windows:
curl.exe -h
On success, you’ll see a long list of command options. Almost every letter of the alphabet, capital and lowercase, are mapped to commands in curl. That’s one of the things that makes it seem difficult.
If you see an error like:
command not found: curl
That means you’ll need to install curl. You’ll need to download a binary for your operating system. Make double sure you choose a binary option, because getting the source would require you to compile curl on your own system—that’s way more complicated than most people need.
Try the example curl command again with the -h (the help option) to make sure you’re good to go.
Your First curl GET Request
It may seem like hyperbole, but your first curl request is going to space. Well, almost. We’ll be calling the Open Notify API to get the number of astronauts currently outside our atmosphere (likely on the International Space Station).
Try this:curl http://api.open-notify.org/astros.json
After a short time to make the connection, you should receive a result like this:
Don’t worry if that blob of text looks confusing. That’s JavaScript Object Notation (JSON) and is a lightweight way to communicate data structures. Many APIs use JSON responses.
It can be easier to read on multiple lines with the structure shown through indentations:
The number of astronauts in space in this case is three, but your result could be different, because Open Notify is always up-to-date. It also provides additional information on the people in space and where they are.
This simple example uses a curl GET request with no authentication (that is, Open Notify doesn’t require you to identify yourself with an API Key or similar token). As for curl, it assumes a GET request, but you can also explicitly state it with the following command:curl -X GET http://api.open-notify.org/astros.json
GET is an HTTP method used to read data. These simple API calls don’t even require curl—you could load this data directly in your browser.
For more advanced API requests, you’ll start to see the value of curl, so let’s move on to writing data using a POST request.
Can curl POST JSON?
You can use curl to read and write all kinds of data. That’s what it does! You can use JSON, XML, URL encoded data, and more. When using APIs, new data is often written with a POST request. If you’ve ever filled out a form on a website, that data is also sent with the HTTP POST method.
For this POST example, we’ll turn to Stripe, the online payments API. Copy the curl command from its documentation for creating a charge. It will look something like this:
It’s important to copy from Stripe, because they will give you a test token that works. When writing data you almost certainly will need to authenticate, because otherwise anyone could write data anywhere, including in your account. Stripe gets around this to provide a great developer experience by generating test tokens in their documentation—even if you haven’t signed up.
The token is passed with curl’s -u flag, which takes a username and password. In this case, the token is the username and the password (which would be on the other side of the :) is blank.
When you perform the operation, you’ll get back a big blob of JSON. Success! But, even though JSON was in the response, we haven’t quite POSTed JSON yet.
What is -d?
One of curl’s many flags is -d, which sends data along with our request. Because curl can be used in so many different ways, this flag is versatile. It can be used once or multiple times (as Stripe does here). By default, curl will send all -d data bunched together with & separating them. It URL encodes the data as would happen with a form (x-www-form-urlencoded).
In the case of Stripe, this is exactly what they’re looking for! Other APIs may be looking for JSON directly in the body of the data that you POST.
How to POST JSON with curl
You’ll need to do things a little differently to use JSON as part of your API request. Here’s how a hypothetical API call might look with JSON in the data:
In this example (which uses example.com and isn’t live), you’d write a new coffee shop to a place API. The name and place type are sent along in JSON with the -d flag. Note that the entire JSON is wrapped in single quotes, which allows us to use double quotes in the JSON without things getting really ugly.
There’s also some authentication (with the -u flag) and then we also need to tell the server that we’re sending JSON. To do that, we add a new Header with the -H flag.
Take APIs Beyond curl
Now that you’ve made your first GET and POST API requests, take your skills further. Use Twilio, Slack, and (more) Stripe to make and combine API calls. With Hands on APIs for the Casual Coder you’ll get five short and fun lessons to master how APIs work.
Questions About curl?
You’re now familiar with the basics of curl, but might have some questions. I’ve gathered common and anticipated questions below, but feel free to reach out with your own and I’ll try to answer them.
Is curl Always Lowercase?
When you run it from the command line, it’s always lowercase: curl. Additionally, that’s how the creator refers to it and how most others write it, as well. Sometimes it’s given a capital c: Curl.
The only time it’s consistently written with any uppercase letters is for the PHP library, cURL.
What is the difference between wget and curl?
You may already be familiar with another command line utility, wget, which has some similar functionality to curl. The focus of wget is centered on HTTP, HTTPS, and FTP. That means wget is perfectly capable of doing everything shown above.
However, wget only supports basic authentication (username and password), so you might have difficulty accessing APIs with more advanced methods.
What is cURL PHP?
The cURL library in PHP can be used to make API and other calls from your PHP code.
There is more curl than simply the command line utility. The curl command we used above is built on a C library called libcurl. PHP’s cURL is also based on libcurl.
What is cURL in WordPress?
If you’ve dove into WordPress source code, you may have seen cURL mentioned. As WordPress is built on PHP, it uses the cURL library to make its own requests. As of WordPress 2.7, there are helper functions like wp_remote_request you can use instead of calling cURL directly.
What is CURL ?
CURL is a tool for data transfer. It is also available as a library for developers and as a CLI for terminal-based use cases. Both have the same engine inside (Truth is that CLI tool is just the program that uses the library under the hood).
CURL works with every protocol you might have used. Head over this site to check whether CURL works with your target protocol or not.
What CURL can do?
Hmm… Everything that is related to data transfer. Everyone must have used a browser. Even now, you are reading this article through your browser. What browser does, it requests a page and gets it as a response. It can write and read cookies. And then it renders(displaying the content, images and executing JS scripts) it.
CURL can do everything a browser except for the last part rendering because it is not related to data transfer.
As wrap up, CURL can download HTML pages, fill HTML forms and submit them, download files from a FTP/HTTP server and upload files to the same and read/write cookies.
This makes it an excellent tool to be used in scripting, debugging and forensic analysis etc.
Curl command examples
Let’s see what can you do with Curl.
1. Get a response from a server
Everything from server is a response to the request. So getting a HTML page is same as downloading a file.
To get a HTML response from http://info.cern.c,
To get the list of posts as a response from a server ( https://jsonplaceholder.typicode.com/posts),
Since we know how to get a response from a server, you can download a file ( say Google logo ).
Above command will dump binary image data which you can’t view in the terminal. You need to save them and then use a photo viewer to see them.
Note that various option flags can be placed anywhere on the command instead of the strict ordering. So no worry if you placed any option in the last while the examples had the flag in the beginning.
2. Save the file with a default file name
Every file that is served on the internet has a filename. To use the same filename as the downloaded filename use -O flag.
3. Save the file with custom name
To save the filename with your own custom name, use -o flag followed (strictly) by a custom name.
4. Download multiple files
To download multiple files, separate them with a white space.
If you want to use -O flag for all the URL’s, use
The same workaround should be done for any flag. This is because the first occurrence of a certain flag is for the first URL, the second flag is for the second URL and so on.
5. Download a range of files
curl has the in-built ability to download a range of files from the server. This can be illustrated from the following example.
Above command downloads files from logo1.png, logo2.png, logo3.png and up to logo9.png.
6. Download a file only if latest
To download a file only if the file’s modification time is latest than the given time.
7. Resume Downloading
If you have already partially transferred a file, you can resume the transfer by using the -C flag. Offset from which transfer needs to be continued should be passed as a parameter to the -C flag.
Curl Cmd To Post Image To Url
8. Upload a file
To upload a file to the server, one needs to use -T flag followed by the file path on your local system.
9. Delete a file
To delete a file named deleteFile.txt in a server, one can use -X flag which is intended for any HTTP verb/method(like GET, POST, PUT, DELETE, PATCH). Most of the FTP servers will have configured DELETE method if not all advanced HTTP methods.
You can also modify the above command for any HTTP method to do the corresponding task. For Example, if your server allows TRUNCATE method ( this is made-up HTTP method, not a standard one) which removes only the content in the file and not the file, one can use the command similar to the below one.
Above mentioned are the main uses of curl. But there might be difficulties which needed to be fought such as redirects, user authentication, SSL certificates, etc., We can call them add-ons as they are only optional but still remain crucial for certain purposes. Let’s see some of those addons and how to handle it with curl in the next section.
10. Avoid redirects
When you request http://www.google.com , you will be served only the regional page such as www.google.co.in. This is done with the help of redirects (HTTP packets with status codes in the range 300-399).
You can avoid redirects with the option L.
11. Authentication
When the server is configured to serve for only certain individuals with credentials, they will be provided with username and password. One can make login with the help of -u flag.
12. Limit data transfer
If you want to impose a data transfer limit use –limit-rate flag. Following command tries to download the file with rate limit as 10K.
13. Show/Hide transfer Status
If the response is redirected from the terminal such as downloading, uploading then curl automatically shows the status/progress meter for the transfer.
If you do not want to see the progress meter, just append the command with -s flag. Progress will not be shown for response directed for the terminal.
14. Ignore SSL certificates
Do you remember the situations in which you need to give security certificate exception to visit some websites? If you trust the sources and you want to do a data transfer, you can ignore SSL certificate validation by using -k flag.
15. Get Header Information also
To display the header information along with transferred data, use the -i flag.
16. Get Header information Only
If you want only the headers and not the data, use the -I flag
17. Change User Agent
Some websites and servers don’t allow certain kinds of devices to access their systems. But how do they know that we are using a specific kind of device? This is due to the User-Agent HTTP header field. We can change this User Agent with -A flag.
18. Sending data to the Server
If the server needs some data such as token or API key, use -d flag to send the data. Data that needs to be sent should follow the flag in the command. One can use “&” to combine multiple data. This is usually done by GET and POST requests in browsers. This is one of the ways by which you can send your form information.
19. Write Cookies to a File
Cookies are some small information that allows maintaining a session with a stateless HTTP protocol. If you want to know more about Cookies, refer to this great resource.
To write cookies to a file, -c flag followed by the cookie filename should be used.
20. Reading Cookies from a File
To read a cookie from the file, -b flag followed by cookie filename can be used.
Note that -b flag only reads the cookie from the file. So if the server resends another cookie, you might need to use -c option to write them.
21. Start a new Session
If you want to initiate a new session by discarding the cookies, use -j flag. It starts a new session even if you have provided the cookie file to read with -b flag.
Congratulations! You made it to the end. If you find this article useful, share it with your friends and follow us on Social media. If you have any suggestions about this article or any other topic, feel free to drop them below.
Become a Member for FREE
Join the conversation.