Dev Brains AI
DevBrainsAI

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.

Frequently Asked Questions

Why does an unencoded & in a query parameter break an API call?

The & character separates query parameters, so an unencoded & inside a value gets read as the start of a new parameter instead of part of the value — silently splitting your data and sending the server something different from what you intended.

Should I use encodeURIComponent or URLSearchParams for API query parameters?

URLSearchParams is usually the better default — it encodes every value automatically and builds the full query string for you, so there is no risk of forgetting to encode one field. Use encodeURIComponent directly only when you are inserting a single value into a template string by hand.

Do I need to manually decode query parameters on the server?

No, in almost all cases. Frameworks like Express, and the built-in URL/URLSearchParams APIs in Node.js, automatically decode query parameters before your code sees them — manual decoding is rarely needed and can even double-decode a value if applied on top of the framework's own decoding.

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.

Need to URL-encode query parameters automatically?

Use the free Dev Brains AI URL Encoder — paste your value and get the encoded output instantly.

Related articles