Build a query string safely

Query values often contain spaces, ampersands, Unicode, or other characters that mean something in a URL. A URL can’t carry them raw. A space must become %20. An & inside a value must become %26. And so on.

Doing that by hand is tedious, and it’s easy to get wrong. Miss one character and the server reads your query differently than you meant.

So don’t do it by hand. Let curl encode each value for you.

Ask curl to build the query string

Send one encoded parameter to an echo endpoint:

curl --get --data-urlencode 'q=network tools' https://httpbin.org/get

Two options work together here. --data-urlencode takes a name=value pair and percent-encodes the value. --get moves that data into the query string instead of sending it as a request body. Without --get, the data options would turn this into a POST.

httpbin echoes back what it received:

{
  "args": {
    "q": "network tools"
  },
  "url": "https://httpbin.org/get?q=network+tools"
}

The value arrived intact. curl turned the space into a safe form on the wire, and the server decoded it back to network tools. You wrote the value once, in its natural form.

Multiple parameters

Repeat the option for each pair:

curl --get \
  --data-urlencode 'q=curl & friends' \
  --data-urlencode 'page=2' \
  https://httpbin.org/get

curl joins the pairs with & in the final URL. The & inside the first value becomes %26, so it stays part of the value instead of splitting the query in two.

I use this every time I test a search endpoint. Typing %20 by hand once is fine. Typing it for a whole sentence with punctuation is where mistakes creep in.

The mistake to avoid

Quote each value. Otherwise the shell splits it, or treats & as “run this in the background”. This command looks close, but it breaks:

curl --get --data-urlencode q=network tools https://httpbin.org/get

The shell splits on the space. tools becomes a separate argument, and curl tries to use it as a URL. You’ll see:

curl: (6) Could not resolve host: tools

That error is your signal. The shell carved up your command before curl ever saw it. Put the whole name=value pair in single quotes and the problem goes away.

Try it with a value that has both a space and an &, then look at the url field in the echo. Every special character should be encoded, and the args value should match what you typed.