# HipStamp Scraper (`crawlerbros/hipstamp-scraper`) Actor

Scrape HipStamp - the philatelic (postage stamp) collector marketplace. Search by keyword, browse by issuing country/category, look up specific listings, or pull a seller's whole inventory. Get price, condition, catalog number, country, era, seller, and images.

- **URL**: https://apify.com/crawlerbros/hipstamp-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** E-commerce, 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/actors/running/actors-in-store.md#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

## HipStamp Scraper

Scrape **HipStamp** — the largest online marketplace dedicated to postage stamps and philatelic material. Search by keyword, browse by issuing country or category using HipStamp's own taxonomy, look up specific listings by ID or URL, or pull a seller's entire storefront. Get price, condition, catalog number, stamp type, issuing country, year of issue, seller/store details, and images. HTTP-only, no login required.

### What this actor does

- **Three modes:** `search` (keyword + rich filters), `byId` (specific listings), `bySeller` (a seller's whole store)
- **Real HipStamp taxonomy:** browse by 280+ issuing countries/regions and categories exactly as listed on the site (Europe, Great Britain, Africa, Topicals, Specialty Philately...)
- **Full filter set:** condition, stamp type, stamp format, centering grade, certificate/certificate grade, year of issue, price range, listing type (auction vs. fixed price), and promo flags (free shipping, on sale, listed today...)
- **Rich detail enrichment (optional, on by default):** visits each listing page to add country, catalog number, stamp type, condition, topic, year of issue, full description, seller/store info, seller's ships-from country, and the full photo gallery
- **Auction-aware:** current bid, bid count, and auction end time for live auctions
- **Sale-aware:** original (pre-markdown) price and discount percent for marked-down listings, plus whether a seller accepts offers
- **Empty fields are omitted**

### Output per listing

- `listingId`, `listingUrl`, `title`, `description`
- `price`, `currency`, `priceType` (`fixed` or `auction`)
- `listPrice`, `discountPercent`, `saleEndsAt` — original pre-markdown price, percent off, and when the markdown expires, when the listing is on sale (fixed-price listings only)
- `offersAccepted` — whether the seller accepts "Or Best Offer" on this listing
- `currentBid`, `bidCount`, `auctionEndsAt` — auction listings only
- `imageUrl` — primary listing image
- `imageUrls` — full photo gallery (all images the seller uploaded, in display order); only present when `fetchDetails` enrichment ran
- `freeShipping`, `shippingCost`, `sponsored`
- `country` — the stamp's issuing country/region (from the listing's own item specifics)
- `catalogNumber`, `stampType`, `condition`, `stampFormat`, `centering`, `topic`, `yearOfIssue`
- `hasCertificate`, `certificateGrade`, `returnPolicyDays`
- `itemSpecificsExtra` — any additional item-specific attributes the listing shows beyond the standard set
- `sellerUsername`, `sellerStoreUrl`, `storeName`, `storeUrl`, `sellerCountryCode` (seller/ships-from country, ISO 3166-1 alpha-2)
- `sellerFeedbackCount`, `sellerFeedbackPercent`, `sellerRegisteredSince`
- `recordType: "listing"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` / `byId` / `bySeller` |
| `searchQuery` | string | `penny black` | Free-text keyword (mode=search) |
| `category` | string | – | Browse by issuing country/region/category (mode=search) — real HipStamp taxonomy, e.g. `Europe - Germany & Colonies` |
| `sellerCountry` | string | – | Filter by seller/item location (mode=search) — distinct from `category` |
| `listingType` | string | `any` | `any` / `product` (Buy It Now) / `auction` |
| `condition` | array | – | Mint (NH), Unused, Used, First Day Cover, Cover (Postal History), Not Specified |
| `stampType` | array | – | General Issue, Air Mail, Booklets, Officials, Revenues, Semi-Postal, etc. |
| `stampFormat` | array | – | Single, Block, Pair, Plate Block, Souvenir Sheet, etc. |
| `centering` | array | – | Superb, XF, VF, Fine, VG & Below, etc. |
| `hasCertificate` | string | `any` | `any` / `yes` / `no` |
| `certificateGrade` | array | – | Numeric expert grades (100 down to 65 & Below) |
| `showOnly` | array | – | Free Shipping, Offers Accepted, Listed Today/This Week/This Month, On Sale, etc. |
| `yearFrom` / `yearTo` | int | – | Year-of-issue range (stamps begin in 1840) |
| `priceMin` / `priceMax` | int | – | Price range in USD |
| `sortBy` | string | `default` | Best Match, Catalog Number, Ending Soonest, Most Popular, Price, Newly Listed |
| `listingIds` | array | – | Listing IDs or URLs (mode=byId) |
| `sellerHandle` | string | `red-fox-stamps` | Store handle from the store URL (mode=bySeller) |
| `fetchDetails` | bool | `true` | Enrich each listing with full detail-page data (slower, much more complete) |
| `maxItems` | int | `40` | Hard cap on emitted records (1–2000) |
| `proxyConfiguration` | object | Apify Proxy (AUTO) | Optional; reduces the chance of transient rate-limit challenges |

