Request

The req object represents the HTTP request and has properties for the request query string, parameters, body, HTTP headers, and more.

app.get('/user/:id', (req, res) => {
  res.send(`User ${req.params.id}`);
});

By convention, the object is always referred to as req (and the HTTP response is res), but its actual name is determined by the parameters to the callback function.

Properties

req.app

Reference to the Express application instance.

req.app

Application

The Express application instance

app.get('/user', (req, res) => {
  console.log(req.app.get('title')); // Access app settings
});

req.baseUrl

The URL path on which a router instance was mounted.

req.baseUrl

string

The base URL path

const router = express.Router();

router.get('/user/:id', (req, res) => {
  console.log(req.baseUrl); // "/api"
});

app.use('/api', router);

req.body

Contains key-value pairs of data submitted in the request body. By default, it is undefined and is populated when you use body-parsing middleware such as express.json() or express.urlencoded().

req.body

object

The parsed request body

app.use(express.json());

app.post('/profile', (req, res) => {
  console.log(req.body.name); // Access parsed JSON data
  res.json(req.body);
});

req.cookies

Contains cookies sent by the request. Requires cookie-parser middleware.

req.cookies

object

Object containing cookies

const cookieParser = require('cookie-parser');
app.use(cookieParser());

app.get('/', (req, res) => {
  console.log(req.cookies.name);
});

req.fresh

Indicates whether the request is “fresh” based on the Last-Modified and/or ETag headers.

req.fresh

boolean

True if the request is fresh, false otherwise

app.get('/document', (req, res) => {
  if (req.fresh) {
    res.status(304).end();
  } else {
    res.send(document);
  }
});

req.host

Contains the hostname from the Host HTTP header. When the trust proxy setting trusts the socket address, the X-Forwarded-Host header field will be trusted.

req.host

string

The hostname including port if present

app.get('/', (req, res) => {
  console.log(req.host); // "example.com:3000"
});

req.hostname

Contains the hostname from the Host HTTP header without the port number.

req.hostname

string

The hostname without port

app.get('/', (req, res) => {
  console.log(req.hostname); // "example.com"
});

req.ip

Contains the remote IP address of the request. When the trust proxy setting trusts the socket address, this property will contain the value from the X-Forwarded-For header.

req.ip

string

The IP address of the client

app.get('/', (req, res) => {
  console.log(req.ip); // "127.0.0.1"
});

req.ips

When the trust proxy setting trusts the socket address, this property contains an array of IP addresses specified in the X-Forwarded-For request header.

req.ips

array

Array of IP addresses

app.set('trust proxy', true);

app.get('/', (req, res) => {
  console.log(req.ips); // ["client", "proxy1", "proxy2"]
});

req.method

Contains the HTTP method of the request: GET, POST, PUT, DELETE, etc.

req.method

string

The HTTP method

app.use((req, res, next) => {
  console.log(req.method); // "GET", "POST", etc.
  next();
});

req.originalUrl

This property retains the original request URL, allowing you to rewrite req.url freely for internal routing purposes.

req.originalUrl

string

The original request URL

app.use('/admin', (req, res, next) => {
  console.log(req.originalUrl); // "/admin/new"
  console.log(req.baseUrl);     // "/admin"
  console.log(req.path);        // "/new"
  next();
});

req.params

An object containing properties mapped to named route parameters.

req.params

object

Object containing route parameters

// Route: /user/:id/:name
app.get('/user/:id/:name', (req, res) => {
  console.log(req.params.id);   // "42"
  console.log(req.params.name); // "john"
});

// URL: /user/42/john

req.path

Contains the path part of the request URL.

req.path

string

The URL path

// URL: http://example.com/users?sort=desc
app.get('/users', (req, res) => {
  console.log(req.path); // "/users"
});

req.protocol

Contains the request protocol string: either http or https when requested with TLS.

req.protocol

string

The protocol (“http” or “https”)

app.get('/', (req, res) => {
  console.log(req.protocol); // "https"
});

