# encode\_uri

Encodes a URI by replacing special characters with their UTF-8 percent-encoded equivalents. Preserves characters that are valid in URIs (like `:`, `/`, `?`, `#`, `&`, `=`).

```liquid
{% assign url = "https://example.com/search?q=hello world&category=shoes" %}
{% log url | encode_uri %}
```

Output:

```
https://example.com/search?q=hello%20world&category=shoes
```

#### Syntax

```liquid
{{ url | encode_uri }}
{{ string | encode_uri }}
```

| Parameter | Description                 |
| --------- | --------------------------- |
| `url`     | The URL or string to encode |

#### Characters Preserved vs Encoded

| Preserved (not encoded) | Encoded               |
| ----------------------- | --------------------- |
| `A-Z a-z 0-9`           | Spaces → `%20`        |
| `- _ . ! ~ * ' ( )`     | `"` → `%22`           |
| `; , / ? : @ & = + $ #` | `<` `>` → `%3C` `%3E` |
|                         | `{` `}` → `%7B` `%7D` |
|                         | Non-ASCII → `%XX`     |

#### Examples

**Encode URL with spaces:**

```liquid
{% assign product_name = "Blue Running Shoes" %}
{% assign search_url = "https://store.com/search?q=" | append: product_name | encode_uri %}

{% log search_url %}
```

Output:

```
https://store.com/search?q=Blue%20Running%20Shoes
```

**Build API URL with parameters:**

```liquid
{% assign base_url = "https://api.example.com/products" %}
{% assign query = "summer collection 2024" %}
{% assign full_url = base_url | append: "?search=" | append: query | encode_uri %}

{% http url: full_url as response %}
```

**Encode redirect URL:**

```liquid
{% assign return_url = shop.url | append: "/pages/thank-you?order=" | append: order.name %}
{% assign encoded_return = return_url | encode_uri %}
{% assign checkout_url = "https://checkout.example.com?return=" | append: encoded_return %}

{% log checkout_url %}
```

**Handle international characters:**

```liquid
{% assign city = "München" %}
{% assign url = "https://store.com/locations/" | append: city | encode_uri %}

{% log url %}
```

Output:

```
https://store.com/locations/M%C3%BCnchen
```

**Encode tracking URL:**

```liquid
{% assign tracking_url = "https://carrier.com/track?id=" | append: fulfillment.tracking_number | append: "&name=" | append: customer.name | encode_uri %}

{% log "Tracking URL: " | append: tracking_url %}
```

**Build webhook callback URL:**

```liquid
{% assign callback_data = order.id | append: "|" | append: order.email %}
{% assign callback_url = "https://myapp.com/webhook?data=" | append: callback_data | encode_uri %}

{% json webhook_payload %}
  {
    "callback_url": "{{ callback_url }}"
  }
{% endjson %}
```

**Encode file path in URL:**

```liquid
{% assign file_name = "Report Q1 2024 (Final).pdf" %}
{% assign download_url = "https://cdn.example.com/files/" | append: file_name | encode_uri %}

{% log download_url %}
```

Output:

```
https://cdn.example.com/files/Report%20Q1%202024%20(Final).pdf
```

**Create mailto link:**

```liquid
{% assign subject = "Order Inquiry: " | append: order.name %}
{% assign body = "Hi, I have a question about my order " | append: order.name %}
{% assign mailto = "mailto:support@store.com?subject=" | append: subject | append: "&body=" | append: body | encode_uri %}

<a href="{{ mailto }}">Contact Support</a>
```

#### encode\_uri vs url\_encode

| Filter       | Use Case               | Encodes                            |
| ------------ | ---------------------- | ---------------------------------- |
| `encode_uri` | Full URLs              | Preserves `: / ? # & =`            |
| `url_encode` | Query parameter values | Encodes everything including `& =` |

**Example difference:**

```liquid
{% assign value = "hello&world=test" %}

{{ value | encode_uri }}
{% comment %} Output: hello&world=test (& and = preserved) {% endcomment %}

{{ value | url_encode }}
{% comment %} Output: hello%26world%3Dtest (& and = encoded) {% endcomment %}
```

**When to use which:**

```liquid
{% comment %} Use encode_uri for complete URLs {% endcomment %}
{% assign full_url = "https://api.com/search?q=hello world" | encode_uri %}

{% comment %} Use url_encode for individual parameter values {% endcomment %}
{% assign param_value = "hello&world" | url_encode %}
{% assign url = "https://api.com/search?q=" | append: param_value %}
```

#### Common Use Cases

| Use Case       | Example                                     |
| -------------- | ------------------------------------------- |
| Search URLs    | \`"/search?q="                              |
| Redirect URLs  | Encode return URLs for OAuth flows          |
| API requests   | Encode URLs with dynamic parameters         |
| Tracking links | Encode customer/order data in URLs          |
| File downloads | Encode file names with spaces/special chars |

#### Notes

* Uses JavaScript's native `encodeURI()` function
* Preserves URI structure characters (`:`, `/`, `?`, `#`, `&`, `=`, etc.)
* For encoding individual query parameter values, consider `url_encode` instead
* Handles UTF-8 characters (international text) correctly
* Safe to call multiple times (already-encoded characters won't be double-encoded)
* See also: `url_encode` for encoding query parameter values


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.datajet-app.com/liquid/filters/encode_uri.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.