#### Example: search with country + condition filters

```json
{
  "mode": "search",
  "searchQuery": "airmail",
  "category": "173",
  "condition": ["used"],
  "maxItems": 50
}
```

#### Example: browse auctions ending soonest in a price range

```json
{
  "mode": "search",
  "listingType": "auction",
  "sortBy": "ending_asc",
  "priceMin": 5,
  "priceMax": 200,
  "maxItems": 50
}
```

#### Example: look up specific listings

```json
{
  "mode": "byId",
  "listingIds": ["57776828", "https://www.hipstamp.com/listing/some-slug/68155649/"]
}
```

#### Example: a seller's whole store

```json
{
  "mode": "bySeller",
  "sellerHandle": "red-fox-stamps",
  "maxItems": 200
}
```

### Use cases

- **Collectors** — track new listings for a specific country, era, or catalog number
- **Dealers** — monitor competitor pricing and inventory across sellers
- **Price research** — pull historical asking prices by condition/grade for a given issue
- **Marketplace analytics** — analyze category/country trends across HipStamp's inventory
- **Collection building** — bulk-discover listings matching a specific want-list (country + year range + condition)

### FAQ

**What's HipStamp?**  A dedicated online marketplace for postage stamps and philatelic material, similar in spirit to eBay but stamp-only. See [hipstamp.com](https://www.hipstamp.com).

**Is this affiliated with HipStamp?**  No — this is a third-party actor that reads HipStamp's public listing pages.