req.query

An object containing a property for each query string parameter in the route.

req.query

object

Object containing parsed query string

// URL: /search?q=express&limit=10
app.get('/search', (req, res) => {
  console.log(req.query.q);     // "express"
  console.log(req.query.limit); // "10"
});

req.res

Reference to the response object.

req.res

Response

The Express response object

app.get('/', (req, res) => {
  console.log(req.res === res); // true
});

req.route

Contains the currently matched route as a string.

req.route

object

The currently matched route

app.get('/user/:id', (req, res) => {
  console.log(req.route.path); // "/user/:id"
});

req.secure

A boolean indicating whether the connection is over HTTPS.

req.secure

boolean

True if the request is over HTTPS

app.get('/', (req, res) => {
  if (req.secure) {
    res.send('Secure connection');
  } else {
    res.redirect('https://' + req.headers.host + req.url);
  }
});

req.signedCookies

Contains signed cookies sent by the request, unsigned and ready for use. Requires cookie-parser middleware.

req.signedCookies

object

Object containing signed cookies

const cookieParser = require('cookie-parser');
app.use(cookieParser('secret'));

app.get('/', (req, res) => {
  console.log(req.signedCookies.user);
});

req.stale

Indicates whether the request is “stale” (opposite of req.fresh).

req.stale

boolean

True if the request is stale

app.get('/', (req, res) => {
  console.log(req.stale); // true or false
});

req.subdomains

An array of subdomains in the domain name of the request.

req.subdomains

array

Array of subdomains

// Host: "tobi.ferrets.example.com"
app.get('/', (req, res) => {
  console.log(req.subdomains); // ["ferrets", "tobi"]
});

req.xhr

A boolean indicating whether the request was issued by an XMLHttpRequest (checks if X-Requested-With header is XMLHttpRequest).

req.xhr

boolean

True if the request is an AJAX request

app.get('/data', (req, res) => {
  if (req.xhr) {
    res.json({ data: 'AJAX response' });
  } else {
    res.send('<html>...</html>');
  }
});

Methods

req.accepts(types)

Checks if the specified content types are acceptable based on the request’s Accept HTTP header. Returns the best match or false if none are acceptable.

app.get('/', (req, res) => {
  // Accept: text/html
  req.accepts('html');              // "html"
  req.accepts('text/html');         // "text/html"
  req.accepts(['json', 'text']);    // "text"
  req.accepts('application/json');  // false
});

req.acceptsCharsets(charset [, …])

Returns the first accepted charset from the specified charsets based on the request’s Accept-Charset HTTP header.

app.get('/', (req, res) => {
  req.acceptsCharsets('utf-8', 'iso-8859-1'); // "utf-8"
});

req.acceptsEncodings(encoding [, …])

Returns the first accepted encoding from the specified encodings based on the request’s Accept-Encoding HTTP header.

app.get('/', (req, res) => {
  req.acceptsEncodings('gzip', 'deflate'); // "gzip"
});

req.acceptsLanguages(lang [, …])

Returns the first accepted language from the specified languages based on the request’s Accept-Language HTTP header.

app.get('/', (req, res) => {
  req.acceptsLanguages('en', 'es', 'fr'); // "en"
});

req.get(field)

Returns the specified HTTP request header field (case-insensitive match). The Referrer and Referer fields are interchangeable.

app.get('/', (req, res) => {
  req.get('Content-Type');  // "text/plain"
  req.get('content-type');  // "text/plain"
  req.get('Referrer');      // "http://example.com"
  req.get('Referer');       // "http://example.com"
});

Alias: req.header(field)

req.header(field)

Alias for req.get(field).

req.is(type)

Returns the matching content type if the incoming request’s Content-Type HTTP header matches the MIME type specified. Returns false if there’s no match.

