{ "openapi": "3.0.1", "info": { "title": "PublicSurplus Scraper - Government Surplus Auction Data API", "description": "Extract open PublicSurplus government surplus auctions: live bid count and price, closing time, selling agency, pick-up address, photos, attached documents, condition and vehicle specs including VIN, mileage and an optional NHTSA VIN decode.", "version": "0.1", "x-build-id": "idcTfhd0IAGWo3x3a" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~publicsurplus-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-publicsurplus-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/parseforge~publicsurplus-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-publicsurplus-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/parseforge~publicsurplus-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-publicsurplus-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", "properties": { "keyword": { "title": "Keyword", "type": "string", "description": "Word or phrase to search for. PublicSurplus matches it against the lot title AND the full description, so `truck` also finds a cabinet whose description mentions a hand-truck. Leave empty to take every open auction." }, "keywords": { "title": "More keywords", "type": "array", "description": "Run several keyword searches in one go. Each is a separate search on PublicSurplus and the results are merged, deduplicated by auction id.", "default": [], "items": { "type": "string" } }, "category": { "title": "Category", "type": "string", "description": "One of PublicSurplus's 28 categories or 204 sub-categories. Accepts the name (`motor pool`), a sub-category (`motor pool > truck`, or just `truck`), or the numeric id." }, "categoryIds": { "title": "More categories", "type": "array", "description": "Extra categories to sweep, by name or numeric id. Each becomes its own search.", "default": [], "items": { "type": "string" } }, "region": { "title": "State or province", "type": "string", "description": "Keep only auctions in one region. Accepts the name (`California`), the two-letter code (`CA`), or the site's own `all,ca`. Covers all 68 regions the site lists: 50 US states, DC, four US territories and 13 Canadian provinces and territories." }, "regions": { "title": "More states or provinces", "type": "array", "description": "Sweep several regions in one run. Each becomes its own search.", "default": [], "items": { "type": "string" } }, "agencyIds": { "title": "Agency IDs", "type": "array", "description": "Pull every open auction from specific agencies instead of searching. Use the `agencyId` from any row this Actor returns, which is the `orgid` in the agency's PublicSurplus URL. When set, the keyword, category and region filters are not sent — PublicSurplus has no agency-plus-keyword endpoint.", "default": [], "items": { "type": "string" } }, "auctionUrls": { "title": "Auction URLs", "type": "array", "description": "Specific auctions to fetch, skipping discovery entirely. Accepts a full https://www.publicsurplus.com/sms/auction/view?auc=… URL or the bare auction number.", "default": [], "items": { "type": "string" } }, "maxItems": { "title": "Max auctions", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of auctions written to the dataset. A ceiling, not a target — a narrow filter returns fewer. About 5,700 auctions are open site-wide at any moment.", "default": 50 }, "maxPages": { "title": "Max listing pages per search", "minimum": 1, "maximum": 250, "type": "integer", "description": "How deep discovery may page into one search before moving on. A search page holds 25 rows, an agency page 50. Discovery stops as soon as it has enough candidates, so this is a ceiling. Each page actually read is one listing-page event.", "default": 40 }, "priceMin": { "title": "Minimum price (USD)", "minimum": 0, "type": "integer", "description": "Keep only lots whose current price is at least this. Sent to PublicSurplus, so cheaper lots are never downloaded." }, "priceMax": { "title": "Maximum price (USD)", "minimum": 0, "type": "integer", "description": "Keep only lots whose current price is at most this. Leave both price fields at 0 to see every lot." }, "endingWithinHours": { "title": "Ending within", "enum": [ "1", "6", "24", "120", "240" ], "type": "string", "description": "Only auctions closing inside this window. PublicSurplus offers these five steps and no others." }, "startedWithinHours": { "title": "Started within", "enum": [ "1", "24", "48", "168" ], "type": "string", "description": "Only auctions that opened inside this window — the fastest way to poll for new listings. Mutually exclusive with `Ending within` on the site's own form." }, "zipCode": { "title": "ZIP code", "type": "string", "description": "Five-digit US ZIP code at the centre of a radius search. Needs `Miles from ZIP` to do anything." }, "milesFromZip": { "title": "Miles from ZIP", "enum": [ "20", "50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "1000" ], "type": "string", "description": "Radius around the ZIP code. PublicSurplus offers these steps and no others." }, "sortBy": { "title": "Sort by", "enum": [ "timeLeft", "price", "id", "title", "none" ], "type": "string", "description": "Order PublicSurplus returns the listing in. With several keywords, categories or regions the merged set is sorted again before rows are written.", "default": "timeLeft" }, "sortDescending": { "title": "Sort descending", "type": "boolean", "description": "Flip the sort — highest price first, newest auction id first, Z–A.", "default": false }, "auctionTypes": { "title": "Auction type", "type": "array", "description": "Keep only these kinds of lot. Leave empty for all three.", "items": { "type": "string", "enum": [ "bid", "fixed-price", "dutch" ], "enumTitles": [ "Bid auction", "Fixed price (buy it now)", "Dutch (multi-unit)" ] }, "default": [] }, "onlyWithBids": { "title": "Only lots with bids", "type": "boolean", "description": "Drop lots nobody has bid on yet.", "default": false }, "onlyWithoutBids": { "title": "Only lots with no bids", "type": "boolean", "description": "The opposite — keep only untouched lots. Useful for finding bargains that are about to close.", "default": false }, "minBidCount": { "title": "Minimum bid count", "minimum": 0, "type": "integer", "description": "Keep lots with at least this many bids." }, "maxBidCount": { "title": "Maximum bid count", "minimum": 0, "type": "integer", "description": "Keep lots with at most this many bids." }, "onlyWithImages": { "title": "Only lots with photos", "type": "boolean", "description": "Drop lots the agency published without a single photo.", "default": false }, "onlyWithVin": { "title": "Only lots with a VIN", "type": "boolean", "description": "Keep only vehicles carrying a valid 17-character VIN — the rows a VIN decode can enrich.", "default": false }, "onlyWithAttachments": { "title": "Only lots with documents", "type": "boolean", "description": "Keep only lots with an attached document, such as a title, inspection report or site map.", "default": false }, "states": { "title": "Keep only these states", "type": "array", "description": "Post-filter on the two-letter region code. Cheaper than `More states` when you already have a broad search running, because it does not fan out into separate searches.", "default": [], "items": { "type": "string" } }, "titleExcludes": { "title": "Exclude words", "type": "array", "description": "Drop lots whose title or description contains any of these words. Case-insensitive.", "default": [], "items": { "type": "string" } }, "listingOnly": { "title": "Listing only (skip the auction page)", "type": "boolean", "description": "Skip the lot's own page for a faster, shallower run: id, title, price, region, closing time, thumbnail and lot type, straight off the listing. Leave it off to also get the condition grade, the selling agency's name and the start date. This does not change the per-row price, and the page is read anyway if you tick an optional block below or set a filter that needs it.", "default": false }, "includeBidding": { "title": "Bidding state", "type": "boolean", "description": "Bid count, opening price, minimum bid, bid increment, the masked high-bidder handle with their years on the platform, reserve status, buy-it-now price and Dutch quantity.", "default": false }, "includeAgencyProfile": { "title": "Agency profile", "type": "boolean", "description": "The selling agency's numeric id, URL slug, storefront, logo and a link to every other lot it has open. The agency's name is in the base row either way.", "default": false }, "includePickupLocation": { "title": "Pick-up location", "type": "boolean", "description": "Location name, street, city, state and ZIP as separate columns, plus the site's map link.", "default": false }, "includeSaleTerms": { "title": "Sale terms", "type": "boolean", "description": "Accepted payment methods, the online card ceiling, the payment caveat, shipping arrangement, bid-deposit rule and the agency's terms document.", "default": false }, "includeItemSpecs": { "title": "Item specifications", "type": "boolean", "description": "The agency's own attribute block as typed columns: vehicle year, make, model, mileage, VIN, engine, transmission, tires and running condition; equipment manufacturer and hours; real-estate parcel number, property type, zoning, lot acres and building square feet. Plus the raw label/value pairs and the CARFAX link. Around 20% of lots carry one.", "default": false }, "includeVinDecode": { "title": "NHTSA VIN decode", "type": "boolean", "description": "For lots with a 17-character VIN, add 16 NHTSA vPIC columns — body class, fuel type, cylinders, displacement, drive type, GVWR class, assembly plant and more — from the US government's public vehicle database. One extra request per vehicle. Works on its own: you do not need the specs block to get the decoded columns.", "default": false }, "includeImages": { "title": "Photo URLs", "type": "boolean", "description": "Every full-resolution photo the agency uploaded, in order, plus the count.", "default": false }, "includeAttachments": { "title": "Attached documents", "type": "boolean", "description": "Documents the agency attached — titles, inspection reports, site maps — as name, URL and file-type triples, plus the count. Around 6% of lots carry one.", "default": false }, "includeDescription": { "title": "Description", "type": "boolean", "description": "The agency's full lot description. Some run to several thousand words.", "default": false }, "descriptionFormat": { "title": "Description format", "enum": [ "text", "html" ], "type": "string", "description": "`text` flattens the agency's markup into readable plain text; `html` keeps it as published. Only matters when the description is switched on.", "default": "text" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Off by default. PublicSurplus answers plain requests, so a run costs you nothing in proxy traffic. Turn it on only if your runs start getting rate-limited.", "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 } } } } } } } } } }