# Numista Coin Catalogue Scraper (`crawlerbros/numista-coin-catalogue-scraper`) Actor

Scrape Numista's coin, banknote, and exonumia catalogue. Search by keyword, or browse by issuer, ruler, material, mint, tag, shape, technique, or script, refined by face value, weight, diameter, or lettering. Get composition, weight, mintage years, catalogue references, and images.

- **URL**: https://apify.com/crawlerbros/numista-coin-catalogue-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Numista Coin Catalogue Scraper

Scrape [Numista](https://en.numista.com) — the world's largest collaborative online catalogue of coins, banknotes, and exonumia (tokens, medals, and other collectibles), covering 250,000+ catalogue entries from every country and era. Search by keyword, or browse by issuing country, ruler, material, mint, theme tag, shape, minting/printing technique, or lettering script — and optionally refine any of those by face value, weight, diameter, width, lettering, engraver, or year in circulation. Get composition, weight, diameter, mintage years, catalogue references (KM#, Pick#, etc.), obverse/reverse descriptions, and images — no login, no API key, no cookies required.

### What this actor does

- **Ten modes:** free-text `search`, plus eight taxonomy browsers (`byIssuer`, `byRuler`, `byMaterial`, `byMint`, `byTag`, `byShape`, `byTechnique`, `byScript`) and an exact `byCoinId` lookup
- **Rich per-item data:** face value, composition/material, weight, diameter, thickness, mintage years, ruler/period, catalogue references, tags, and obverse/reverse imagery
- **Deep detail lookup:** `byCoinId` fetches the full catalogue page for a coin/banknote/token — obverse & reverse descriptions, lettering, engraver, edge, mint list, related items, and swap-market availability
- **Curated dropdowns:** 187 issuing countries, 62 materials, 220 theme tags, 79 shapes, 32 minting/printing techniques, 113 lettering scripts, and popular rulers/mints — plus free-text overrides for anything not in the list
- **Seven refinements, combinable with any search/browse mode:** face value, weight (g), diameter (mm), width (mm, for banknotes), visible lettering/inscription (with `*` wildcard), engraver/designer, and year in circulation
- **Empty fields are always omitted** — you only ever see fields that have real data

> **Note:** `byCoinId` (direct lookup by catalogue number) is the most reliable mode and is used by default. `search` and the taxonomy-browse modes (`byIssuer`, `byRuler`, `byMaterial`, `byMint`, `byTag`, `byShape`, `byTechnique`, `byScript`) depend on Numista's catalogue search pages, which are currently subject to the source site's own access restrictions and may return no results. If a search/browse run returns 0 items, switch to `byCoinId` with a known catalogue number, or try again later.

### Output per item

Every record includes:

- `coinId` — Numista catalogue number
- `title` — catalogue title (e.g. `1 Dollar "Morgan Dollar"`)
- `year`, `yearFrom`, `yearTo` — mintage year or year range
- `issuerName`, `issuerSlug` — issuing country/entity
- `categoryMain` / `categorySub` — e.g. `Coins` › `Standard circulation coins`
- `composition` — e.g. `Copper-nickel (75% Copper, 25% Nickel)`
- `weightGrams`, `diameterMm` — coins; `sizeText` — banknotes
- `catalogueReferences` — e.g. `["KM# 22"]`
- `commemorativeNote` — commemorative issue name, when applicable
- `obverseImageUrl`, `reverseImageUrl`
- `swapAvailable` — whether a Numista member currently lists it for swap
- `numistaUrl` — canonical catalogue page
- `recordType` — `coin`, `banknote`, or `exonumia`
- `scrapedAt`

**`byCoinId` mode additionally returns:** `rulerName`/`rulerId`/`rulerYears`/`rulerRole`, `currencyName`/`currencyYears`, `material`/`materialId`, `thicknessMm`, `faceValue`, `shape`, `technique`, `orientation`, `references`, `photoCredit`, `obverseDescription`/`obverseScript`/`obverseLettering`/`obverseTranslation`/`obverseEngraver` (and the `reverse*` equivalents), `edgeDescription`, `mints[]` (name + mint ID), `tags[]`, `notes` (community notes), `swapOffersCount`.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | select | `byCoinId` | `byCoinId` / `search` / `byIssuer` / `byRuler` / `byMaterial` / `byMint` / `byTag` / `byShape` / `byTechnique` / `byScript` |
| `searchQuery` | string | `morgan dollar` | Free-text query (mode=search). Quote a phrase for an exact match, use `*` as a wildcard, `-word` to exclude |
| `issuer` | select | – | Issuing country/entity — 187 curated options (mode=search refinement, mode=byIssuer) |
| `customIssuerSlug` | string | – | Advanced override for any issuer not in the dropdown |
| `coinIds` | array | `["1492"]` | Catalogue numbers or full URLs (mode=byCoinId) |
| `ruler` | select | – | Curated list of well-known rulers (mode=byRuler) |
| `customRulerId` | integer | – | Advanced override for any ruler ID |
| `material` | select | `Copper-nickel` | One of 62 materials (mode=byMaterial) |
| `mint` | select | – | Curated list of well-known mints (mode=byMint) |
| `customMintId` | integer | – | Advanced override for any mint ID |
| `tags` | array (multi-select) | – | One or more of 220 theme tags (mode=byTag) |
| `shape` | select | – | One of 79 physical shapes (mode=byShape) — round, square, scalloped, polygonal, etc. |
| `mintingTechnique` | select | – | One of 32 minting/printing techniques (mode=byTechnique) — hammered, milled, cast, offset-printed, etc. |
| `script` | select | – | One of 113 lettering scripts (mode=byScript) — Latin, Arabic, Chinese, Cyrillic, Devanagari, etc. |
| `faceValue` | string | – | Restrict any search/browse mode to a specific numeric face value (e.g. `5`, `25`), regardless of currency/denomination unit |
| `weight` | string | – | Restrict any search/browse mode to a weight in grams — a value (e.g. `9.5`, ±0.5g tolerance) or a range (e.g. `7.5-10`) |
| `diameter` | string | – | Restrict any search/browse mode to a diameter/size in mm — a value (e.g. `24`, ±0.5mm tolerance) or a range (e.g. `20-25`) |
| `width` | string | – | Restrict any search/browse mode to a width in mm (rectangular items, e.g. banknotes) — a value or range |
| `lettering` | string | – | Restrict any search/browse mode to items whose visible lettering matches this text — `*` as a wildcard for unreadable letters |
| `engraver` | string | – | Restrict any search/browse mode to items credited to this engraver/designer |
| `usableInYear` | string | – | Restrict any search/browse mode to currency in circulation in this year, or `now` for currency still in use today |
| `recordTypeFilter` | select | `all` | `all` / `coin` / `banknote` / `exonumia` |
| `yearMin` | integer | – | Drop items whose year is before this (client-side; combine both bounds to also narrow the server-side result set) |
| `yearMax` | integer | – | Drop items whose year is after this (client-side; combine both bounds to also narrow the server-side result set) |
| `swapAvailableOnly` | boolean | `false` | Only emit items listed for swap by a member |
| `maxItems` | integer | `20` | Hard cap on emitted records (1–50) |

#### Example: search with an issuer refinement

```json
{
  "mode": "search",
  "searchQuery": "morgan dollar",
  "issuer": "united-states",
  "maxItems": 20
}
```

#### Example: browse all coins/banknotes issued by a country

```json
{
  "mode": "byIssuer",
  "issuer": "barbade",
  "recordTypeFilter": "coin",
  "maxItems": 30
}
```

#### Example: exact lookup by catalogue ID

```json
{
  "mode": "byCoinId",
  "coinIds": ["1492", "https://en.numista.com/22693"]
}
```

#### Example: search refined by weight, diameter, and lettering

```json
{
  "mode": "search",
  "searchQuery": "dollar",
  "issuer": "united-states",
  "weight": "26.73",
  "diameter": "38.1",
  "lettering": "LIBERTY",
  "maxItems": 20
}
```

#### Example: browse by ruler

```json
{
  "mode": "byRuler",
  "ruler": "275",
  "maxItems": 25
}
```

#### Example: browse gold coins available for swap

```json
{
  "mode": "byMaterial",
  "material": "6",
  "swapAvailableOnly": true
}
```

#### Example: browse coins with a scalloped shape

```json
{
  "mode": "byShape",
  "shape": "15",
  "maxItems": 20
}
```

#### Example: browse hammered-struck coins

```json
{
  "mode": "byTechnique",
  "mintingTechnique": "2",
  "maxItems": 20
}
```

#### Example: browse coins lettered in Arabic script

```json
{
  "mode": "byScript",
  "script": "3",
  "maxItems": 20
}
```

#### Example: search refined to a specific face value

```json
{
  "mode": "search",
  "searchQuery": "dollar",
  "faceValue": "25",
  "maxItems": 20
}
```

### Use cases

- **Coin dealers & marketplaces** — enrich listings with composition, weight, and catalogue references
- **Numismatic research** — bulk-export a country's or ruler's coinage for cataloguing
- **Collection management tools** — pull structured metadata for a want-list or inventory
- **Price-guide / appraisal apps** — cross-reference catalogue numbers (KM#, Pick#) against your own database
- **Educational content** — source real mintage years, mint locations, and imagery for history/economics material
- **Theme collectors** — find every coin tagged with a subject (animals, ships, sports, independence, etc.)

### FAQ

**What's Numista?** A free, collaborative online catalogue of coins, banknotes, and exonumia maintained by a community of collectors, covering nearly every country and historical period. See [en.numista.com](https://en.numista.com).

**Do I need an account or API key?** No. This actor only reads Numista's public catalogue pages — no login, cookies, or API key needed.

**Why is `maxItems` capped at 50?** Numista serves catalogue search/browse results one page at a time; the actor fetches that first page (up to 50 items) per run. Narrow your query with `issuer`, `material`, `tags`, `shape`, `mintingTechnique`, `script`, or `faceValue` — these are sent straight to Numista, so they change which 50 items come back. `yearMin`/`yearMax` and `swapAvailableOnly`, by contrast, only filter *within* that same fetched page of 50 (Numista has no year/swap query parameter), so a narrow year range on a broad browse mode can legitimately return fewer items — or zero — if none of the ~50 fetched items happen to fall in range. Run the actor multiple times with different filters, or use `mode=search` with a specific query, to cover more ground.

**What's the difference between `issuer` and `customIssuerSlug`?** `issuer` is a curated dropdown of 187 common issuing countries/entities. `customIssuerSlug` lets you target any of Numista's thousands of issuers (including historical states, colonies, and private/local issuers) by typing its catalogue slug directly — find it in the URL of a `catalogue.numista.com/catalogue/<slug>-1.html` page.

**How does `byRuler`/`byMint` work if my ruler/mint isn't in the dropdown?** Use `customRulerId` / `customMintId` with the numeric ID from the ruler or mint's Numista URL (`ruler.php?id=...` / `mint.php?id=...`).

**What does `recordType` mean?** `coin` for coins and coin-like tokens, `banknote` for paper money and banknote-format collectibles, `exonumia` for tokens, medals, and other non-coin/non-banknote items.

**Why do some items lack `weightGrams`/`diameterMm`?** Those fields only apply to coins. Banknotes report `sizeText` instead, and some exonumia entries don't have every physical measurement catalogued.

**What is `swapAvailable`?** Whether at least one Numista community member currently lists that exact catalogue item as available to swap. It reflects the live marketplace at scrape time.

**How fresh is the data?** Numista's catalogue is community-maintained and updated continuously; this actor always reads the live page at run time.

**Why do `search`/browse modes sometimes return 0 results while `byCoinId` always works?** `byCoinId` fetches one specific catalogue page directly, which is consistently accessible. `search` and the taxonomy-browse modes rely on Numista's catalogue search pages, which are occasionally subject to the source site's own access restrictions independent of this actor. If you hit 0 results on a search/browse mode, retry later or use `byCoinId` with a known catalogue number in the meantime.

**Does Numista have an official API?** Yes, but it requires creating a Numista account and generating an API key, so it's out of scope for this actor (no login/API key required, per design). This actor reads the same public catalogue pages any visitor sees.

**Is this affiliated with the data source?** No, this is a third-party actor using Numista's public catalogue pages. It is not affiliated with, endorsed by, or sponsored by Numista.

# Actor input Schema

## `mode` (type: `string`):

What to fetch from the Numista catalogue.

## `searchQuery` (type: `string`):

Free-text query, e.g. `morgan dollar`, `1 franc`, `elizabeth ii crown`. Put quotes around a phrase for an exact match, use `*` as a wildcard, and a leading `-` to exclude a word.

## `issuer` (type: `string`):

Restrict results to coins/banknotes issued by this country or historical entity.

## `customIssuerSlug` (type: `string`):

Overrides `issuer` with any Numista issuer slug not in the dropdown (find it in a catalogue.numista.com/catalogue/<slug>-1.html URL).

## `coinIds` (type: `array`):

Numista catalogue numbers (e.g. `1492`) or full URLs (e.g. `https://en.numista.com/1492`).

## `ruler` (type: `string`):

A curated list of well-known rulers. Use `customRulerId` for any ruler not listed here.

## `customRulerId` (type: `integer`):

Overrides `ruler` with any Numista ruler ID not in the dropdown (find it in a ruler.php?id=<id> URL).

## `material` (type: `string`):

The metal or material the coin/token is made of.

## `mint` (type: `string`):

A curated list of well-known mints. Use `customMintId` for any mint not listed here.

## `customMintId` (type: `integer`):

Overrides `mint` with any Numista mint ID not in the dropdown (find it in a mint.php?id=<id> URL).

## `tags` (type: `array`):

One or more subject tags (e.g. animals, ships, sports). Selecting several narrows results to items matching all of them.

## `shape` (type: `string`):

The physical shape of the coin/token/banknote.

## `mintingTechnique` (type: `string`):

How the coin/token was struck (hammered, milled, cast...) or the banknote was printed (offset, lithography...).

## `script` (type: `string`):

The writing script used in the coin/banknote's lettering (e.g. Latin, Arabic, Chinese, Cyrillic).

## `faceValue` (type: `string`):

Restrict results to a specific numeric face value (e.g. `5`, `25`, `1.5`), regardless of currency/denomination unit. Combine with any search or browse mode.

## `weight` (type: `string`):

Restrict results to a weight in grams — a single value (e.g. `9.5`, with a built-in ±0.5g tolerance) or a range (e.g. `7.5-10`).

## `diameter` (type: `string`):

Restrict results to a diameter/size in millimetres — a single value (e.g. `24`, with a built-in ±0.5mm tolerance) or a range (e.g. `20-25`).

## `width` (type: `string`):

Restrict results to a width in millimetres (for rectangular items such as banknotes) — a single value or a range (e.g. `60-70`).

## `lettering` (type: `string`):

Restrict results to items whose visible obverse/reverse lettering matches this text. Use `*` as a wildcard for any unreadable letters (e.g. `UNITED STA*S`).

## `engraver` (type: `string`):

Restrict results to items credited to this engraver or designer.

## `usableInYear` (type: `string`):

Restrict results to currency that was in circulation in this year (e.g. `1950`), or `now` for currency still in use today.

## `recordTypeFilter` (type: `string`):

Restrict results to a single catalogue type (search/browse modes only).

## `yearMin` (type: `integer`):

Drop items whose (first) year is before this. Only applied when a single year could be parsed.

## `yearMax` (type: `integer`):

Drop items whose (first) year is after this. Only applied when a single year could be parsed.

## `swapAvailableOnly` (type: `boolean`):

Only emit items that at least one Numista member has listed as available for swap.

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

Hard cap on emitted records. Search/browse modes are limited to a single results page (Numista blocks deeper pagination), so the practical ceiling is 50.

## Actor input object example

```json
{
  "mode": "byCoinId",
  "searchQuery": "morgan dollar",
  "coinIds": [
    "1492"
  ],
  "material": "2",
  "tags": [],
  "recordTypeFilter": "all",
  "swapAvailableOnly": false,
  "maxItems": 20
}
```

# Actor output Schema

## `items` (type: `string`):

Dataset containing all scraped Numista catalogue items.

# 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 = {
    "mode": "byCoinId",
    "searchQuery": "morgan dollar",
    "coinIds": [
        "1492"
    ],
    "material": "2",
    "tags": [],
    "recordTypeFilter": "all",
    "swapAvailableOnly": false,
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/numista-coin-catalogue-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 = {
    "mode": "byCoinId",
    "searchQuery": "morgan dollar",
    "coinIds": ["1492"],
    "material": "2",
    "tags": [],
    "recordTypeFilter": "all",
    "swapAvailableOnly": False,
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/numista-coin-catalogue-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "mode": "byCoinId",
  "searchQuery": "morgan dollar",
  "coinIds": [
    "1492"
  ],
  "material": "2",
  "tags": [],
  "recordTypeFilter": "all",
  "swapAvailableOnly": false,
  "maxItems": 20
}' |
apify call crawlerbros/numista-coin-catalogue-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=crawlerbros/numista-coin-catalogue-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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