# Factorio Mods Scraper (`confidential_marina/factorio-mods-scraper`) Actor

Export mods from the official Factorio mod portal: name, owner, downloads, score, category, tags, versions, license, homepage. Public JSON API. No login.

- **URL**: https://apify.com/confidential_marina/factorio-mods-scraper.md
- **Developed by:** [Kaleb Holley](https://apify.com/confidential_marina) (community)
- **Categories:** Developer tools, Open source, Games
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Factorio Mods Scraper

Export mods from the **[official Factorio mod portal](https://mods.factorio.com/)** — ~20k published mods with clean structured data: name, title, owner, summary, downloads, score, category, tags, license, homepage, Factorio version, latest release, and optional full release history.

Data comes from the Factorio mods portal JSON API (`/api/mods` + `/api/mods/{name}/full`). No browser, no proxy, no login.

> Not affiliated with or sanctioned by Wube Software. Uses the public mod-portal browse endpoints with polite rate limits.

### What can it do?

- **Full catalog export.** Load the portal catalog (`page_size=max`) and sort by downloads or score.
- **Search & filters.** Case-insensitive query across name / title / owner / summary / category; optional category and tag filters.
- **Sort.** Downloads, score, updated, created, or name (ascending / descending).
- **Full details (default).** Description, tags, license, homepage, thumbnail, images, created/updated dates, release count.
- **Release history (optional).** Attach newest-first `releases[]` capped by `maxReleasesPerMod`.
- **Factorio version awareness.** Pass `factorioVersion` and optionally hide incompatible/deprecated mods.
- **Fast and cheap.** Pure JSON over HTTPS, concurrency ≤ 4 with Retry-After backoff. Runs on 512 MB.

### Use cases

- **Modding market datasets** for AI / RAG about Factorio ecosystems (Space Age, overhauls, QoL)
- **Competitor / ecosystem tracking** for mod authors (downloads, score, release cadence)
- **Lead generation**: owner names and homepage / Discord links
- **Modpack research**: discover popular content by downloads and category
- **Scheduled snapshots** of the Factorio mod portal catalog

### Input

| Field | Type | Description |
|---|---|---|
| `query` | string | Case-insensitive text filter. Empty = all (then sort / maxItems). |
| `category` | string | `content`, `overhaul`, `tweaks`, `utilities`, `scenarios`, `mod-packs`, `localizations`, `internal`, `no-category`. |
| `tag` | string | Optional tag (`logistics`, `trains`, `combat`, …). Forces details fetch. |
| `sort` | string | `-downloads` (default), `-score`, `-updated`, `-created`, `name`, or ascending variants. |
| `maxItems` | integer | Max mods to output (default 100). |
| `hideDeprecated` | boolean | Hide deprecated / incompatible mods (default `true`). |
| `factorioVersion` | string | Optional Factorio version (e.g. `2.0.76`). |
| `includeDetails` | boolean | Fetch full mod details (default `true`). |
| `includeReleases` | boolean | Attach `releases[]` (default `false`). |
| `maxReleasesPerMod` | integer | Cap on releases when included (default 5; `0` = all). |

Example: top mods by downloads:

```json
{ "sort": "-downloads", "maxItems": 100 }
```

Example: logistics-tagged content mods matching “belt”:

```json
{
  "query": "belt",
  "category": "content",
  "tag": "logistics",
  "sort": "-downloads",
  "maxItems": 50,
  "includeDetails": true
}
```

### Output

One dataset item per mod:

```json
{
  "name": "helmod",
  "title": "Helmod: Assistant for planning your factory",
  "owner": "Helfima",
  "summary": "Assistant for planning your factory…",
  "description": "…",
  "category": "utilities",
  "tags": ["manufacturing"],
  "downloads": 547131,
  "score": 12.5,
  "latestVersion": "2.0.0",
  "factorioVersion": "2.0",
  "homepage": "https://…",
  "license": "MIT",
  "thumbnailUrl": "https://mods.factorio.com/assets/…",
  "createdAt": "2016-01-01T00:00:00Z",
  "updatedAt": "2026-09-01T00:00:00Z",
  "url": "https://mods.factorio.com/mod/helmod",
  "releaseCount": 40,
  "scrapedAt": "2026-10-14T20:00:00+00:00"
}
```

### Pricing

Pay-per-event: **$0.002 per mod** ($2 per 1,000 results).

### Notes

- Uses Factorio’s mod portal JSON API only. Identifies as `factorio-mods-scraper (Apify; +https://apify.com/confidential_marina; not affiliated with Wube Software)`.
- Downloads/score sorts fetch the full catalog once (~12 MB, ~20k mods) then filter locally.
- Rate limits are respected with concurrency ≤ 4, inter-request pacing, and Retry-After backoff.

# Actor input Schema

## `query` (type: `string`):

Case-insensitive filter across name, title, owner, summary, and category. Empty = all mods (then sorted / capped by maxItems).

## `category` (type: `string`):

Optional Factorio mod category filter.

## `tag` (type: `string`):

Optional tag filter (requires includeDetails). Tags include transportation, logistics, trains, combat, etc.

## `sort` (type: `string`):

How to order results. Prefix with - for descending. Downloads/score load the full catalog once; name/updated/created use native API pagination.

## `maxItems` (type: `integer`):

Maximum mods to output.

## `hideDeprecated` (type: `boolean`):

When true (default), exclude mods marked deprecated or incompatible with factorioVersion.

## `factorioVersion` (type: `string`):

Optional Factorio version string (e.g. 2.0.76). Mods incompatible with this version are treated as deprecated when hideDeprecated is true.

## `includeDetails` (type: `boolean`):

Fetch /api/mods/{name}/full for description, tags, license, homepage, dates, thumbnail, images, release count. Recommended.

## `includeReleases` (type: `boolean`):

Attach a releases\[] array (newest first). Increases output size; requires includeDetails.

## `maxReleasesPerMod` (type: `integer`):

When includeReleases is true, cap how many releases are kept (0 = all).

## Actor input object example

```json
{
  "category": "",
  "tag": "",
  "sort": "-downloads",
  "maxItems": 100,
  "hideDeprecated": true,
  "includeDetails": true,
  "includeReleases": false,
  "maxReleasesPerMod": 5
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "",
    "category": "",
    "tag": "",
    "sort": "-downloads",
    "maxItems": 100,
    "factorioVersion": "",
    "maxReleasesPerMod": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("confidential_marina/factorio-mods-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "",
    "category": "",
    "tag": "",
    "sort": "-downloads",
    "maxItems": 100,
    "factorioVersion": "",
    "maxReleasesPerMod": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("confidential_marina/factorio-mods-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "",
  "category": "",
  "tag": "",
  "sort": "-downloads",
  "maxItems": 100,
  "factorioVersion": "",
  "maxReleasesPerMod": 5
}' |
apify call confidential_marina/factorio-mods-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,confidential_marina/factorio-mods-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/hokEEYlXvmMeArzCl/builds/N3RQhDp2IIyc3Rk6d/openapi.json