Public Surplus API & Scraper
Public Surplus is where US and Canadian cities, counties, school districts, universities, transit agencies and utilities auction what they no longer need: pickups and buses, forklifts and loaders, laptops and monitors, lab and medical instruments, desks and chairs, scrap, even land.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
About 6,650 auctions were live when measured, across 28 top-level and 211 sub-categories. This API turns the site into four calls. search filters by keyword, category, state or province, distance from a ZIP, price band, closing window and listing age, and every row carries the current price, the exact end time in UTC and the seconds left by the source's own clock. detail returns one auction in full: the selling agency with its id, the pick-up address, start and end time, whether the auction can extend, the bid count, the price and whether it is still the opening price, the increment and the minimum next bid, the bid-deposit rule, the high bidder's handle exactly as the source masks it, the agency's description, every photo, accepted payment methods, the shipping rule, the buyer's premium and the agency's disclaimer. seller_listings follows one agency's live lots, and categories returns the full tree with live counts. End times are the trap: the site prints every end time in Mountain time whatever state the agency is in, so this API reads the exact instant from the page's own countdown and returns UTC, with the printed label beside it.
What one search row carries
Measured on 250 rows: 25 per category across ten categories (Motor Pool, Computers, Heavy Equipment, Furniture, Medical, Industrial Equipment, Electronics, Outdoor Equipment, Office Equipment, Marine).
| Field | Fill | What it is |
|---|---|---|
| item_id / auction_id | 250/250 | The auction number detail takes. Same id, same type, on every round trip. |
| title | 250/250 | The lot title as the agency wrote it. |
| current_bid + price_display | 250/250 | The price as a number and the source's own string. The number matched the printed string on 250 of 250 rows. |
| ends_at | 250/250 | ISO-8601 UTC, read from the page's own countdown, not from the Mountain-time label. |
| seconds_remaining + source_time_left | 250/250 | Seconds left by Public Surplus's own clock, and its own human countdown string beside it. |
| state | 250/250 | Two-letter state or province of the selling agency. It matched the pick-up address state on every round trip where the address had one. |
| image_url | 250/250 | The lead photo. |
| title_matches_query | every row when query is given | Whether every query word is in the title. The source also matches the description, so this tells the two apart. |
The search page does not name the selling agency or the bid count, and it does not say whether the price is a standing bid or still the opening price. detail returns all three. Closed auctions are not public on Public Surplus — they ask for a login — so this API covers live auctions only.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/publicsurplus/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "truck",
"sort": "ending_soonest"
}
}{
"ok": true,
"meta": {
"api": "publicsurplus",
"endpoint": "search",
"mode": "live",
"latency_ms": 1050.8,
"record_count": 25,
"bytes": 167503,
"cache_hit": false,
"upstream_requests": 1,
"charged_credits": 2,
"version": "1.0.0",
"request_id": "39df5f7586774053",
"queue_ms": 1.3,
"fetched_at": "2026-10-07T15:52:11.720Z"
},
"data": {
"total": 252,
"page": 1,
"page_size": 25,
"last_page": 11,
"has_more": true,
"page_beyond_last": false,
"query": "truck",
"measured_at_utc": "2026-10-07T15:52:11Z",
"listings": [
{
"item_id": "4091351",
"auction_id": 4091351,
"title": "2012 Ford F350 Truck W/ Dump Bed - Low Miles, New Motor!",
"url": "https://www.publicsurplus.com/sms/auction/view?auc=4091351",
"current_bid": 7810,
"price_display": "$7,810.00",
"ends_at": "2026-10-07T17:00:00Z",
"seconds_remaining": 4068,
"ended": false,
"source_time_left": "1 hour 7 mins",
"state": "OH",
"image_url": "https://d37qv0n5b4mbzm.cloudfront.net/sms/docviewer/cdnmainaucdoc/thumb-b/4091351/71983835",
"title_matches_query": true
},
{
"item_id": "4094717",
"auction_id": 4094717,
"title": "Lot of thirty-four (34) pails of Misc Roofing Supplies",
"url": "https://www.publicsurplus.com/sms/auction/view?auc=4094717",
"current_bid": 500,
"price_display": "$500.00",
"ends_at": "2026-10-07T18:00:00Z",
"seconds_remaining": 7668,
"ended": false,
"source_time_left": "2 hours 7 mins",
"state": "CO",
"image_url": "https://d37qv0n5b4mbzm.cloudfront.net/sms/docviewer/cdnmainaucdoc/thumb-b/4094717/72077062",
"title_matches_query": false
},
{
"item_id": "4095365",
"auction_id": 4095365,
"title": "2009 FORD F350 CREW CAB (DIESEL)",
"url": "https://www.publicsurplus.com/sms/auction/view?auc=4095365",
"current_bid": 5000,
"price_display": "$5,000.00",
"ends_at": "2026-10-07T19:00:00Z",
"seconds_remaining": 11268,
"ended": false,
"source_time_left": "3 hours 7 mins",
"state": "TX",
"image_url": "https://d37qv0n5b4mbzm.cloudfront.net/sms/docviewer/cdnmainaucdoc/thumb-b/4095365/72006456",
"title_matches_query": false
}
]
}
}What the Public Surplus API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search LIVE Public Surplus auctions — the marketplace US and Canadian cities, counties, school districts, universities, transit agencies and utilities use to sell surplus vehicles, heavy equipment, computers, lab and medical gear, furniture and scrap. Filter by keyword, category, state or province, distance from a ZIP, price band, closing window and listing age. Every row carries the current price, the exact end time in UTC and the seconds left by the source's own clock. All parameters are optional; with none the call browses every live lot. | Pricing teams call search to search LIVE Public Surplus auctions. | query, category_id, state, zip, radius_miles, ... |
| detail | Everything Public Surplus publishes about one live auction: the selling agency (id, name, logo, storefront), the pick-up address, start and end time (end in UTC plus the source's own label), whether it can extend, bid count, current price, increment, minimum next bid, currency, bid deposit, the high bidder's handle exactly as the source masks it, condition, the agency's full description with its labelled fields (odometer, engine, VIN where typed), every photo, payment methods, shipping terms, buyer's premium and the agency disclaimer. | Marketplace operators call detail to get everything Public Surplus publishes about one live auction. | auction_id |
| seller_listings | Every live auction one selling agency currently has open, 50 per page — the agency id is detail's seller.seller_id. The way to watch one city, county or university's surplus as it is listed. | Catalog enrichment teams call seller_listings to get every live auction one selling agency currently has open, 50 per page. | seller_id, page |
| categories | The Public Surplus category tree with the live lot count on every sub-category, as the site's own all-categories page prints it. Ids are what search's category_id takes. | Retail analysts call categories to get the Public Surplus category tree with the live lot count on every sub-category, as the site's…. | flat |
Call search from your stack
curl -X POST https://api.reefapi.com/publicsurplus/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"truck","sort":"ending_soonest"}'import requests
r = requests.post(
"https://api.reefapi.com/publicsurplus/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "truck",
"sort": "ending_soonest"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/publicsurplus/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "truck",
"sort": "ending_soonest"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.publicsurplus.search with {"query":"truck","sort":"ending_soonest"}.Who uses this API and why
- Fleet and equipment buyers watching school-district and county surplus by state, distance and closing window.
- Refurbishers sourcing laptops, monitors and networking gear in bulk from universities and agencies.
- Bid-timing and alert tools that need a real UTC end time instead of a Mountain-time label.
- Lab and medical equipment resellers tracking instruments released by hospitals and research universities.
- Merging Public Surplus with GovDeals into one government-surplus feed on shared field names.
Questions developers ask before integrating
What timezone are the end times in?
Public Surplus prints every end time with a Mountain-time label (MDT when measured), whatever state the agency is in — a Connecticut hospital, a Texas county and an Arizona school district all said MDT. ends_at is therefore built from the exact instant inside the page's own countdown and returned as UTC, and ends_at_local, ends_at_zone_label and ends_at_offset_hours ship beside it. On every lot checked, the printed time plus six hours equalled ends_at to the minute.
How do I know if anyone has bid?
Call detail. A lot nobody has bid on shows an opening price, an empty bid count and no high bidder; detail returns price_basis opening_price and bid_count 0 for it, and price_basis current_bid with the real count otherwise. The source's own arithmetic checks out: the minimum next bid equalled current price plus increment on every bid-on lot and equalled the opening price on every unbid lot, 16 of 16 round trips.
Why does a keyword search return items without that word in the title?
Public Surplus matches the description too, including the agency's standard terms. Searching forklift returned 663 lots, but only 4 of the first 25 titles mentioned a forklift — the rest were lots whose terms mention loading by forklift. Each row carries title_matches_query, so you can keep title hits without a second call.
Which filters work?
Keyword, category or sub-category, state or province, ZIP plus radius, minimum and maximum price, closing within 1, 6, 24, 120 or 240 hours, and listed within 1, 24, 48 or 168 hours. Each was measured against two control searches in the same run. On 245 truck lots: Texas 10, California 24, Motor Pool 47, at least $1,000 89, at most $100 84, within 200 miles of 85718 13, closing within 24 hours 25. Price, state and closing-window filters were also checked row by row and no row broke them.
How deep can I page?
25 rows per page, fixed by the source. Paging is honest to the end: 245 truck lots gave 20 rows on page 10 and nothing past it, and last_page, has_more and page_beyond_last tell an overrun apart from a search that found nothing.
Can I follow one agency?
Yes. detail returns seller.seller_id, and seller_listings returns every live lot that agency has open, 50 per page. Harris County Purchasing had 12 pages when measured, the City of Roanoke 17 lots on one page.
What is not available?
Closed auctions and their final prices, the bid history, the question-and-answer thread and the agency contact person all require a Public Surplus login, so none of them is here. Everything this API returns is what a visitor sees without signing in.
What do the categories look like?
28 top-level categories and 211 sub-categories with live counts. Largest when measured: Computers 1,240, Electronics 709, Office Equipment 698, Industrial Equipment 682, Furniture 664, Motor Pool 544. Any id works as search's category_id, top-level or sub-category.
What is the Public Surplus API?
Public Surplus API is a ReefAPI endpoint group for city, county, school and university surplus auctions with the agency, the bid count and the end time in real utc. It returns live JSON through POST requests under /publicsurplus/v1.
Is the Public Surplus API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Public Surplus calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Public Surplus login or account?
No login to Public Surplus is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Public Surplus data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Public Surplus API use?
Public Surplus actions currently cost 2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Public Surplus from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call publicsurplus actions with the same key, credit pool and JSON envelope used by normal REST requests.