# NGC Coin Census Scraper - Population / Grade Data (`lulzasaur/ngc-coin-pop-scraper`) Actor

Scrape the NGC Coin Census (population report): how many coins are graded at each NGC grade. Look up any country, coin type, or series and get per-coin grade breakdowns (MS/PF 70 down to circulated and Details) with total population, year, denomination, mint mark, and variety.

- **URL**: https://apify.com/lulzasaur/ngc-coin-pop-scraper.md
- **Developed by:** [lulz bot](https://apify.com/lulzasaur) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $15.00 / 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/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

## NGC Coin Census Scraper — Population / Grade Data

Get **NGC coin census (population report) data** — how many coins are graded at each NGC grade — for any country, coin type, or series. This is the numismatic equivalent of a card population report: for every coin (year, mint mark, variety) it returns the full grade breakdown, from **MS/PF 70** down through circulated grades and **Details** (problem-coin) buckets, plus the total graded population.

Great for coin dealers, collectors, registry-set builders, price-guide makers, and anyone analyzing rarity and grade distribution.

### What you get

For each coin in a series:

| Field | Description |
|-------|-------------|
| `description` | Human-readable coin label, e.g. `1909-S VDB 1C MS RD` |
| `country` | Census category / country (e.g. United States) |
| `coinType` | Denomination category (e.g. Cents) |
| `series` | Series / group (e.g. Lincoln Cents) |
| `year`, `denomination`, `mintMark`, `strike`, `variety`, `designation` | Coin attributes (designation = MS, PF, etc.) |
| `populationByGrade` | Object mapping grade label → count, e.g. `{ "MS/PF 70": 12, "MS/PF 69": 340, ... }` — only non-zero grades are included |
| `totalPop` | Total coins graded for this coin |
| `listingUrl` | Link to the NGC census page for the series |
| `coinId`, `populationId` | NGC identifiers |

### Input

Navigate the census the same way the NGC website does: **Country → Coin Type → Series**.

```json
{
  "country": "United States",
  "coinType": "Cents",
  "series": "Lincoln",
  "maxResults": 1000
}
```

| Field | Description |
|-------|-------------|
| `country` | Country / census category. Default: United States |
| `coinType` | Denomination category (e.g. Cents, Dollars, Gold Double Eagles). Blank = all types |
| `series` | Series name filter (substring). Blank = all series in the coin type |
| `groupId` | Advanced: scrape one series directly by its NGC research group ID |
| `maxResults` | Max coin rows (0 = unlimited). Default 1000 |
| `maxSeries` | Max number of series to scrape (0 = unlimited) |
| `proxyConfiguration` | RESIDENTIAL proxy is used by default (NGC blocks datacenter IPs) |

#### Examples

Scrape one specific series directly:

```json
{ "groupId": 82 }
```

All Morgan / Peace dollars:

```json
{ "country": "United States", "coinType": "Dollars", "series": "Morgan" }
```

### Notes

- Data comes from NGC's public census. **Use the residential proxy** (default) — NGC blocks datacenter IPs.
- `populationByGrade` only lists grades with a non-zero count, keeping output compact.
- NGC grade scale includes Plus (`+`) and Star (`★`) designations, and `Details` buckets for coins with problems.

# Actor input Schema

## `country` (type: `string`):

Country / census category to scrape. Examples: 'United States', 'China', 'Canada', 'Great Britain', 'Mexico'. Defaults to United States.

## `coinType` (type: `string`):

Coin type within the country. Examples (US): 'Cents', 'Nickels', 'Dimes', 'Quarters', 'Half Dollars', 'Dollars', 'Gold Double Eagles', 'Commemoratives'. Leave blank to scan ALL coin types.

## `series` (type: `string`):

Optional series name filter (substring match). Examples: 'Lincoln', 'Morgan', 'Liberty Cap', 'Walking Liberty'. Leave blank to scrape all series in the coin type.

## `groupId` (type: `integer`):

Advanced: scrape one specific NGC series directly by its research group ID (skips country/coinType/series). Find it in a series page URL: .../population-report/<country>/<id>/<type>/<id>/<series>/\<GROUP\_ID>/all/

## `maxResults` (type: `integer`):

Maximum number of coin rows to output (0 = unlimited). Each row is one coin (year/mint/variety) with its full grade breakdown.

## `maxSeries` (type: `integer`):

Maximum number of series/groups to scrape (0 = unlimited). Useful to cap broad scrapes that span an entire country or coin type.

## `proxyConfiguration` (type: `object`):

NGC blocks datacenter IPs, so RESIDENTIAL proxy is strongly recommended (and used by default). Leave as-is unless you have a reason to change it.

## Actor input object example

```json
{
  "country": "United States",
  "maxResults": 200,
  "maxSeries": 0,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# 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 = {
    "country": "United States",
    "maxResults": 200,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("lulzasaur/ngc-coin-pop-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 = {
    "country": "United States",
    "maxResults": 200,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("lulzasaur/ngc-coin-pop-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 '{
  "country": "United States",
  "maxResults": 200,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call lulzasaur/ngc-coin-pop-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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