URL Encoding for REST API Query Parameters

One of the most common sources of silent bugs in API integrations is incorrect URL encoding. An unencoded ampersand in a search query, a space in a date parameter, or a slash in a file name can corrupt the entire URL, causing the server to receive the wrong data while your code gets back a confusing 400 or empty result set. This guide covers how to encode query parameters correctly in JavaScript.

The problem — unencoded special characters

// Looks fine, but & breaks the query string:
const search = 'oil & gas';
fetch(`/api/companies?industry=${search}`);
// Sends: /api/companies?industry=oil & gas
// Server sees: industry=oil (gas becomes a separate unknown param)

Fix 1 — encodeURIComponent

const search = 'oil & gas';
fetch(`/api/companies?industry=${encodeURIComponent(search)}`);
// Sends: /api/companies?industry=oil%20%26%20gas ✅

Fix 2 — URLSearchParams (recommended)

URLSearchParams handles all encoding automatically and is the cleanest approach for building query strings:

const params = new URLSearchParams({
  industry: 'oil & gas',
  country: 'India',
  minRevenue: 5000000,
  startDate: '2024-01-01T00:00:00Z',
});

fetch(`/api/companies?${params}`);
// /api/companies?industry=oil+%26+gas&country=India&minRevenue=5000000&startDate=2024-01-01T00%3A00%3A00Z

Building URLs with the URL API

const url = new URL('https://api.example.com/search');
url.searchParams.set('q', 'cron scheduler & automation');
url.searchParams.set('page', 2);
url.searchParams.set('sort', 'relevance');

console.log(url.toString());
// https://api.example.com/search?q=cron+scheduler+%26+automation&page=2&sort=relevance

fetch(url); // works directly with a URL object

Axios — params option (auto-encodes)

import axios from 'axios';

// Pass params as an object — axios encodes them automatically
const response = await axios.get('/api/companies', {
  params: {
    industry: 'oil & gas',
    country: 'India',
  },
});
// No manual encoding needed ✅

Encoding path segments vs query parameters

Path segments and query values are encoded slightly differently. A slash / in a path segment must become %2F, but query values use encodeURIComponent which also encodes slashes:

// File path in URL path segment
const fileName = 'reports/2024/Q1.pdf';
const url = `/files/${encodeURIComponent(fileName)}`;
// /files/reports%2F2024%2FQ1.pdf

// vs query param — same function, same result
const dlUrl = `/download?file=${encodeURIComponent(fileName)}`;

Server-side: reading encoded params in Node.js

// Express automatically decodes query params
app.get('/search', (req, res) => {
  const industry = req.query.industry;
  // 'oil & gas' — already decoded by Express ✅
  res.json({ industry });
});

// Manually with the URL API in Node.js 18+
const url = new URL(req.url, 'https://example.com');
const q = url.searchParams.get('q'); // auto-decoded

Checklist for safe API query strings

• Never concatenate user input directly into a URL string.
• Use URLSearchParams or axios params — they encode automatically.
• When using encodeURIComponent manually, apply it only to values, not the entire URL.
• Watch out for double-encoding: if a value is already encoded, encoding again produces %2520 (encoded percent sign).
• Dates with colons and plus signs need encoding: 2024-01-01T09:00+05:30 → 2024-01-01T09%3A00%2B05%3A30.

Encode or decode instantly

Use our free URL Encoder / Decoder to percent-encode parameter values before pasting them into requests, or decode encoded strings from API logs to read them clearly.