{ "openapi": "3.0.1", "info": { "title": "HipStamp Scraper", "description": "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.", "version": "1.0", "x-build-id": "XIaiR4Q1rHWS1gY5W" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~hipstamp-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-hipstamp-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~hipstamp-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-hipstamp-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~hipstamp-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-hipstamp-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "byId", "bySeller" ], "type": "string", "description": "What to fetch.", "default": "search" }, "searchQuery": { "title": "Search query", "type": "string", "description": "Free-text keyword search (mode=search), e.g. penny black, airmail, scott 231. Leave blank to browse by category/country/filters only." }, "category": { "title": "Category / issuing country", "enum": [ "", "1", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "50", "51", "52", "53", "54", "55", "56", "57", "58", "59", "60", "61", "62", "63", "288", "64", "65", "66", "67", "68", "69", "70", "71", "72", "74", "75", "76", "77", "78", "79", "80", "2", "81", "82", "83", "84", "85", "287", "86", "87", "88", "89", "90", "91", "92", "93", "94", "95", "96", "97", "98", "99", "100", "101", "102", "73", "103", "104", "3", "105", "106", "107", "108", "109", "110", "111", "112", "113", "114", "115", "117", "118", "119", "120", "121", "122", "123", "124", "125", "126", "127", "128", "4", "295", "296", "297", "298", "299", "300", "301", "302", "5", "6", "129", "130", "131", "132", "133", "134", "135", "136", "137", "138", "139", "140", "141", "142", "236", "237", "143", "144", "145", "146", "147", "148", "149", "150", "151", "9", "223", "224", "225", "226", "227", "229", "230", "231", "232", "233", "234", "235", "238", "239", "240", "241", "242", "243", "244", "245", "7", "152", "153", "154", "155", "156", "157", "158", "159", "160", "161", "162", "163", "164", "165", "167", "168", "169", "170", "171", "172", "173", "251", "174", "175", "176", "177", "178", "179", "180", "181", "182", "183", "184", "185", "186", "187", "188", "189", "190", "191", "192", "193", "194", "195", "196", "197", "198", "200", "201", "202", "203", "204", "205", "199", "206", "207", "208", "209", "210", "211", "212", "213", "214", "8", "10", "246", "247", "249", "250", "252", "253", "254", "255", "256", "257", "258", "259", "260", "261", "262", "263", "264", "265", "13", "275", "276", "277", "280", "278", "279", "14", "281", "283", "284", "286", "285", "303", "12", "11", "266", "267", "268", "290", "269", "270" ], "type": "string", "description": "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.", "default": "" }, "sellerCountry": { "title": "Seller / item location", "enum": [ "", "2375", "1866", "2376", "2373", "2377", "2378", "2379", "1874", "1875", "2380", "1877", "1878", "1879", "1880", "1881", "1882", "1883", "1884", "1885", "1886", "1887", "1888", "1889", "1890", "1891", "1892", "1893", "1894", "1895", "1896", "1897", "1898", "1899", "1900", "1901", "1902", "1903", "1904", "1905", "1906", "1907", "1908", "1909", "1910", "1911", "1912", "1913", "1914", "1915", "1916", "1917", "1918", "1919", "1920", "1921", "1922", "1923", "1924", "1925", "1926", "1927", "1928", "1929", "1931", "1932", "1933", "1934", "1935", "1936", "1937", "1938", "1939", "1940", "1941", "1942", "1943", "1944", "1945", "1946", "1947", "1948", "1949", "1950", "1951", "1952", "1954", "2368", "1955", "1956", "1957", "1958", "1959", "1960", "1961", "1962", "1963", "1964", "1965", "1966", "2381", "2354", "2370", "1968", "1969", "1970", "1971", "2369", "1972", "1973", "1974", "1975", "1976", "1977", "1978", "2367", "1980", "1981", "1982", "1983", "2382", "1984", "1985", "1986", "1987", "1988", "1989", "1990", "1991", "1992", "1993", "1994", "1995", "1996", "1997", "1998", "1999", "2000", "2001", "2002", "2003", "2004", "2383", "2005", "2006", "2007", "2008", "2009", "2010", "2011", "2012", "2013", "2014", "2015", "2016", "2017", "2018", "2019", "2020", "2022", "2023", "2024", "2025", "2026", "2027", "2028", "2029", "2030", "2031", "2032", "2033", "2035", "2036", "2037", "2038", "2039", "2040", "2041", "2042", "2043", "2044", "2045", "2046", "2048", "2353", "2049", "2050", "2051", "2052", "2053", "2054", "2055", "2056", "2057", "2058", "2059", "2060", "2061", "2062", "2063", "2064", "2065", "2066", "2067", "2068", "2069", "2070", "2071", "2072", "2073", "2074", "2075", "2076", "2077", "2078", "2079", "2080", "2081", "2082", "2083", "2084", "2085", "2086", "2087", "2088", "2089", "2090", "2093", "2094", "2095", "2096", "2097" ], "type": "string", "description": "Filter to listings whose seller/item is located in this country (mode=search). Distinct from category, which is the stamp's issuing country.", "default": "" }, "listingType": { "title": "Listing type", "enum": [ "any", "product", "auction" ], "type": "string", "description": "Restrict to fixed-price (Buy It Now) listings or live auctions (mode=search).", "default": "any" }, "condition": { "title": "Condition", "uniqueItems": true, "type": "array", "description": "Filter by stamp condition (mode=search). Multi-select; leave empty for all conditions.", "items": { "type": "string", "enum": [ "mint-nh-", "unused", "used", "first-day-cover", "cover-postal-history-", "not-specified" ], "enumTitles": [ "Mint (NH)", "Unused", "Used", "First Day Cover", "Cover (Postal History)", "Not Specified" ] }, "default": [] }, "stampType": { "title": "Stamp type", "uniqueItems": true, "type": "array", "description": "Filter by stamp type / back-of-book category (mode=search). Multi-select; leave empty for all types.", "items": { "type": "string", "enum": [ "general-issue", "air-mail", "booklets", "duck-stamps-federal", "locals-carriers", "military", "newspaper-stamps", "occupation", "offices-abroad-forerunner|offices-abroad", "officials", "parcel-post", "postage-due", "postal-cards", "postal-stationery-registration-stamps|postal-stationery", "revenues-postal-tax|revenues", "semi-postal", "special-delivery", "back-of-book-other-prefecture|back-of-book-other-machin-head|back-of-book-other-revolutionary-government|back-of-book-other-war-tax", "not-specified" ], "enumTitles": [ "General Issue", "Air Mail", "Booklets", "Duck Stamps - Federal", "Locals and Carriers", "Military", "Newspaper Stamps", "Occupation", "Offices Abroad", "Officials", "Parcel Post", "Postage Due", "Postal Cards", "Postal Stationery", "Revenues", "Semi-Postal", "Special Delivery", "Back of Book (Other)", "Not Specified" ] }, "default": [] }, "stampFormat": { "title": "Stamp format", "uniqueItems": true, "type": "array", "description": "Filter by physical format (mode=search). Multi-select; leave empty for all formats.", "items": { "type": "string", "enum": [ "single", "block", "error", "full-sheet", "miniature-sheet", "multiple", "pair", "plate-block", "plate-number-coil", "souvenir-sheet" ], "enumTitles": [ "Single", "Block", "Error", "Full Sheet", "Miniature Sheet", "Multiple", "Pair", "Plate Block", "Plate Number Coil", "Souvenir Sheet" ] }, "default": [] }, "centering": { "title": "Centering grade", "uniqueItems": true, "type": "array", "description": "Filter by centering/grade (mode=search). Multi-select; leave empty for all grades.", "items": { "type": "string", "enum": [ "superb", "xf-superb", "xf", "vf-xf", "vf", "f-vf", "fine", "vg-below", "not-specified" ], "enumTitles": [ "Superb", "XF/Superb", "XF", "VF/XF", "VF", "F/VF", "Fine", "VG and Below", "Not Specified" ] }, "default": [] }, "hasCertificate": { "title": "Has certificate", "enum": [ "any", "yes", "no" ], "type": "string", "description": "Filter by whether the listing has an expert certificate (mode=search).", "default": "any" }, "certificateGrade": { "title": "Certificate grade", "uniqueItems": true, "type": "array", "description": "Filter by numeric certificate grade (mode=search). Multi-select; leave empty for all grades.", "items": { "type": "string", "enum": [ "100", "98", "95", "90", "85", "80", "75", "70", "65-below", "not-graded", "not-specified" ], "enumTitles": [ "100 (Gem)", "98 (Superb)", "95 (XF/Superb)", "90 (XF)", "85 (VF/XF)", "80 (VF)", "75 (F/VF)", "70 (Fine)", "65 and Below", "Not Graded", "Not Specified" ] }, "default": [] }, "showOnly": { "title": "Show only", "uniqueItems": true, "type": "array", "description": "Restrict to listings matching these promo/recency flags (mode=search). Multi-select; leave empty for no restriction.", "items": { "type": "string", "enum": [ "free_shipping", "make_offer", "listed_today", "listed_this_week", "listed_this_month", "on_sale", "on_sale_25", "on_sale_50" ], "enumTitles": [ "Free Shipping", "Offers Accepted", "Listed Today", "Listed This Week", "Listed This Month", "Items On Sale", "On Sale 25% or More", "On Sale 50% or More" ] }, "default": [] }, "yearFrom": { "title": "Year of issue (from)", "minimum": 1840, "maximum": 2026, "type": "integer", "description": "Drop listings issued before this year (mode=search). Stamps begin in 1840 (the Penny Black)." }, "yearTo": { "title": "Year of issue (to)", "minimum": 1840, "maximum": 2026, "type": "integer", "description": "Drop listings issued after this year (mode=search)." }, "priceMin": { "title": "Price (min, USD)", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Drop listings priced below this amount, in USD (mode=search)." }, "priceMax": { "title": "Price (max, USD)", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Drop listings priced above this amount, in USD (mode=search)." }, "sortBy": { "title": "Sort order", "enum": [ "default", "catalog", "ending_asc", "popular_desc", "price_asc", "price_desc", "started_desc" ], "type": "string", "description": "Result ordering (mode=search).", "default": "default" }, "listingIds": { "title": "Listing IDs or URLs", "type": "array", "description": "HipStamp listing IDs (e.g. 57776828) or full listing URLs (mode=byId).", "default": [], "items": { "type": "string" } }, "sellerHandle": { "title": "Seller store handle", "type": "string", "description": "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": { "title": "Fetch full listing details", "type": "boolean", "description": "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.", "default": true }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Hard cap on emitted records.", "default": 40 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "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.", "default": { "useApifyProxy": false } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }