Qué es la codificación de URLs
Una URL solo puede contener un conjunto reducido de caracteres ASCII: letras sin acentos, dígitos y unos pocos símbolos. Además, algunos de esos símbolos tienen un significado propio: / separa segmentos de la ruta, ? marca el inicio de la query string, & separa parámetros, = une un nombre con su valor y # introduce el fragmento. Para incluir cualquier otro carácter, o para usar uno de esos símbolos como dato y no como delimitador, se usa la codificación porcentual (percent-encoding), definida en el RFC 3986.
La regla es simple: el carácter se convierte a bytes con UTF-8 y cada byte se escribe como % seguido de su valor en dos dígitos hexadecimales. Un espacio es el byte 0x20, así que se escribe %20; la ñ ocupa dos bytes en UTF-8 (0xC3 0xB1) y se escribe %C3%B1; el símbolo € ocupa tres y queda como %E2%82%AC.
Los tres modos y cuándo usar cada uno
La pregunta clave antes de codificar es qué parte de la URL se está armando, porque eso decide qué caracteres hay que proteger:
- Componente (
encodeURIComponent): para un valor suelto que va a ir dentro de una URL, como el valor de un parámetro (?q=…) o un segmento de ruta. Codifica también/ ? & = #, porque dentro de un valor esos caracteres son datos y no deben confundirse con delimitadores. Es el modo correcto en la gran mayoría de los casos. - URL completa (
encodeURI): para una URL entera que ya tiene su estructura armada y solo contiene algún espacio o acento. Respeta todos los delimitadores, así que nunca debe usarse para un valor: si el valor contiene&, el resultado parte el parámetro en dos. - Formulario (
application/x-www-form-urlencoded): el formato con el que los navegadores envían los formularios HTML y el que generaURLSearchParams. Es casi igual al modo componente, pero convierte el espacio en+y codifica además! ' ( ) ~.
Tabla de referencia
Cómo queda cada carácter frecuente en cada modo:
| Carácter | Componente | URL completa | Formulario |
|---|---|---|---|
| espacio | %20 | %20 | + |
& | %26 | & | %26 |
/ | %2F | / | %2F |
? | %3F | ? | %3F |
= | %3D | = | %3D |
# | %23 | # | %23 |
+ | %2B | + | %2B |
: | %3A | : | %3A |
@ | %40 | @ | %40 |
% | %25 | %25 | %25 |
~ | ~ | ~ | %7E |
ñ | %C3%B1 | %C3%B1 | %C3%B1 |
€ | %E2%82%AC | %E2%82%AC | %E2%82%AC |
Dos filas merecen atención. El + literal siempre hay que codificarlo como %2B dentro de un valor, porque del lado del servidor muchas librerías interpretan + como espacio en la query string. Y el propio % se codifica como %25: es la señal típica de una doble codificación, cuando un valor que ya estaba codificado se vuelve a codificar y %20 termina como %2520.
Decodificar y detectar errores
Al decodificar, la herramienta convierte cada secuencia %XX en su byte y reconstruye los caracteres UTF-8. En modo formulario, además, interpreta + como espacio. Si encuentra un % que no está seguido de dos dígitos hexadecimales (por ejemplo, un 100% sin codificar), o una serie de bytes que no forma un carácter UTF-8 válido (una ñ a la que le falta el segundo byte), indica la secuencia exacta y su posición, en lugar del genérico URIError: URI malformed de JavaScript.
Analizar una URL
La segunda parte de la herramienta separa una URL absoluta en sus componentes (protocolo, usuario, host, puerto, ruta y fragmento) y lista los parámetros de la query string ya decodificados, en su orden original y conservando los repetidos. Usa la misma API URL que los navegadores, así que el resultado es exactamente el que vería una aplicación web. Es útil para revisar enlaces largos con parámetros de seguimiento, depurar redirecciones de inicio de sesión o entender qué recibe realmente un servidor.
Errores frecuentes
- Armar URLs concatenando texto.
"https://api.ejemplo.com/buscar?q=" + "pan & vino"produce una URL donde el servidor recibeq=pany un parámetro vacío llamadovino. Hay que codificar el valor con el modo componente o, mejor, construir la URL conURLyURLSearchParams. - Usar
encodeURIpara un parámetro. No codifica&ni=, así que tiene el mismo problema que la concatenación. - Codificar dos veces. Si un valor ya pasó por un codificador, volver a pasarlo convierte cada
%en%25. - Confundir
+y%20. Los dos representan un espacio en una query string de formulario, pero en la ruta de una URL el+es un signo más literal.
El detalle de cada caso, con ejemplos en varios lenguajes, está en la guía Codificación de URLs: percent-encoding, %20 y + explicados.
Privacidad
La codificación, la decodificación y el análisis de URLs se hacen en el navegador. El texto ingresado no se envía a ningún servidor ni queda guardado en la URL de esta página.