**What's the difference between `category` and `sellerCountry`?**  `category` is the stamp's *issuing* country/region (HipStamp's own browse taxonomy — e.g. a US-based seller can list a stamp issued by Germany). `sellerCountry` filters by where the seller/item is physically located, which is a separate HipStamp filter.

**Why is `fetchDetails` on by default?**  Search-result cards only carry title, price, image, and seller username. Country, condition, catalog number, and the rest of the philatelic detail live on each listing's own page — `fetchDetails` visits it once per listing to fill those in. Turn it off for a faster, thinner pull.

**What's the difference between `price` and `currentBid`?**  For fixed-price (Buy It Now) listings, `price` is the asking price. For auctions, `price` mirrors `currentBid` — the current highest bid.

**Why do some listings lack a `country` or `topic` field?**  Sellers don't always fill in every item specific on HipStamp; only fields the seller actually populated are included.

**How fresh is the data?**  Real-time — every run reads HipStamp's live listing pages directly.

**Are prices in USD?**  Yes, all HipStamp listings are priced in USD.

**Why might `showOnly: ["free_shipping"]` occasionally include a listing that isn't marked free-shipping?**  It won't — `free_shipping`, `make_offer`, `on_sale`, `on_sale_25`, and `on_sale_50` are all re-checked against each listing's own extracted data (`freeShipping`, `offersAccepted`, `listPrice`/`discountPercent`) before being returned, so the emitted results are always accurate for those flags. Only the recency flags (Listed Today/This Week/This Month) rely on HipStamp's own server-side filtering, since there's no reliably-extracted listing-date field to re-verify against.

**What are `listPrice` and `discountPercent`?**  When a seller marks a fixed-price listing down from an original price, HipStamp shows both prices (the current price and a struck-through original price). `listPrice` is that original price and `discountPercent` is the percent off, both computed directly from the listing's own data — not estimates. Only present when a listing is actually on sale; not applicable to auctions.

**What's in `imageUrls`?**  The full photo gallery for the listing (every image the seller uploaded, not just the primary thumbnail), in the order they appear on the listing page. Populated only when `fetchDetails` is on, since the gallery lives on the listing's own detail page.

**What is `sellerCountryCode`?**  The seller's ships-from country, as a 2-letter ISO 3166-1 code (e.g. `US`, `GB`, `DE`) — taken from the listing's own shipping/return-policy data. This is different from `country` (the stamp's issuing country) and from the `sellerCountry` search filter (which filters by the same underlying seller location).

**What does `category` cover?**  HipStamp's real browse taxonomy: top-level regions (Europe, Africa, Asia, Great Britain, etc.) plus the individual issuing countries/territories nested under each region (e.g. Germany, France, Hong Kong under their respective regions), plus non-geographic groups like Topicals, Publications & Supplies, and Specialty Philately.

# Actor input Schema

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

What to fetch.

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

Free-text keyword search (mode=search), e.g. penny black, airmail, scott 231. Leave blank to browse by category/country/filters only.

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

Browse HipStamp's real taxonomy (mode=search): top-level regions (Europe, Africa, Asia...) or a specific issuing country/territory nested under a region (e.g. Europe - Germany and Colonies). Combine with searchQuery or use alone to browse.

## `sellerCountry` (type: `string`):

Filter to listings whose seller/item is located in this country (mode=search). Distinct from category, which is the stamp's issuing country.

## `listingType` (type: `string`):

Restrict to fixed-price (Buy It Now) listings or live auctions (mode=search).

## `condition` (type: `array`):

Filter by stamp condition (mode=search). Multi-select; leave empty for all conditions.

## `stampType` (type: `array`):

Filter by stamp type / back-of-book category (mode=search). Multi-select; leave empty for all types.

## `stampFormat` (type: `array`):

Filter by physical format (mode=search). Multi-select; leave empty for all formats.

## `centering` (type: `array`):

Filter by centering/grade (mode=search). Multi-select; leave empty for all grades.

## `hasCertificate` (type: `string`):

Filter by whether the listing has an expert certificate (mode=search).

## `certificateGrade` (type: `array`):

Filter by numeric certificate grade (mode=search). Multi-select; leave empty for all grades.

## `showOnly` (type: `array`):

Restrict to listings matching these promo/recency flags (mode=search). Multi-select; leave empty for no restriction.

## `yearFrom` (type: `integer`):

Drop listings issued before this year (mode=search). Stamps begin in 1840 (the Penny Black).

## `yearTo` (type: `integer`):

Drop listings issued after this year (mode=search).

## `priceMin` (type: `integer`):

Drop listings priced below this amount, in USD (mode=search).

## `priceMax` (type: `integer`):

Drop listings priced above this amount, in USD (mode=search).

## `sortBy` (type: `string`):

Result ordering (mode=search).

## `listingIds` (type: `array`):

HipStamp listing IDs (e.g. 57776828) or full listing URLs (mode=byId).

## `sellerHandle` (type: `string`):

A seller's store handle/slug from their store URL, e.g. red-fox-stamps from hipstamp.com/store/red-fox-stamps (mode=bySeller).

## `fetchDetails` (type: `boolean`):

Visit each listing's detail page to enrich records with country, catalog number, stamp type, condition, topic, year of issue, description, and seller/store info. Slower but much more complete. When off, only search-result-card fields are returned.

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

Hard cap on emitted records.

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

Optional. HipStamp does not require a proxy and direct connections are noticeably faster; only enable Apify Proxy if you hit transient blocking on a very high-volume run.

## Actor input object example

```json
{
  "mode": "search",
  "searchQuery": "penny black",
  "category": "",
  "sellerCountry": "",
  "listingType": "any",
  "condition": [],
  "stampType": [],
  "stampFormat": [],
  "centering": [],
  "hasCertificate": "any",
  "certificateGrade": [],
  "showOnly": [],
  "sortBy": "default",
  "listingIds": [],
  "sellerHandle": "red-fox-stamps",
  "fetchDetails": true,
  "maxItems": 40,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `listings` (type: `string`):

Dataset containing all scraped HipStamp listings.

# 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": "search",
    "searchQuery": "penny black",
    "category": "",
    "sellerCountry": "",
    "listingType": "any",
    "condition": [],
    "stampType": [],
    "stampFormat": [],
    "centering": [],
    "hasCertificate": "any",
    "certificateGrade": [],
    "showOnly": [],
    "sortBy": "default",
    "listingIds": [],
    "sellerHandle": "red-fox-stamps",
    "fetchDetails": true,
    "maxItems": 40,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/hipstamp-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": "search",
    "searchQuery": "penny black",
    "category": "",
    "sellerCountry": "",
    "listingType": "any",
    "condition": [],
    "stampType": [],
    "stampFormat": [],
    "centering": [],
    "hasCertificate": "any",
    "certificateGrade": [],
    "showOnly": [],
    "sortBy": "default",
    "listingIds": [],
    "sellerHandle": "red-fox-stamps",
    "fetchDetails": True,
    "maxItems": 40,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/hipstamp-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 '{
  "mode": "search",
  "searchQuery": "penny black",
  "category": "",
  "sellerCountry": "",
  "listingType": "any",
  "condition": [],
  "stampType": [],
  "stampFormat": [],
  "centering": [],
  "hasCertificate": "any",
  "certificateGrade": [],
  "showOnly": [],
  "sortBy": "default",
  "listingIds": [],
  "sellerHandle": "red-fox-stamps",
  "fetchDetails": true,
  "maxItems": 40,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call crawlerbros/hipstamp-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlerbros/hipstamp-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/RlMstzt1YNwHeTEW6/builds/XIaiR4Q1rHWS1gY5W/openapi.json