# VGHF Search (`dalborgo/vghf-search`) Actor

Find video game reviews, articles, ads, and historical references in the Video Game History Foundation Digital Archive.

- **URL**: https://apify.com/dalborgo/vghf-search.md
- **Developed by:** [Marco Dal Borgo](https://apify.com/dalborgo) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.10 / 1,000 results

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

## VGHF Search

Search the Video Game History Foundation Digital Archive and rank matching magazines and documents by the **Text Match** count reported by the archive.

VGHF Search is useful when a normal archive search returns many documents and you want to quickly identify the issues where a game, company, person, console, publication, or other topic is discussed most extensively.

### Why use this Actor?

The Video Game History Foundation Digital Archive can return many matching documents for a search.

VGHF Search collects the complete result set and ranks documents by the **Text Match** count exposed by the archive, making it easier to identify results where your search term appears most often.

For example, searching for `windjammers` quickly surfaces **Edge, Issue 10 (July 1994)** with 9 text matches:

![Windjammers matches in Edge Issue 10](https://www.dalborgo.it/public/first.png)

Each result includes a direct link to the original VGHF archive record, so you can continue exploring the source material and open the scanned document:

![Edge Issue 10 in the VGHF Digital Archive](https://www.dalborgo.it/public/second.png)

This makes it easier to distinguish between:

- magazines containing a full review or feature
- magazines containing only a short mention
- catalogs or promotional material
- documents where the archive does not expose a Text Match count

It is particularly useful for retrogaming enthusiasts, researchers, collectors, and video game historians looking for references in vintage magazines.

### Features

- Search the VGHF Digital Archive
- Full-text or all-fields search
- Exact phrase search
- Optional publication year range
- Automatically follows all result pages
- Extracts document title and publication date
- Extracts VGHF Text Match counts
- Extracts matched-text snippets when available
- Ranks results by Text Match count
- Keeps documents without a Text Match count instead of discarding them
- Handles searches containing thousands of documents
- Deduplicates results by document URL
- Stores intermediate progress for large searches

### Input

#### Search term

The game, company, person, console, publication, or other term you want to find.

Example:

```text
windjammers
```

#### Search mode

Two search modes are available.

##### Full text

Searches inside the full text of documents in the archive.

This is the recommended mode when you want to find occurrences inside magazines, catalogs, press material, and other scanned documents.

##### All fields

Uses the archive's general keyword search and may include matches from other indexed fields in addition to document text.

#### Exact phrase

When enabled, the Actor searches the term as an exact phrase.

For example:

```text
windjammers
```

becomes:

```text
"windjammers"
```

This is recommended for game titles, people, companies, and other proper names.

#### Start year

Optional first publication year to include.

Example:

```text
1994
```

#### End year

Optional last publication year to include.

Example:

```text
1996
```

Both year fields are optional.

### Example input

```json
{
  "keyword": "windjammers",
  "searchMode": "fullText",
  "exactPhrase": true,
  "dateStart": 1994,
  "dateEnd": 1996
}
```

### Output

Each result contains:

| Field | Description |
| --- | --- |
| `title` | Magazine issue or document title |
| `date` | Publication date shown by the archive |
| `textMatches` | Number of occurrences of the search term reported by the VGHF Digital Archive |
| `snippet` | Matched-text excerpt when available |
| `url` | Direct URL to the VGHF document record |

Results are ordered from the highest `textMatches` value to the lowest, making documents with more text matches easier to identify.

If VGHF does not expose a Text Match count for a document, the Actor keeps the result with:

```json
{
  "textMatches": null,
  "snippet": null
}
```

Results without a reported Text Match count are placed after documents with a reported count.

### Example output

```json
{
  "title": "Edge, Issue 10",
  "date": "July 1994",
  "textMatches": 9,
  "snippet": "...",
  "url": "https://archive.gamehistory.org/item/..."
}
```

### Example use case

Suppose you are researching the history of **Windjammers**.

A normal archive search may return dozens of magazines and documents.

With:

```json
{
  "keyword": "windjammers",
  "searchMode": "fullText",
  "exactPhrase": true,
  "dateStart": 1994,
  "dateEnd": 1996
}
```

VGHF Search collects every matching archive result in that period and ranks the documents by how many Text Matches the archive reports.

This can help distinguish substantial coverage from passing references.

### Large searches

Broad search terms can return thousands of documents.

The Actor follows every result page before producing the final ranking. This is necessary because the complete result set must be collected before documents can be globally sorted by Text Match count.

For faster and cheaper searches, consider using:

- Exact phrase
- A publication year range
- A more specific search term

Very broad searches can take several minutes and consume more compute than focused searches.

### Reliability

The Actor stores intermediate progress while processing large searches.

Pagination failures are retried locally, results are deduplicated by document URL, and the final Dataset is written only after the complete result set has been collected successfully.

If the archive temporarily fails to load a result page, the Actor retries that page before stopping.

### What this Actor does not do

VGHF Search does **not** download magazine or document PDFs.

It extracts search-result metadata exposed by the Video Game History Foundation Digital Archive and links back to the original document records.

### Resource usage

The Actor uses Playwright to interact reliably with the archive's search pagination.

Focused searches usually complete quickly. Large searches containing hundreds of result pages can take several minutes.

The recommended default memory configuration is:

```text
2 GB
```

### Notes

VGHF Search depends on the current structure and availability of the Video Game History Foundation Digital Archive.

If the archive changes its search interface or result markup, the Actor may require an update.

This Actor is an independent tool and is not affiliated with or endorsed by the Video Game History Foundation.

# Actor input Schema

## `keyword` (type: `string`):

Game, company, person, console, or other term to search for.

## `searchMode` (type: `string`):

Choose whether to search inside document text or across all indexed fields.

## `exactPhrase` (type: `boolean`):

Search the term as an exact phrase. Recommended for game titles and proper names.

## `dateStart` (type: `integer`):

Optional first publication year to include.

## `dateEnd` (type: `integer`):

Optional last publication year to include.

## Actor input object example

```json
{
  "keyword": "windjammers",
  "searchMode": "fullText",
  "exactPhrase": true
}
```

# Actor output Schema

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

Documents matching the search keyword, ranked by Text Match count.

# 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 = {
    "keyword": "windjammers"
};

// Run the Actor and wait for it to finish
const run = await client.actor("dalborgo/vghf-search").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 = { "keyword": "windjammers" }

# Run the Actor and wait for it to finish
run = client.actor("dalborgo/vghf-search").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 '{
  "keyword": "windjammers"
}' |
apify call dalborgo/vghf-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dalborgo/vghf-search"
        }
    }
}
```

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/1fcxJqOAB59DwV89r/builds/4vWjBMNBDp4ii5bKB/openapi.json