minecraft-apk-scraper

Scraper Minecraft APK download links from mcpedl.org.

Requirements

• Node.js >= 18.0.0

Installation

npm install minecraft-apk-scraper

Quick start

const { getLatestVersion } = require('minecraft-apk-scraper');

const data = await getLatestVersion();
console.log(data.title);       // "Minecraft PE 1.21.0"
console.log(data.downloadUrl); // "https://..."

API

getLatestVersion([usePuppeteer])

Fetches the latest stable (non-beta, non-preview) version and resolves its APK download URL in one call.

| Parameter | Type | Default | Description | |---|---|---|---| | usePuppeteer | boolean | false | Force Puppeteer instead of axios for the download step |

Returns: Promise<VersionResult>

{
  title: string;
  slug: string;
  description: string;
  thumbnail: string | undefined;
  downloadUrl: string | null;
  allDownloads: DownloadForm[];
}

getVersionList([page])

Returns a paginated list of versions from the downloads index.

| Parameter | Type | Default | Description | |---|---|---|---| | page | number | 1 | Page number (1-based) |

Returns: Promise<Array<{ title: string, slug: string }>>

const versions = await getVersionList(1);
// [{ title: "Minecraft PE 1.21.0", slug: "/minecraft-pe-1-21-0-apk/" }, ...]

getVersionPage(slug)

Fetches metadata and download form data for a single version page.

| Parameter | Type | Description | |---|---|---| | slug | string | Path slug (e.g. /minecraft-pe-1-21-0-apk/) or full URL |

Returns:

{
  title: string;
  description: string;
  thumbnail: string | undefined;
  url: string;
  downloads: DownloadForm[];
}

Where DownloadForm is:

{
  action: string;      // form action URL
  formData: Record<string, string>; // hidden input values
  buttonText: string;
}

getDownloadUrl(action, formData, [referer], [usePuppeteer])

Submits a download form and resolves the final APK URL. Tries axios first; falls back to Puppeteer only on parse or selector failures (hard network errors are re-thrown immediately).

| Parameter | Type | Default | Description | |---|---|---|---| | action | string | — | Form action path or full URL | | formData | object | — | Hidden form field key/value pairs | | referer | string | undefined | Referer header value | | usePuppeteer | boolean | false | Skip axios entirely |

Returns: Promise<string | null>

setProxy(proxyUrl)

Configures an HTTP, HTTPS, or SOCKS proxy for all subsequent requests.

setProxy('http://user:pass@host:port');
setProxy('socks5://127.0.0.1:1080');

disableProxy()

Clears the current proxy configuration.

getProxy()

Returns the currently active proxy URL, or null if none is set.

Examples

Get the latest version

const { getLatestVersion } = require('minecraft-apk-scraper');

const data = await getLatestVersion();
console.log('Title:', data.title);
console.log('Download URL:', data.downloadUrl);

Browse all versions (paginated)

const { getVersionList, getVersionPage, getDownloadUrl } = require('minecraft-apk-scraper');

const versions = await getVersionList(1);

for (const v of versions) {
  const page = await getVersionPage(v.slug);
  if (!page.downloads.length) continue;

  const { action, formData } = page.downloads[0];
  const url = await getDownloadUrl(action, formData, page.url);
  console.log(`${v.title}: ${url}`);
}

Use with a proxy

const { setProxy, getLatestVersion, disableProxy } = require('minecraft-apk-scraper');

setProxy('http://user:pass@host:port');

const data = await getLatestVersion();
console.log(data.downloadUrl);

disableProxy();

Force Puppeteer (JS countdown pages)

const { getLatestVersion } = require('minecraft-apk-scraper');

const data = await getLatestVersion(true);
console.log(data.downloadUrl);

How it works

1. getVersionList — scrapes the /downloading/ index page with cheerio. Uses a primary CSS selector set and a broader link-scan fallback if the primary yields nothing.
2. getVersionPage — fetches the individual version page and extracts all download forms (action URL + hidden fields).
3. getDownloadUrlFast — POSTs the form with axios, then parses the response HTML for the final APK link. Also scans inline <script> tags as a last resort.
4. getDownloadUrlWithPuppeteer — launches a stealth headless Chromium, submits the form via JS, waits for the download button to appear (handles JS countdowns), and simulates mouse movement before extracting the URL.
5. getDownloadUrl — orchestrates 3 and 4: runs the fast path first, falls back to Puppeteer on selector/parse failures only.

All outbound requests use random User-Agent rotation, realistic browser headers, and a 1–5 second random delay between requests to reduce detection risk.

License

MIT