Setting Custom Character Encoding in Axios

Axios defaults to UTF-8 for encoding outgoing request payloads and decoding incoming response bodies. When integrating with legacy systems or specialized APIs that require alternative character sets such as ISO-8859-1, Windows-1252, or Shift-JIS, you must explicitly configure request headers and intercept the raw response data to decode it using tools like the native TextDecoder API or third-party decoding libraries.

Setting Encoding for Outgoing Requests

To inform the receiving server about the character encoding used in your request payload, define the charset parameter inside the Content-Type request header.

const axios = require('axios');

axios.post('https://api.example.com/data', payload, {
  headers: {
    'Content-Type': 'application/json; charset=ISO-8859-1'
  }
});

If the payload itself must be transmitted as raw bytes encoded in a specific character set (rather than standard UTF-8), encode the string into a binary buffer before passing it to Axios:

const iconv = require('iconv-lite');

// Encode string to ISO-8859-1 Buffer
const encodedData = iconv.encode('Special characters: ä, ö, ü', 'ISO-8859-1');

axios.post('https://api.example.com/data', encodedData, {
  headers: {
    'Content-Type': 'text/plain; charset=ISO-8859-1'
  }
});

Decoding Incoming Responses with Custom Encodings

Axios automatically attempts to parse response streams as UTF-8. To process a non-UTF-8 response correctly without data corruption, prevent Axios from auto-parsing the response by setting responseType to 'arraybuffer'.

Method 1: Using the Native TextDecoder API

For standard web-supported encodings (such as windows-1252, iso-8859-1, or shift-jis), use the built-in TextDecoder interface available in Node.js and modern browsers.

const axios = require('axios');

async function fetchData() {
  const response = await axios.get('https://api.example.com/legacy-endpoint', {
    responseType: 'arraybuffer'
  });

  // Decode the raw ArrayBuffer into a string using the desired charset
  const decoder = new TextDecoder('iso-8859-1');
  const decodedText = decoder.decode(response.data);

  // If the endpoint returns JSON, parse the decoded string manually
  const jsonData = JSON.parse(decodedText);
  return jsonData;
}

Method 2: Using `iconv-lite` for Extended Encodings

For environments or character encodings not covered by TextDecoder (such as specific regional or legacy encodings), use the iconv-lite library.

const axios = require('axios');
const iconv = require('iconv-lite');

async function fetchCustomEncodedData() {
  const response = await axios.get('https://api.example.com/data-shiftjis', {
    responseType: 'arraybuffer'
  });

  // Decode from Buffer using iconv-lite
  const decodedText = iconv.decode(Buffer.from(response.data), 'shift_jis');
  
  return decodedText;
}

Automating Response Decoding with Axios Interceptors

If you make frequent requests to endpoints with custom encodings, use an Axios response interceptor to automatically decode incoming data based on the Content-Type header:

const axios = require('axios');
const iconv = require('iconv-lite');

const client = axios.create({
  responseType: 'arraybuffer'
});

client.interceptors.response.use((response) => {
  const contentType = response.headers['content-type'] || '';
  const match = contentType.match(/charset=([^;]+)/i);
  const charset = match ? match[1].trim() : 'utf-8';

  const decodedData = iconv.decode(Buffer.from(response.data), charset);

  if (contentType.includes('application/json')) {
    try {
      response.data = JSON.parse(decodedData);
    } catch {
      response.data = decodedData;
    }
  } else {
    response.data = decodedData;
  }

  return response;
});