How to URL Encode POST Data Automatically with cURL

Sending POST requests with URL-encoded data is a common task when interacting with web APIs. This article explains how to use the curl command-line tool to automatically URL-encode your POST payload using the --data-urlencode flag, ensuring your data is formatted correctly without the need for manual conversion.

When sending data using the standard -d or --data flags, curl expects the data to already be URL-encoded. If your data contains spaces, ampersands, or other special characters, sending it raw will break the request.

To solve this, curl provides the --data-urlencode option, which automatically handles the encoding process for you.

Basic Syntax for Key-Value Pairs

To URL-encode a simple key-value pair, use the --data-urlencode flag followed by key=value.

curl --data-urlencode "name=John Doe" --data-urlencode "status=active & happy" https://httpbin.org/post

In this example, curl automatically converts the space in “John Doe” to %20 (or +) and the ampersand in “active & happy” to %26, preventing the server from misinterpreting the query parameters.

Different Formats of --data-urlencode

The --data-urlencode flag is highly versatile and supports several input formats depending on how you structure your data:

  1. content (Value only): URL-encodes the entire string.

    curl --data-urlencode "pure data to encode" https://httpbin.org/post

  2. name=content (Key and Value): URL-encodes the value side only, keeping the key intact.

    curl --data-urlencode "search=red shoes" https://httpbin.org/post

  3. name@filename (Value from a file): Loads the contents of a file, URL-encodes it, and assigns it to the specified key.

    curl --data-urlencode "bio@biography.txt" https://httpbin.org/post

  4. @filename (File content only): Loads and URL-encodes the entire content of a file without a key.

    curl --data-urlencode "@data.txt" https://httpbin.org/post

By utilizing these variations of the --data-urlencode flag, you can safely transmit complex characters and file data via POST requests without worrying about manual percentage-encoding.