URL encoding: qué es, cuándo codificar una URL y cómo hacerlo

Cuando una URL contiene espacios, acentos o símbolos como & y ?, no se puede usar tal cual: hay que codificarla. Esta guía explica qué es el URL encoding, qué caracteres deben escaparse y cuándo usar cada función de JavaScript.

Qué es el URL encoding

El URL encoding (o percent-encoding) convierte los caracteres que no son seguros en una URL en una secuencia % seguida de su valor hexadecimal. Por ejemplo, un espacio se convierte en %20 y el carácter ñ en %C3%B1.

Existe porque las URLs solo pueden contener un conjunto limitado de caracteres ASCII. Todo lo demás (espacios, acentos, emojis, símbolos reservados) debe representarse con esta codificación para no romper la dirección.

Caracteres reservados vs no reservados

No reservados: letras, dígitos, y - _ . ~. Nunca necesitan codificarse.
Reservados: tienen un significado especial en la URL y hay que codificarlos si forman parte de un dato, no de la estructura: : / ? # [ ] @ ! $ & ' ( ) * + , ; =.

Por ejemplo, & separa parámetros (?a=1&b=2). Si el valor de un parámetro contiene un & literal, hay que codificarlo como %26, o romperá la URL.

encodeURI vs encodeURIComponent

JavaScript tiene dos funciones, y elegir mal es un error muy común:

encodeURI("https://web.com/buscar?q=hola mundo");
// → "https://web.com/buscar?q=hola%20mundo"
// Respeta la estructura: NO codifica : / ? & =

encodeURIComponent("hola&mundo");
// → "hola%26mundo"
// Codifica TODO, incluidos los reservados

La regla:

encodeURI para una URL completa (respeta ://, ?, &).
encodeURIComponent para un trozo que vas a insertar en la URL (el valor de un parámetro). Es la que usarás casi siempre al construir query strings.

Cuándo necesitas codificar

Al meter texto del usuario en un parámetro de URL (búsquedas, filtros).
Al construir enlaces con acentos o espacios.
Al pasar datos en un query string que contienen &, =, + o #.
En APIs que reciben parámetros por URL.

Decodificar: el camino inverso

Para leer una URL codificada y recuperar el texto original, se decodifica con decodeURIComponent. Útil para ver qué contiene realmente un enlace lleno de %20 y %C3.

Puedes codificar y decodificar URLs gratis con el codificador de URL de esta web, que procesa todo en tu navegador.

Errores comunes

Usar encodeURI para un parámetro: no escapa & ni =, así que un valor con esos caracteres rompe la URL. Usa encodeURIComponent.
Doble codificación: codificar algo ya codificado convierte %20 en %2520. Codifica una sola vez.
El + y los espacios: en query strings antiguos, un espacio puede ser + en vez de %20. Depende del contexto; al decodificar formularios, tenlo en cuenta.

Preguntas frecuentes

¿Por qué aparece %20 en las URLs? Es un espacio codificado. Los espacios no son válidos en una URL.

¿Cuál uso, encodeURI o encodeURIComponent? Para una URL entera, encodeURI. Para el valor de un parámetro, encodeURIComponent (lo más habitual).

¿Se suben mis datos al codificar? No, si usas una herramienta local. Todo ocurre en tu navegador.

Codifica y decodifica URLs al instante con el codificador de URL gratis, 100% en tu navegador.