Authentication

The Get Pages endpoint requires API credentials passed via request headers. The Get Editions endpoint is publicly accessible.

Required Headers

Example Request

GET /epapers/getPage/20260906/gujarati/Gujarat%20Samachar/Ahmedabad HTTP/1.1
Host: api.tradingref.com
CF-Access-Client-Id: your-client-id
CF-Access-Client-Secret: your-client-secret

cURL Example

curl -X GET \
  "https://api.tradingref.com/epapers/getPage/20260906/gujarati/Gujarat%20Samachar/Ahmedabad" \
  -H "CF-Access-Client-Id: your-client-id" \
  -H "CF-Access-Client-Secret: your-client-secret"

Error Response

If credentials are missing or invalid, the API returns a 403 Forbidden status:

{
  "error": "Invalid or missing credentials"
}

Workflow

Follow these steps to integrate the E-Paper API into your application.

GET /epapers/editions/20260906

GET /epapers/getPage/20260906/gujarati/Gujarat%20Samachar/Ahmedabad

Get Editions

Retrieve all languages, newspapers, and edition names available for a specific date. This endpoint requires no authentication.

Request

GET /epapers/editions/{date}

Path Parameters

Response

Returns a nested JSON object. The first level is keyed by language code, the second by newspaper name, and the value is an array of edition names.

Example Response 200 OK

{
  "gujarati": {
    "Gujarat Samachar": ["Ahmedabad", "Rajkot", "Mumbai", "Surat"],
    "Divya Bhaskar": ["Main Edition", "Saurashtra"]
  },
  "hindi": {
    "Dainik Bhaskar": ["Delhi", "Mumbai", "Jaipur"],
    "Dainik Jagran": ["Lucknow", "Kanpur"]
  },
  "english": {
    "Times of India": ["Ahmedabad", "Mumbai"],
    "Hindustan Times": ["Delhi"]
  }
}

Example Requests

# cURL
curl "https://api.tradingref.com/epapers/editions/20260906"

# JavaScript
const res = await fetch("https://api.tradingref.com/epapers/editions/20260906");
const editions = await res.json();

# Python
import requests
r = requests.get("https://api.tradingref.com/epapers/editions/20260906")
editions = r.json()

Get Pages

Fetch page URLs and content type for a specific newspaper edition. Requires API authentication.

Request

GET /epapers/getPage/{date}/{language}/{newspaper}/{edition}

Path Parameters

Response

Returns a JSON object with two fields:

Example Response 200 OK

{
  "type": "image",
  "pages": [
    "https://epaperstatic.gujaratsamachar.com/epaper/20260906-abc123-0.jpg",
    "https://epaperstatic.gujaratsamachar.com/epaper/20260906-abc123-1.jpg",
    "https://epaperstatic.gujaratsamachar.com/epaper/20260906-abc123-2.jpg",
    "https://epaperstatic.gujaratsamachar.com/epaper/20260906-abc123-3.jpg"
  ]
}

Error Responses

Page Types

The type field in the Get Pages response determines how the URLs in the pages array should be interpreted and used.

Using Encrypted PDFs (pdfl)

When fetching a page URL with type pdfl, the server includes an X-Session header in the response. This header contains the password needed to decrypt the PDF.

// Example: Fetching an encrypted PDF page
const response = await fetch(pageUrl, {
  headers: {
    "CF-Access-Client-Id": "your-client-id",
    "CF-Access-Client-Secret": "your-client-secret"
  }
});

// Extract the decryption password from the response header
const password = response.headers.get("X-Session");

// Get the encrypted PDF data
const pdfBlob = await response.blob();

// Use the password to decrypt and display the PDF
// (implementation depends on your PDF library)

Tiles Format

When the page type is tiles, each URL in the pages array returns a JSON object describing how the page image is split into a grid of smaller tiles.

Response Structure

Chunk Object

Example Response

{
  "width": 1600,
  "height": 2378,
  "cols": 2,
  "rows": 2,
  "chunks": [
    {
      "tx": 0, "ty": 0,
      "width": 800, "height": 1189,
      "url": "https://cache.epapr.in/4200698/.../1x1.jpg"
    },
    {
      "tx": 0, "ty": 1189,
      "width": 800, "height": 1189,
      "url": "https://cache.epapr.in/4200698/.../1x2.jpg"
    },
    {
      "tx": 800, "ty": 0,
      "width": 800, "height": 1189,
      "url": "https://cache.epapr.in/4200698/.../2x1.jpg"
    },
    {
      "tx": 800, "ty": 1189,
      "width": 800, "height": 1189,
      "url": "https://cache.epapr.in/4200698/.../2x2.jpg"
    }
  ]
}

Stitching Tiles Together

To reconstruct the full page image, create a canvas with the dimensions width x height, then draw each tile at its tx, ty position.

// JavaScript example using Canvas
async function stitchTiles(tileData) {
  const canvas = document.createElement("canvas");
  canvas.width = tileData.width;
  canvas.height = tileData.height;
  const ctx = canvas.getContext("2d");

  for (const chunk of tileData.chunks) {
    const img = await loadImage(chunk.url);
    ctx.drawImage(img, chunk.tx, chunk.ty, chunk.width, chunk.height);
  }

  return canvas;
}

function loadImage(url) {
  return new Promise((resolve) => {
    const img = new Image();
    img.crossOrigin = "anonymous";
    img.onload = () => resolve(img);
    img.src = url;
  });
}

Errors

The API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON body with details.

Error Response Format

{
  "error": "Description of what went wrong"
}

HTTP Status Codes

Handling Errors

// JavaScript error handling example
async function fetchEditions(date) {
  const res = await fetch(`https://api.tradingref.com/epapers/editions/${date}`);

  if (!res.ok) {
    const error = await res.json();
    throw new Error(error.error || `HTTP ${res.status}`);
  }

  return res.json();
}