A codificação de URL explicada

Copie uma URL com um termo de busca dentro e você verá com frequência algo como %20 ou %C3%A9 onde deveria haver um espaço ou uma letra acentuada. Isso é a codificação de URL em ação. Este guia explica o que ela faz, por que é necessária e quais caracteres são escapados.

O que é a codificação de URL

A codificação de URL — também chamada de codificação por porcentagem (percent-encoding) — é um jeito de representar numa URL caracteres que de outra forma seriam inseguros ou ambíguos. Cada caractere desses é substituído por um % seguido do seu valor de byte em hexadecimal. Um espaço vira %20; um e comercial vira %26.

Por que é necessária

As URLs só podem conter um conjunto limitado de caracteres, e alguns deles têm papéis especiais: ? inicia a string de consulta, & separa parâmetros, / separa segmentos de caminho e # marca um fragmento. Se um valor que você põe numa URL contém um destes, ele precisa ser codificado para ser tratado como dado, não como estrutura.

Search term:  cats & dogs
In a URL:     ?q=cats%20%26%20dogs

Sem codificação, o & cru seria lido como o começo de um novo parâmetro, e a busca quebraria.

Caracteres reservados vs. não reservados

• Caracteres não reservados (Unreserved) — letras, dígitos e - _ . ~ — são sempre seguros e nunca precisam de codificação.
• Caracteres reservados (Reserved) — como ? & / # : @ = — têm significado especial e precisam ser codificados quando usados como dados literais.
• Todo o resto — espaços, letras acentuadas, emoji e a maioria dos símbolos — é codificado com base nos seus bytes UTF-8, e por isso um caractere pode virar vários pares %xx.

Uma confusão comum: o sinal de mais

Na string de consulta de um envio de formulário, os espaços às vezes são codificados como + em vez de %20. Ambos podem significar “espaço” dependendo do contexto, o que faz as pessoas tropeçarem — na dúvida, %20 é sempre seguro.

Codificação de URL vs. Base64

Estas resolvem problemas diferentes. A codificação de URL torna o texto seguro para colocar dentro de uma URL; o Base64 torna dados binários seguros para mover por canais baseados em texto. Às vezes são combinados (Base64URL), mas não são intercambiáveis.

Para codificar ou decodificar um valor, use o codificador de URL, e para separar todos os parâmetros de uma string de consulta, o analisador de string de consulta os divide numa lista legível.