URL Encoding with cURL: Handle Special Characters

When making HTTP requests with cURL — either from the command line or using libcurl in a programming language — special characters in URLs and form data must be percent-encoded to be interpreted correctly by web servers and APIs. cURL provides built-in mechanisms to handle URL encoding automatically, but knowing when and how to apply them prevents subtle bugs in your requests.

How to Use the URL Encoder Tool

1. Open the URL Encoder on ToolSparkr.
2. Paste the string you need to encode — a search query, API parameter, or path segment — into the input field.
3. Copy the percent-encoded output and insert it into your cURL command or script.
4. For automatic encoding within cURL itself, use the --data-urlencode flag described below.

URL Encoding in cURL with --data-urlencode

The safest way to send special characters in cURL POST data is the --data-urlencode flag, which encodes the value for you:

# cURL automatically encodes the value
curl -X POST https://api.example.com/search \\
  --data-urlencode \"q=hello world & more\" \\
  --data-urlencode \"lang=en\"

# Equivalent manually encoded form
curl -X POST https://api.example.com/search \\
  -d \"q=hello+world+%26+more&lang=en\"

Encoding Query Parameters in a GET Request

For GET requests with special characters in the query string, use --get together with --data-urlencode:

# GET request with encoded query parameters
curl -G https://api.example.com/search \\
  --data-urlencode \"query=price <= $50\" \\
  --data-urlencode \"category=tools & utilities\"

# Resulting URL (cURL encodes automatically):
# https://api.example.com/search?query=price+%3C%3D+%2450&category=tools+%26+utilities

Encoding in Shell Scripts with printf %s

When building URLs dynamically in a shell script, use Python or jq to encode values safely rather than relying on manual substitution:

#!/bin/bash
VALUE=\"hello world & special chars: /?#\"

# Use Python for reliable URL encoding in shell scripts
ENCODED=$(python3 -c \"import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1]))\" \"$VALUE\")

curl \"https://api.example.com/search?q=${ENCODED}\"

Why Use URL Encoding with cURL?

• Correct API calls — Unencoded ampersands, equals signs, and spaces are misinterpreted as parameter delimiters, breaking your request.
• OAuth and authentication — OAuth 1.0 signatures require precisely encoded parameter strings; a single encoding error invalidates the signature.
• Webhook testing — When testing webhooks with cURL, payload values containing special characters must be encoded to reach the handler intact.
• Automation reliability — Scripts that encode values properly handle edge cases like user-supplied input without breaking.

Tips and Best Practices

• Prefer --data-urlencode over manually constructing encoded strings — it eliminates a whole class of encoding bugs.
• Use -v (verbose) with cURL to inspect the actual request URL and headers sent, which helps debug encoding issues.
• Remember that + means space in application/x-www-form-urlencoded format but is a literal plus sign in path segments — always use %2B for a literal plus in query values.
• When testing APIs, tools like ToolSparkr's URL Encoder let you verify encoding visually before embedding values in scripts.

Encode any URL or parameter string instantly with the free URL Encoder on ToolSparkr — no signup or installation needed.