app.post('/upload', (req, res) => {
  // Content-Type: text/html; charset=utf-8
  req.is('html');       // "html"
  req.is('text/html');  // "text/html"
  req.is('text/*');     // "text/*"
  
  // Content-Type: application/json
  req.is('json');              // "json"
  req.is('application/json');  // "application/json"
  req.is('html');              // false
});

req.range(size[, options])

Parses the Range header field, returning an array of ranges or an error code.

app.get('/file', (req, res) => {
  const range = req.range(1000);
  
  if (range === -1) {
    res.status(416).send('Range not satisfiable');
  } else if (range && range.type === 'bytes') {
    // range[0].start, range[0].end
    res.status(206).send(partialContent);
  } else {
    res.send(fullContent);
  }
});

Complete Example

const express = require('express');
const app = express();

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.get('/user/:id', (req, res) => {
  // Request properties
  console.log('Method:', req.method);           // GET
  console.log('Path:', req.path);               // /user/123
  console.log('Original URL:', req.originalUrl); // /user/123?name=john
  console.log('Protocol:', req.protocol);        // http or https
  console.log('Secure:', req.secure);            // true or false
  console.log('IP:', req.ip);                    // Client IP
  console.log('Hostname:', req.hostname);        // example.com
  
  // Parameters and query
  console.log('User ID:', req.params.id);       // 123
  console.log('Query name:', req.query.name);   // john
  
  // Headers
  console.log('Content-Type:', req.get('Content-Type'));
  console.log('User-Agent:', req.get('User-Agent'));
  
  // Content negotiation
  if (req.accepts('json')) {
    res.json({ userId: req.params.id });
  } else if (req.accepts('html')) {
    res.send(`<html><body>User ${req.params.id}</body></html>`);
  } else {
    res.status(406).send('Not Acceptable');
  }
});

app.post('/upload', (req, res) => {
  // Check content type
  if (req.is('application/json')) {
    console.log('Received JSON:', req.body);
    res.json({ success: true });
  } else if (req.is('text/plain')) {
    console.log('Received text:', req.body);
    res.send('Text received');
  } else {
    res.status(415).send('Unsupported Media Type');
  }
});

app.listen(3000);

Core API

Properties

req.app

req.baseUrl

req.body

req.cookies

req.fresh

req.host

req.hostname

req.ip

req.ips

req.method

req.originalUrl

req.params

req.path

req.protocol

req.query

req.res

req.route

req.secure

req.signedCookies

req.stale

req.subdomains

req.xhr

Methods

req.accepts(types)

req.acceptsCharsets(charset [, …])

req.acceptsEncodings(encoding [, …])

req.acceptsLanguages(lang [, …])

req.get(field)

req.header(field)

req.is(type)

req.range(size[, options])

Complete Example

Build docs developers (and LLMs) love

Core API

Documentation Index

​Properties

​req.app

​req.baseUrl

​req.body

​req.cookies

​req.fresh

​req.host

​req.hostname

​req.ip

​req.ips

​req.method

​req.originalUrl

​req.params

​req.path

​req.protocol

​req.query

​req.res

​req.route

​req.secure

​req.signedCookies

​req.stale

​req.subdomains

​req.xhr

​Methods

​req.accepts(types)

​req.acceptsCharsets(charset [, …])

​req.acceptsEncodings(encoding [, …])

​req.acceptsLanguages(lang [, …])

​req.get(field)

​req.header(field)

​req.is(type)

​req.range(size[, options])

​Complete Example

Build docs developers (and LLMs) love

Properties

req.app

req.baseUrl

req.body

req.cookies

req.fresh

req.host

req.hostname

req.ip

req.ips

req.method

req.originalUrl

req.params

req.path

req.protocol

req.query

req.res

req.route

req.secure

req.signedCookies

req.stale

req.subdomains

req.xhr

Methods

req.accepts(types)

req.acceptsCharsets(charset [, …])

req.acceptsEncodings(encoding [, …])

req.acceptsLanguages(lang [, …])

req.get(field)

req.header(field)

req.is(type)

req.range(size[, options])

Complete Example