# URL encode: como codificar parâmetros de URL sem quebrar nada

> Codificar uma URL é trocar os caracteres que têm significado especial (como &, =, ? e espaço) por sequências %XX, para que um valor não seja confundido com a estrutura do endereço. Este guia explica a diferença entre encodeURIComponent e encodeURI, por que o espaço às vezes vira + e às vezes %20, e mostra o jeito certo em JavaScript, Python e PHP.

- Endereço oficial: https://pradev.com.br/guias/url-encode-como-codificar-parametros
- Tipo: Guia
- Publicado em: 2026-09-30
- Atualizado em: 2026-09-30
- Autor: Leonardo Gaertner (https://pradev.com.br/sobre)
- Ferramentas: [Codificar e Decodificar URL](https://pradev.com.br/url-encode-decode)

## Por que codificar

Na URL `/buscar?q=pão & café`, o `&` separa parâmetros, então o servidor recebe `q=pão ` e um parâmetro estranho chamado ` café`. Codificado, o valor vira `p%C3%A3o%20%26%20caf%C3%A9` e chega inteiro. Os acentos viram os bytes do UTF-8, cada um como `%XX`.

Para codificar ou decodificar um valor na hora, use o [codificador de URL](https://pradev.com.br/url-encode-decode).

## encodeURIComponent ou encodeURI?

- `encodeURIComponent` codifica tudo que tem significado na URL, inclusive `/`, `?`, `&` e `=`. Use para um valor: um parâmetro, um trecho do caminho.
- `encodeURI` mantém esses caracteres, porque espera uma URL inteira. Use só para corrigir espaços e acentos de um endereço já montado.
- O erro mais comum é usar `encodeURI` em um valor: um `&` dentro dele passa sem codificar e quebra a query string.

## Espaço: %20 ou +?

Os dois existem. Na URL em geral, o espaço é `%20`. No formato de formulário (`application/x-www-form-urlencoded`), usado na query string por `URLSearchParams`, `urlencode` do Python e `http_build_query` do PHP, ele vira `+`.

O problema aparece na leitura: `decodeURIComponent("a+b")` devolve `a+b`, com o sinal de mais. Para ler uma query string, use o leitor da própria linguagem, que entende os dois formatos.

## Em JavaScript

Para montar uma query com vários parâmetros, `URLSearchParams` codifica cada valor e cuida dos separadores:

```javascript
// Um valor dentro da URL (parâmetro, trecho do caminho): espaço vira %20
function codificarParametro(valor) {
  return encodeURIComponent(valor);
}

// A query string inteira, no formato de formulário: espaço vira +
function montarQuery(params) {
  return new URLSearchParams(params).toString();
}

// Ler a query string: o URLSearchParams entende tanto + quanto %20
function lerQuery(query) {
  return Object.fromEntries(new URLSearchParams(query));
}
```

_JavaScript. Funciona no navegador e no Node.js._

## Em Python e PHP

No Python, `quote` deixa a barra sem codificar, a não ser que você passe `safe=""`. No PHP, prefira `rawurlencode`, que usa `%20`, a `urlencode`, que usa `+`.

```python
from urllib.parse import parse_qsl, quote, urlencode


def codificar_parametro(valor: str) -> str:
    return quote(valor, safe="")  # espaço vira %20; sem safe="", a barra passaria


def montar_query(params: dict) -> str:
    return urlencode(params)  # espaço vira +


def ler_query(query: str) -> dict:
    return dict(parse_qsl(query, keep_blank_values=True))
```

_Python_

```php
<?php
function codificarParametro(string $valor): string
{
    return rawurlencode($valor); // espaço vira %20
}

function montarQuery(array $params): string
{
    return http_build_query($params); // espaço vira +
}

function lerQuery(string $query): array
{
    parse_str($query, $params);
    return $params;
}
```

_PHP_

## Cuidados

- Codifique cada valor uma única vez. Codificar de novo transforma `%20` em `%2520`, e o servidor recebe o texto errado.
- Os caracteres `! ' ( ) *` ficam sem codificar no `encodeURIComponent`, mas são codificados no Python e no PHP. Os dois resultados são válidos e decodificam igual.
- Não codifique a URL inteira com `encodeURIComponent`: o `https://` vira `https%3A%2F%2F` e deixa de ser um endereço.
- Dados sensíveis, como senhas e tokens, não devem ir na URL, mesmo codificados: ela fica em históricos e registros de servidores.

## Perguntas frequentes

### Qual a diferença entre encodeURI e encodeURIComponent?

O encodeURIComponent codifica também os caracteres que estruturam a URL, como barra, interrogação, e comercial e igual, e serve para valores. O encodeURI mantém esses caracteres e serve para uma URL inteira.

### Por que o espaço aparece como + em algumas URLs?

É o formato de formulário, usado em query strings. Nele o espaço vira mais. No resto da URL, o espaço vira %20. Os leitores de query string das linguagens entendem as duas formas.

### URL encode é o mesmo que Base64?

Não. O URL encode troca só os caracteres especiais por %XX e mantém o resto legível. O Base64 converte todos os bytes para outro alfabeto.

### Como os acentos ficam na URL?

Cada letra acentuada vira os bytes do UTF-8 codificados. O ã, por exemplo, vira %C3%A3. Os navegadores costumam mostrar a letra na barra de endereço, mas enviam a forma codificada.

## Fontes

- [RFC 3986: sintaxe de URI](https://www.rfc-editor.org/rfc/rfc3986)
- [MDN: encodeURIComponent](https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)

## Guias relacionados

- [Base64 com acentos: como codificar e decodificar sem erro](https://pradev.com.br/guias/base64-com-acentos-utf8): Por que o btoa erra com acentos e emojis e como codificar e decodificar Base64 em UTF-8 e Base64URL em JavaScript, Python e PHP, com código testado.