Reef AI: ask for any data. Try it
This page is the Mascus parameter reference. What the data is used for, a real sample and pricing are on Mascus API: what you get →
E-commerce & Marketplaces

Mascus API & Scraper: parameters and responses

This is the reference for the 8 Mascus endpoints under /mascus/v1 (search, detail, categories, facets, suggest, brands, seller and seller_listings) and their 36 parameters. Each endpoint lists its parameters, required or optional, with allowed values and defaults, and comes with a cURL, Python and JavaScript call; every response uses the same { ok, data, meta, error } envelope.

The Mascus API turns the global used heavy-machinery marketplace into JSON in eight actions.

8 actionsLive JSON1,000 free credits$0.67–$1.50 / 1,000 creditsMCP-ready
Get a free keyOpen in playground

🤖 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.

search walks the whole catalogue with the filters the source itself honours: sector, category and sub-category, make and model, condition, advert type, year window, price band, hour-meter band, odometer band, engine output, gross weight, seller country and region, has-a-price, has-a-photo, has-a-video and listed-in-the-last-N-days, sorted by price, year, listing date, hours, odometer, make or country, up to 200 rows a page. detail returns one listing in full, including every technical property the dealer typed, each with the source's own label in your chosen language, a language-free field name and a parsed number and unit. categories returns all 676 taxonomy nodes with live counts, facets returns the source's own counts for every make, country, region, condition and advert type that has stock for your query, suggest turns a half-typed word into values the filters will actually match, brands returns the makes the marketplace itself promotes per sector, and seller and seller_listings cover the supply side. The field that makes this worth an API rather than a scraper is the price, because this marketplace runs about forty country front-ends and every one of them converts. The same John Deere S240 shows as 1,850 USD, 1,651 EUR, 1,400 GBP, 7,228 PLN, 604,144 HUF and 292,688 JPY depending on which front-end answers; price and currency here are always the seller's own asking price, verified identical across six front-ends and four requested currencies, and the conversion comes back under its own name. The odometer has the same problem and gets the same treatment: the international front-end reports miles and the other thirty-eight kilometres, so mileage_km is normalised on every market and the odometer filter is always taken in kilometres. One ReefAPI key, the standard { ok, data, meta, error } envelope, no Mascus account.

Reference

The same machine, read through six country front-ends

Listing gu7q6jaj is a 2021 John Deere S240 whose seller priced it at 1,850 USD. This is what each front-end displays, and what the API returns. Measured 2026-10-08.

front-endwhat the site displaysprice / currencyprice_converted
com (international)1,850 USD1850 USD— (no conversion asked for)
de (Germany)1,651 EUR1850 USD1651 EUR
uk (United Kingdom)1,400 GBP1850 USD1400 GBP
pl (Poland)7,228 PLN1850 USD7228 PLN
hu (Hungary)604,144 HUF1850 USD604144 HUF
jp (Japan)292,688 JPY1850 USD292688 JPY

Ten readings of the same listing across six front-ends and four requested currencies returned exactly one price and currency pair: 1850 USD. Publishing the displayed number instead would make the same machine 1,850 or 604,144 depending on which host answered — a 326x error in a field that is always filled and always plausible.

Live example

Real request and response JSON

Captured from the indexed primary action, search, on .

Captured request
{
  "method": "POST",
  "url": "https://api.reefapi.com/mascus/v1/search",
  "headers": {
    "x-api-key": "$REEF_KEY",
    "content-type": "application/json"
  },
  "body": {
    "query": "excavator",
    "market": "com",
    "currency": "EUR",
    "page": 1,
    "page_size": 40
  }
}
Captured response
{
  "ok": true,
  "meta": {
    "api": "mascus",
    "endpoint": "search",
    "mode": "live",
    "latency_ms": 437.6,
    "record_count": 40,
    "bytes": 69277,
    "cache_hit": false,
    "total": 46575,
    "price_filter_currency": "EUR",
    "market": "com",
    "odometer_unit_on_this_market": "mi",
    "filters_applied": {
      "query": "excavator"
    },
    "pagination": {
      "page": 1,
      "page_size": 40,
      "last_page": 250,
      "retrievable_max": 10000,
      "has_more": true
    },
    "source_search_title": "excavator",
    "warnings": [
      "this query matches 46,575 listings but only the first 10,000 are retrievable; narrow it with a filter rather than paging, because past that ceiling the source re-serves page 1"
    ],
    "charged_credits": 3,
    "version": "1.0.0",
    "request_id": "c5230a17609f4c25",
    "queue_ms": 1.6,
    "fetched_at": "2026-10-31T13:02:54.696Z"
  },
  "data": {
    "listings": [
      {
        "listing_id": "E3A7485B",
        "asset_id": "hidm7n8q",
        "url": "https://www.mascus.com/construction/mini-diggers-excavators-7/john-deere-35-p/hidm7n8q.html",
        "listing_type": "classified",
        "brand": "John Deere",
        "model": "35 P",
        "year": 2024,
        "catalog": "construction",
        "category": "miniexcavators",
        "operating_hours": 12,
        "operating_hours_unit": "h",
        "mileage": null,
        "mileage_unit": null,
        "mileage_km": null,
        "mileage_km_exact": null,
        "price": 55000,
        "currency": "USD",
        "price_on_request": false,
        "price_eur": 48945,
        "price_converted": 48945,
        "price_converted_currency": "EUR",
        "location_city": "Indianapolis, Indiana",
        "location_country_code": "US",
        "seller": {
          "dealer_id": "C349AC7F",
          "name": "West Side Tractor Sales Co.- Indianapolis",
          "country": "US",
          "url": "https://www.mascus.com/west-side-tractor-sales-co-indianapolis/c349ac7f,1,relevance,searchdealer.html"
        },
        "image": "https://dnge9sb91helb.cloudfront.net/image/product/medium/johndeereus/john-deere-35-p,10141437_80520025_65726.jpg",
        "image_count": 22,
        "video_count": 0,
        "featured": false,
        "highlighted": false,
        "listed_last_24h": true,
        "listed_at": "2026-10-31T03:15:24.54"
      },
      {
        "listing_id": "5060C15D",
        "asset_id": "8f9ffg8s",
        "url": "https://www.mascus.com/construction/mini-diggers-excavators-7/bobcat-e20/8f9ffg8s.html",
        "listing_type": "auction",
        "brand": "Bobcat",
        "model": "E20",
        "year": 2016,
        "catalog": "construction",
        "category": "miniexcavators",
        "operating_hours": 1366,
        "operating_hours_unit": "h",
        "mileage": null,
        "mileage_unit": null,
        "mileage_km": null,
        "mileage_km_exact": null,
        "price": null,
        "currency": "USD",
        "price_on_request": true,
        "price_eur": null,
        "location_city": "Perris, California",
        "location_country_code": "US",
        "seller": {
          "dealer_id": "7D1826F8",
          "name": "Ritchie Bros Los Angeles",
          "country": "US",
          "url": "https://www.mascus.com/ritchie-bros-los-angeles/7d1826f8,1,relevance,searchdealer.html"
        },
        "image": "https://dnge9sb91helb.cloudfront.net/image/product/medium/rbauctionusatwo/bobcat-e20,b5044be3c08d48ea.jpg",
        "image_count": 32,
        "video_count": 0,
        "featured": false,
        "highlighted": false,
        "listed_last_24h": false,
        "listed_at": "2026-10-31T02:08:37",
        "auction": {
          "event_name": "California Regional Auction, USA - Nov 04, 2026",
          "starts_at": "2026-11-04T18:00:00",
          "ends_at": "2026-11-06T05:00:00",
          "country": "US",
          "city": "Perris, CA",
          "lot_url": "https://www.rbauction.com/pdp/2016-bobcat-e20-excavators/16205765",
          "auction_house_listing_id": "85A5B245-39F6-407D-B67B-8B86DCB9226E"
        }
      },
      {
        "listing_id": "E9B63DF5",
        "asset_id": "hoel6sik",
        "url": "https://www.mascus.com/construction/crawler-excavators/cat-335fl-cr-tracked-excavator/hoel6sik.html",
        "listing_type": "auction",
        "brand": "CAT",
        "model": "335FL CR Tracked Excavator",
        "year": 2018,
        "catalog": "construction",
        "category": "crawlerexcavators",
        "operating_hours": 3313,
        "operating_hours_unit": "h",
        "mileage": null,
        "mileage_unit": null,
        "mileage_km": null,
        "mileage_km_exact": null,
        "price": null,
        "currency": "USD",
        "price_on_request": true,
        "price_eur": null,
        "location_city": "Perris, California",
        "location_country_code": "US",
        "seller": {
          "dealer_id": "7D1826F8",
          "name": "Ritchie Bros Los Angeles",
          "country": "US",
          "url": "https://www.mascus.com/ritchie-bros-los-angeles/7d1826f8,1,relevance,searchdealer.html"
        },
        "image": "https://dnge9sb91helb.cloudfront.net/image/product/medium/rbauctionusatwo/cat-335fl-cr-tracked-e,5dbd37c9d22249ae.jpg",
        "image_count": 30,
        "video_count": 0,
        "featured": false,
        "highlighted": false,
        "listed_last_24h": false,
        "listed_at": "2026-10-31T02:08:34",
        "auction": {
          "event_name": "California Regional Auction, USA - Nov 04, 2026",
          "starts_at": "2026-11-04T18:00:00",
          "ends_at": "2026-11-06T05:00:00",
          "country": "US",
          "city": "Perris, CA",
          "lot_url": "https://www.rbauction.com/pdp/2018-cat-335flcrtrackedexcavator-excavators/16147196",
          "auction_house_listing_id": "5E40291E-7732-404C-A8EE-69F7B8C31F62"
        }
      }
    ]
  }
}
Actions

What the Mascus API does

ActionDescriptionConcrete use caseKey params
searchSearch or browse the whole marketplace. Combine a keyword with any of the typed filters the source supports natively — sector, category, sub-category, make, model, condition, advert type, year window, price band, hour-meter band, odometer band, engine output, gross weight, seller country and region, has-a-price, has-a-photo, has-a-video, listed-in-the-last-N-days — and sort by price, year, listing date, hours, odometer, make or country. Up to 200 rows a page. 🔴 Two things worth knowing before you build a loop: only the first 10,000 rows of any query are retrievable (past that the source silently re-serves page 1, so this endpoint refuses the call instead), and `price`/`currency` are the seller's own asking price — NOT the number the country front-end displays, which is a live conversion and differs by up to 326x between front-ends for the same machine.Pricing teams call search to search or browse the whole marketplace.market, currency, query, catalog, category, ...
detailOne listing in full, by id or URL. Returns the machine (make, model, model group, year, category path, hour meter, odometer normalised to kilometres), the price block (the seller's own asking price and currency, the EUR equivalent, the VAT rate, whether a price is published at all, and the source's own printed price rows), every technical property the seller typed — each with the source's own label in your chosen language, a language-free field name, and a parsed number and unit where there is one — the accessories list, the seller's free-text description in each language they wrote it in, the auction event with its bidding deadline and the auction house's own lot id, the rental day/week/month rates with and without VAT and the regions it can be hired in, the machine's own town, region, postcode, country and map coordinates, the dealer's business address and years on the marketplace, the finance/insurance/transport services offered, the full-size gallery and any videos, and the category breadcrumb.Marketplace operators call detail to get one listing in full, by id or URL.asset_id, url, market
categoriesThe marketplace's own taxonomy with live per-node listing counts: six sectors (construction 252,476 · transport 96,956 · agriculture 83,644 · material handling 27,455 · forestry 25,707 · groundcare 10,840) and, under each, the categories and sub-categories with the exact codes every other action's `category` and `subcategory` filters take. Pass a `category_code` to get one sector's sub-tree. Every count is the source's own live figure. 🔴 The filter code and the source's URL slug differ on three of the six sectors, so this is the action to read codes from rather than lifting them out of a URL.Catalog enrichment teams call categories to get the marketplace's own taxonomy with live per-node listing counts.market, category_code
facetsThe source's own live filter counts for a query: which makes, countries, regions, categories, conditions, advert types, accessories and emission levels have stock and how much of it. This is how you learn the exact spelling a filter wants (the source wants 'CAT', not 'Caterpillar', and region NAMES rather than codes) and how to split a query that is deeper than the 10,000-row retrievable ceiling. Every group says in `value_kind` whether its values are names, ISO codes or the source's own numeric property ids — the ids are what the filter takes, so they are published as they are rather than guessed at.Retail analysts call facets to get the source's own live filter counts for a query.market, currency, query, catalog, category, ...
suggestThe marketplace's own type-ahead for whatever a user has typed, in one list where every entry is tagged with its kind: make, model, model group, category (with the code the `category`/`subcategory` filters take) and dealer (with the id the `seller` action takes). Use it to turn free text into values the filters will actually match, instead of guessing a spelling the source answers with zero rows.Pricing teams call suggest to get the marketplace's own type-ahead for whatever a user has typed, in one list where every entry….query, market
brandsThe makes the marketplace itself promotes per sector, with a live listing count each — the source's own shortlist of the biggest manufacturers in construction, transport, agriculture, material handling, forestry and groundcare. A cheap, single-call answer to 'what is actually traded here and in what volume'. For the COMPLETE make list of a specific query, including the long tail, use `facets` and read its `brand` group.Marketplace operators call brands to get the makes the marketplace itself promotes per sector, with a live listing count each.market
sellerOne dealer's public business profile by id: company name, postal address (street, postcode, town, region, country), visiting address where they publish one, website, logo, their own description of the business, the makes they list themselves under, their branch outlets, map coordinates, and how long they have traded on this marketplace with the date that count runs from. 🔴 The source also returns a named salesperson, a direct e-mail, a mobile and a switchboard number on this object; none of it is returned here on any action. Use `seller_listings` for this dealer's stock.Catalog enrichment teams call seller to get one dealer's public business profile by id.dealer_id, market
seller_listingsOne dealer's full stock, as rows identical to `search`, with every `search` filter and sort available on top. 🔴 This is the action the source makes easiest to get wrong: handing its dealer filter the complete GUID answers HTTP 200 with 125 rows from FOUR different companies, because the GUID's middle segment is shared. This endpoint sends only the short id the source's own dealer links use, and then checks that what came back really belongs to one company before returning it — if it does not, you get an error rather than four dealers' machines labelled as one.Retail analysts call seller_listings to get one dealer's full stock, as rows identical to `search`, with every `search` filter and sort a….dealer_id, market, currency, query, catalog, ...
Code samples

Call search from your stack

curl -X POST https://api.reefapi.com/mascus/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"excavator","market":"com","currency":"EUR","page":1,"page_size":40}'
MCP one-liner
Ask your MCP-connected assistant: call reefapi.mascus.search with {"query":"excavator","market":"com","currency":"EUR","page":1,"page_size":40}.
Use cases

Who uses this API and why

  • Price a machine before you buy or sell it: narrow one make and model to a year window and an hour-meter band and you have the live comparable set — and because price is the seller's own currency on every row, the comparables are comparable without you unwinding six exchange rates first.
  • Source stock across 80 countries: filter by seller country and region, condition, price band, auction-only or rental-only, then pull the dealer behind any row with seller, or their whole inventory with seller_listings.
  • Watch a segment: sort by newest listing, poll a narrow query with listed_within_days, and read the auction wing's bidding deadlines straight off the rows that have them.
  • Build a filter UI without guessing a spelling: facets returns the source's own live counts for every make, country, region, condition and advert type that has stock for your query, with value_kind saying whether each group's values are names, ISO codes or the source's own property ids, and suggest maps whatever a user typed onto values the filters will match.
  • Track the market's shape: categories returns all 676 taxonomy nodes with live per-node counts in one call, which is how you see 252,476 construction machines split into 40,078 excavators and 20,810 crawler excavators.
FAQ

Questions developers ask before integrating

Which price does the API return, and does it change with the market?

It returns the seller's own asking price in the seller's own currency, and it does not change. That matters because the marketplace itself does change it: the same John Deere S240 displays as 1,850 USD on the international front-end and 1,651 EUR, 1,400 GBP, 7,228 PLN, 604,144 HUF and 292,688 JPY on the others. Read across six front-ends and four requested currencies, price and currency came back as 1850 USD every single time. The conversion is still there when you want it, as price_eur and as price_converted with price_converted_currency beside it, so it can never be mistaken for the asking price.

Is the odometer in kilometres or miles?

mileage_km is always kilometres, on every market. The source is not: a Kubota M5-111D reads 1,972 mil on the international front-end and 3,173 km on all thirty-eight others, the same machine. mileage and mileage_unit give you the reading as that front-end published it, and mileage_km_exact tells you when the normalised value is a back-conversion rather than the stored number, because the source stores kilometres and rounds them to whole miles for one host. The odometer filter, mileage_km_min and mileage_km_max, is always taken in kilometres and converted before the request leaves — the same 0 to 100,000 band answers 9,811 rows on one front-end and 7,051 on another if you send it raw.

How many rows can I get for one query?

10,000, at any page size, and the API refuses the call that would go past it rather than letting you page into nothing. This is the one limit worth knowing before you build a loop: past 10,000 the source answers HTTP 200 and serves page 1's rows under the page number you asked for, which was measured at four different page sizes. pagination.retrievable_max is 10,000, has_more is honest, and page_size goes to 200 so the ceiling is 50 calls away rather than 250. The way deeper is to narrow, and all 22 filters were measured to bite.

Is the hour meter the same field as the odometer?

No, and keeping them apart is deliberate. operating_hours is the hour meter, mileage is the odometer, and this source publishes one or the other per machine, never both — excavators and tractors carry hours, trucks and vans carry an odometer. Comparing a 9,110 to a 161,190 because they sat in one field would be the easiest wrong answer on this marketplace. The hour meter is also the one reading the source does not convert: the 0 to 2,000 hour band answers the same 412 rows on every front-end.

Why do so many listings have no price?

Because about half of this marketplace is auction lots and price-on-request dealer stock. Measured over 700 rows from 14 different queries, 337 had no price. That is returned as a state and not as a gap: price_on_request is true, price is null, and the currency is still published because the source does know which currency the machine would have been priced in. A price of 0 on this source means the same thing as null, which is why neither is ever returned as a number. Set with_price if you only want priced comparables; that alone takes a 46,041-row query to 32,308.

What happens if I send a filter value or a filter name the source does not know?

You get a clear error instead of the wrong answer. Three of this source's filter names and two of its value sets are accepted with HTTP 200 and then silently ignored, which returns the whole unfiltered catalogue looking filtered — a year window built the obvious way is one of them. So every enum and every parameter name is checked before the request leaves, and anything this endpoint does not know is reported in meta.warnings rather than forwarded. Where the source IS honest, it is left alone: an unknown make or country is answered with zero rows, and that is passed through as the answer it is.

Which markets are supported, and do they share one catalogue?

39 country front-ends, and yes — one shared catalogue, so market picks the language the labels come back in and nothing about the inventory. Each of the 39 was verified by loading a real listing on that host and confirming its label vocabulary came back populated. Three front-ends the marketplace itself links, mascus.fr, mascus.es and mascus.com.br, serve their home page but answer HTTP 404 for every listing, checked repeatedly; they return MARKET_UNAVAILABLE rather than a half-filled answer.

Can I get one dealer's whole inventory?

Yes, with seller_listings, and it is checked before it is returned. This is the action the source makes easiest to get wrong: handing its dealer filter the complete GUID answers HTTP 200 with 125 rows from four different companies, because the GUID's middle segment is shared between them. The endpoint sends only the short dealer id the source's own links use and then asserts that every row it got back really belongs to one company — if it does not, you get an error rather than four dealers' machines labelled as one. seller returns that dealer's business profile beside it.

What do I get about the dealer, and what is left out?

Business facts and nothing personal: company name, street, postcode, town, region, country, visiting address where they publish one, website, logo, their own description, branch outlets, coordinates and how many years they have traded on the marketplace with the date that count runs from. The source also returns a named salesperson, a direct e-mail, a mobile and a switchboard number on the same records; none of them is returned by any action here. The one thing passed through verbatim is the seller's own advert text, which is the machine's description and occasionally has a phone number typed into it by the dealer.

How fast is it, and how reliable?

One request to the source per call, with a median of 631 ms and a 95th percentile of 1.5 s. A run across all eight actions and six different front-ends was 20 of 20.

Does a free-text search give the same results on every market?

No, and this is worth knowing if you need reproducibility. Free text is scored in the chosen front-end's own language, so the same word is a different query per market: 'excavator' answered 46,041 rows on the international front-end and 46,118 on the German one, and the first 40 rows of the two answers had not one listing in common. A make-and-model query such as 'Kubota M5-111D' does match identically on both. Pin a result set you need to reproduce with the typed filters or a dealer id, not with a word.

What is the Mascus API?

Mascus API is a ReefAPI endpoint group for the global used heavy-machinery marketplace as json: ~497,000 live listings of construction plant, trucks, agricultural and forestry machines from dealers in 80 countries, each with the seller's own asking price in the seller's own currency — not the number the country front-end converts it into. It returns live JSON through POST requests under /mascus/v1.

Is the Mascus API free to try?

Yes. ReefAPI starts with 1,000 free credits, no card required. Mascus calls use the same shared credit balance as every other ReefAPI engine.

Do I need a Mascus login or account?

No login to Mascus 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.

docs / mascus

Mascus

The global used heavy-machinery marketplace as JSON: ~497,000 live listings of construction plant, trucks, agricultural and forestry machines from dealers in 80 countries, each with the seller's own asking price in the seller's own currency — not the number the country front-end converts it into.

base /mascus/v18 endpoints
post/mascus/v1/detail3 credits

One listing in full, by id or URL. Returns the machine (make, model, model group, year, category path, hour meter, odometer normalised to kilometres), the price block (the seller's own asking price and currency, the EUR equivalent, the VAT rate, whether a price is published at all, and the source's own printed price rows), every technical property the seller typed — each with the source's own label in your chosen language, a language-free field name, and a parsed number and unit where there is one — the accessories list, the seller's free-text description in each language they wrote it in, the auction event with its bidding deadline and the auction house's own lot id, the rental day/week/month rates with and without VAT and the regions it can be hired in, the machine's own town, region, postcode, country and map coordinates, the dealer's business address and years on the marketplace, the finance/insurance/transport services offered, the full-size gallery and any videos, and the category breadcrumb.

ParameterAllowed / rangeDescription
asset_idoptional—The listing id, as every search row returns it in `asset_id` and as the last segment of any listing URL (a full URL is accepted and the id taken out of it; the source ignores every other path segment, so the slug need not be right). 🔴 An id here is not always valid on every front-end: measured, the id the international front-end prints resolves on three front-ends while the id the German one prints for the SAME machine answers HTTP 404 on the other two. Prefer the row's `url`; an id that does not resolve on the `market` asked for is tried on the two widest front-ends and `meta` says which one answered.
urloptional—A listing URL instead of an id — whichever you happen to have. Either `asset_id` or `url` is required.
market = comoptionalcom · uk · ie · au · nz · za · de · at · lu · nl · be · it · pt · mx · pl · cz · sk · hu · ro · bg · hr · si · rs · me · gr · se · no · dk · fi · ee · lt · lv · ua · ua_ru · tr · jp · kr · tw · arWhich country front-end to read. All 39 share ONE catalogue, so this does NOT pick a different inventory: it picks the language of the labels on `detail`, `categories` and `suggest`, and 🔴 the UNITS — the international front-end ('com') reports the odometer in MILES, the other 38 in kilometres. `mileage_km` is normalised on every market and `mileage_km_min/max` is always in kilometres, so you never have to care. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE rather than a half-filled answer.
Try in playground →
post/mascus/v1/categories1 credit

The marketplace's own taxonomy with live per-node listing counts: six sectors (construction 252,476 · transport 96,956 · agriculture 83,644 · material handling 27,455 · forestry 25,707 · groundcare 10,840) and, under each, the categories and sub-categories with the exact codes every other action's `category` and `subcategory` filters take. Pass a `category_code` to get one sector's sub-tree. Every count is the source's own live figure. 🔴 The filter code and the source's URL slug differ on three of the six sectors, so this is the action to read codes from rather than lifting them out of a URL.

ParameterAllowed / rangeDescription
market = comoptionalcom · uk · ie · au · nz · za · de · at · lu · nl · be · it · pt · mx · pl · cz · sk · hu · ro · bg · hr · si · rs · me · gr · se · no · dk · fi · ee · lt · lv · ua · ua_ru · tr · jp · kr · tw · arWhich country front-end to read. All 39 share ONE catalogue, so this picks the LANGUAGE this action answers in, not a different inventory. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE.
category_codeoptional—Return this node's sub-tree instead of the whole taxonomy. Takes a sector code ('construction', 'agriculture') and narrows the answer to that sector's categories and sub-categories with their live counts.
Try in playground →
post/mascus/v1/facets2 credits

The source's own live filter counts for a query: which makes, countries, regions, categories, conditions, advert types, accessories and emission levels have stock and how much of it. This is how you learn the exact spelling a filter wants (the source wants 'CAT', not 'Caterpillar', and region NAMES rather than codes) and how to split a query that is deeper than the 10,000-row retrievable ceiling. Every group says in `value_kind` whether its values are names, ISO codes or the source's own numeric property ids — the ids are what the filter takes, so they are published as they are rather than guessed at.

ParameterAllowed / rangeDescription
market = comoptionalcom · uk · ie · au · nz · za · de · at · lu · nl · be · it · pt · mx · pl · cz · sk · hu · ro · bg · hr · si · rs · me · gr · se · no · dk · fi · ee · lt · lv · ua · ua_ru · tr · jp · kr · tw · arWhich country front-end to read. All 39 share ONE catalogue, so this does NOT pick a different inventory: it picks the language of the labels on `detail`, `categories` and `suggest`, and 🔴 the UNITS — the international front-end ('com') reports the odometer in MILES, the other 38 in kilometres. `mileage_km` is normalised on every market and `mileage_km_min/max` is always in kilometres, so you never have to care. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE rather than a half-filled answer.
currency = EURoptional—The currency to convert into, one of the 131 the source supports (EUR, USD, GBP, PLN, SEK, CZK, HUF, TRY, JPY, ZAR…). 🔴 Two measured consequences. (1) `price_min`/`price_max` are bands IN THIS CURRENCY: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. (2) The conversion appears as `price_converted` + `price_converted_currency`, never as `price` — `price` and `currency` are always the seller's own asking price and do not move with this parameter.
queryoptional—Free-text keyword, as typed into the marketplace's own search box: a machine type ('excavator', 'bagger'), a make, a model, or several words. Extra words NARROW here rather than widen — measured: 'excavator' 46,033 rows, 'caterpillar 320' 2,273 — and an unmatched word gives an honest empty answer. 🔴 FREE TEXT IS SCORED IN THE CHOSEN FRONT-END'S OWN LANGUAGE, so the same word is a different query per market: 'excavator' answered 46,041 rows on the international front-end and 46,118 on the German one, and the first 40 rows of the two had NOT ONE listing in common (a make-and-model query such as 'Kubota M5-111D' does match identically on both). A result set that must be reproducible across markets has to be pinned with the typed filters or a dealer, not with free text.
catalogoptionalconstruction · cargo-transport · agriculture · materialhandling · forestry · groundscareOne of the marketplace's six sectors. Comma-separate for several. 🔴 The value is the sector CODE, which differs from the URL slug on three of the six ('cargo-transport' not 'transportation', 'materialhandling' not 'material-handling', 'groundscare' not 'groundcare') — a value guessed off a URL returns zero rows, so the codes are published and validated here.
categoryoptional—Category code inside a sector, as the `categories` action returns it ('excavators', 'tractors', 'trucks', 'forklifts'). Comma-separate for several. An unknown code is answered honestly with zero rows rather than ignored, but reading the code out of `categories` or `suggest` is the way to be sure.
subcategoryoptional—The third taxonomy level ('crawlerexcavators', 'miniexcavators', 'wheelexcavators'), from the `categories` action with a `category_code` set. This is how you get from 40,068 excavators to the 20,806 crawler excavators.
brandoptional—Make, spelled the way the source's own facet spells it ('CAT' not 'Caterpillar', 'John Deere', 'Volvo', 'Mercedes-Benz'). Case does not matter, the spelling does — read it from `facets` or let `suggest` map what a user typed. Measured to bite: 46,035 rows for 'excavator' → 9,913 for CAT.
modeloptional—Model name, as the source's own type-ahead spells it. Only works with `brand` — a bare model name is ambiguous across makes, so it is rejected rather than returning an answer that looks filtered. Measured: brand=CAT + model=320 → 1,553 rows.
countryoptional—Seller country, 2-letter ISO code. Comma-separate for several. 80 countries have stock on a typical query; the `facets` action lists them with counts. Measured to bite: 46,035 → 3,494 for DE.
regionoptional—Seller region or province, by the NAME the source prints ('Bayern', 'Tennessee', 'Västernorrlands län') — not a code; `facets` returns the names that have stock. Measured to bite: 'Bayern' → 132 rows.
conditionoptionalused · new · reconditioned · remanufactured · demo · vintage · damaged · dismantled · operates_with_deficiencies · rental_possibilityCondition class. Comma-separate for several. The source stores these as numeric property ids; this takes the words and sends the ids. Measured: 46,035 → 4,458 for 'new'.
ad_typeoptionalusedad · auctionad · rentaladThe structural kind of advert. 🔴 An unknown value is NOT an error on this source: it is dropped and you get the whole unfiltered catalogue with HTTP 200, so this endpoint validates it instead of forwarding it. Measured to bite: 46,035 → 5,116 auction lots, → 333 rental machines.
year_minoptional1900–2100Earliest year of construction, inclusive. 🔴 The source's own name for this filter is not the obvious one and the obvious one is accepted with HTTP 200 and then ignored, so a naive year window returns the unfiltered catalogue looking filtered. Here it bites: 46,035 → 11,205 for 2015-2020.
year_maxoptional1900–2100Latest year of construction, inclusive. Note the source carries seller-entered years as far ahead as 2027, so an open-ended upper bound is not the same as 'up to this year'.
price_minoptional0–Lowest price to include, 🔴 IN THE `currency` YOU ASKED FOR (default EUR), not in the seller's currency. Measured: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. Any price bound also excludes the listings that publish no price at all and the source's own 0 and 1 placeholder prices.
price_maxoptional0–Highest price to include, 🔴 in the `currency` you asked for (default EUR), not in the seller's currency. Setting it also excludes every listing that publishes no price at all.
operating_hours_minoptional0–Lowest hour-meter reading to include, in hours — the field a used-plant buyer prices on. Verified front-end independent, unlike the odometer: the 0-2,000 h band answers the same 412 rows on the international and the German front-end.
operating_hours_maxoptional0–Highest hour-meter reading to include, in hours. Measured to bite: 46,035 → 412 for 0-2,000 h on the transport sector.
mileage_km_minoptional0–Lowest odometer reading to include, 🔴 ALWAYS IN KILOMETRES. The source filters in the front-end's own unit — the same 0-100,000 band answers 9,811 rows on the international front-end (miles) and 7,051 on the German one — so the unit is fixed at kilometres here and converted before the request leaves. Separate from `operating_hours_*` on purpose: the source publishes only one of the two per machine and they are not comparable.
mileage_km_maxoptional0–Highest odometer reading to include, 🔴 always in kilometres whatever `market` is set to — the source filters in the front-end's own unit and this endpoint converts before the request leaves.
with_price = falseoptional—Only listings that publish a price. Most of this marketplace does not — auction lots carry none at all and many dealers list 'price on request' — so this is the most useful narrowing filter for a pricing job. Measured: 46,035 → 32,305.
dealer_idoptional—Restrict to one dealer's stock, by the 8-character id the source's own dealer links use (also on every row as `seller.dealer_id`). 🔴 The full GUID is accepted by the source and answers 125 rows from FOUR different companies because its middle segment is shared, so a full GUID passed here is shortened for you and the answer is checked to contain exactly one company before it is returned.
Try in playground →
post/mascus/v1/suggest1 credit

The marketplace's own type-ahead for whatever a user has typed, in one list where every entry is tagged with its kind: make, model, model group, category (with the code the `category`/`subcategory` filters take) and dealer (with the id the `seller` action takes). Use it to turn free text into values the filters will actually match, instead of guessing a spelling the source answers with zero rows.

ParameterAllowed / rangeDescription
queryrequired—What the user has typed so far, from 2 characters up. The answer mixes makes, models, model groups, categories and dealers, each tagged with its kind and carrying the value the matching filter wants — so a UI never has to guess a spelling the source would answer with zero rows.
market = comoptionalcom · uk · ie · au · nz · za · de · at · lu · nl · be · it · pt · mx · pl · cz · sk · hu · ro · bg · hr · si · rs · me · gr · se · no · dk · fi · ee · lt · lv · ua · ua_ru · tr · jp · kr · tw · arWhich country front-end to read. All 39 share ONE catalogue, so this picks the LANGUAGE this action answers in, not a different inventory. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE.
Try in playground →
post/mascus/v1/brands1 credit

The makes the marketplace itself promotes per sector, with a live listing count each — the source's own shortlist of the biggest manufacturers in construction, transport, agriculture, material handling, forestry and groundcare. A cheap, single-call answer to 'what is actually traded here and in what volume'. For the COMPLETE make list of a specific query, including the long tail, use `facets` and read its `brand` group.

ParameterAllowed / rangeDescription
market = comoptionalcom · uk · ie · au · nz · za · de · at · lu · nl · be · it · pt · mx · pl · cz · sk · hu · ro · bg · hr · si · rs · me · gr · se · no · dk · fi · ee · lt · lv · ua · ua_ru · tr · jp · kr · tw · arWhich country front-end to read. All 39 share ONE catalogue, so this picks the LANGUAGE this action answers in, not a different inventory. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE.
Try in playground →
post/mascus/v1/seller2 credits

One dealer's public business profile by id: company name, postal address (street, postcode, town, region, country), visiting address where they publish one, website, logo, their own description of the business, the makes they list themselves under, their branch outlets, map coordinates, and how long they have traded on this marketplace with the date that count runs from. 🔴 The source also returns a named salesperson, a direct e-mail, a mobile and a switchboard number on this object; none of it is returned here on any action. Use `seller_listings` for this dealer's stock.

ParameterAllowed / rangeDescription
dealer_idrequired—The dealer's 8-character id, as every search row returns it in `seller.dealer_id`, as `suggest` returns it for a dealer match, and as the source's own dealer links carry it. A full GUID is shortened for you.
market = comoptionalcom · uk · ie · au · nz · za · de · at · lu · nl · be · it · pt · mx · pl · cz · sk · hu · ro · bg · hr · si · rs · me · gr · se · no · dk · fi · ee · lt · lv · ua · ua_ru · tr · jp · kr · tw · arWhich country front-end to read. All 39 share ONE catalogue, so this picks the LANGUAGE this action answers in, not a different inventory. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE.
Try in playground →
post/mascus/v1/seller_listings3 credits

One dealer's full stock, as rows identical to `search`, with every `search` filter and sort available on top. 🔴 This is the action the source makes easiest to get wrong: handing its dealer filter the complete GUID answers HTTP 200 with 125 rows from FOUR different companies, because the GUID's middle segment is shared. This endpoint sends only the short id the source's own dealer links use, and then checks that what came back really belongs to one company before returning it — if it does not, you get an error rather than four dealers' machines labelled as one.

ParameterAllowed / rangeDescription
dealer_idrequired—The dealer's 8-character id, as every search row returns it in `seller.dealer_id`, as `suggest` returns it for a dealer match, and as the source's own dealer links carry it. A full GUID is shortened for you.
market = comoptionalcom · uk · ie · au · nz · za · de · at · lu · nl · be · it · pt · mx · pl · cz · sk · hu · ro · bg · hr · si · rs · me · gr · se · no · dk · fi · ee · lt · lv · ua · ua_ru · tr · jp · kr · tw · arWhich country front-end to read. All 39 share ONE catalogue, so this does NOT pick a different inventory: it picks the language of the labels on `detail`, `categories` and `suggest`, and 🔴 the UNITS — the international front-end ('com') reports the odometer in MILES, the other 38 in kilometres. `mileage_km` is normalised on every market and `mileage_km_min/max` is always in kilometres, so you never have to care. Three front-ends the marketplace itself links (mascus.fr, mascus.es, mascus.com.br) answer HTTP 404 for every listing and return MARKET_UNAVAILABLE rather than a half-filled answer.
currency = EURoptional—The currency to convert into, one of the 131 the source supports (EUR, USD, GBP, PLN, SEK, CZK, HUF, TRY, JPY, ZAR…). 🔴 Two measured consequences. (1) `price_min`/`price_max` are bands IN THIS CURRENCY: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. (2) The conversion appears as `price_converted` + `price_converted_currency`, never as `price` — `price` and `currency` are always the seller's own asking price and do not move with this parameter.
queryoptional—Free-text keyword, as typed into the marketplace's own search box: a machine type ('excavator', 'bagger'), a make, a model, or several words. Extra words NARROW here rather than widen — measured: 'excavator' 46,033 rows, 'caterpillar 320' 2,273 — and an unmatched word gives an honest empty answer. 🔴 FREE TEXT IS SCORED IN THE CHOSEN FRONT-END'S OWN LANGUAGE, so the same word is a different query per market: 'excavator' answered 46,041 rows on the international front-end and 46,118 on the German one, and the first 40 rows of the two had NOT ONE listing in common (a make-and-model query such as 'Kubota M5-111D' does match identically on both). A result set that must be reproducible across markets has to be pinned with the typed filters or a dealer, not with free text.
catalogoptionalconstruction · cargo-transport · agriculture · materialhandling · forestry · groundscareOne of the marketplace's six sectors. Comma-separate for several. 🔴 The value is the sector CODE, which differs from the URL slug on three of the six ('cargo-transport' not 'transportation', 'materialhandling' not 'material-handling', 'groundscare' not 'groundcare') — a value guessed off a URL returns zero rows, so the codes are published and validated here.
categoryoptional—Category code inside a sector, as the `categories` action returns it ('excavators', 'tractors', 'trucks', 'forklifts'). Comma-separate for several. An unknown code is answered honestly with zero rows rather than ignored, but reading the code out of `categories` or `suggest` is the way to be sure.
subcategoryoptional—The third taxonomy level ('crawlerexcavators', 'miniexcavators', 'wheelexcavators'), from the `categories` action with a `category_code` set. This is how you get from 40,068 excavators to the 20,806 crawler excavators.
brandoptional—Make, spelled the way the source's own facet spells it ('CAT' not 'Caterpillar', 'John Deere', 'Volvo', 'Mercedes-Benz'). Case does not matter, the spelling does — read it from `facets` or let `suggest` map what a user typed. Measured to bite: 46,035 rows for 'excavator' → 9,913 for CAT.
modeloptional—Model name, as the source's own type-ahead spells it. Only works with `brand` — a bare model name is ambiguous across makes, so it is rejected rather than returning an answer that looks filtered. Measured: brand=CAT + model=320 → 1,553 rows.
countryoptional—Seller country, 2-letter ISO code. Comma-separate for several. 80 countries have stock on a typical query; the `facets` action lists them with counts. Measured to bite: 46,035 → 3,494 for DE.
conditionoptionalused · new · reconditioned · remanufactured · demo · vintage · damaged · dismantled · operates_with_deficiencies · rental_possibilityCondition class. Comma-separate for several. The source stores these as numeric property ids; this takes the words and sends the ids. Measured: 46,035 → 4,458 for 'new'.
ad_typeoptionalusedad · auctionad · rentaladThe structural kind of advert. 🔴 An unknown value is NOT an error on this source: it is dropped and you get the whole unfiltered catalogue with HTTP 200, so this endpoint validates it instead of forwarding it. Measured to bite: 46,035 → 5,116 auction lots, → 333 rental machines.
year_minoptional1900–2100Earliest year of construction, inclusive. 🔴 The source's own name for this filter is not the obvious one and the obvious one is accepted with HTTP 200 and then ignored, so a naive year window returns the unfiltered catalogue looking filtered. Here it bites: 46,035 → 11,205 for 2015-2020.
year_maxoptional1900–2100Latest year of construction, inclusive. Note the source carries seller-entered years as far ahead as 2027, so an open-ended upper bound is not the same as 'up to this year'.
price_minoptional0–Lowest price to include, 🔴 IN THE `currency` YOU ASKED FOR (default EUR), not in the seller's currency. Measured: the same 10,000-50,000 band answers 19,366 rows in EUR and 18,583 in USD. Any price bound also excludes the listings that publish no price at all and the source's own 0 and 1 placeholder prices.
price_maxoptional0–Highest price to include, 🔴 in the `currency` you asked for (default EUR), not in the seller's currency. Setting it also excludes every listing that publishes no price at all.
operating_hours_minoptional0–Lowest hour-meter reading to include, in hours — the field a used-plant buyer prices on. Verified front-end independent, unlike the odometer: the 0-2,000 h band answers the same 412 rows on the international and the German front-end.
operating_hours_maxoptional0–Highest hour-meter reading to include, in hours. Measured to bite: 46,035 → 412 for 0-2,000 h on the transport sector.
with_price = falseoptional—Only listings that publish a price. Most of this marketplace does not — auction lots carry none at all and many dealers list 'price on request' — so this is the most useful narrowing filter for a pricing job. Measured: 46,035 → 32,305.
sort = relevanceoptionalrelevance · price_asc · price_desc · year_desc · year_asc · newest · oldest · hours_asc · hours_desc · mileage_asc · mileage_desc · brand_asc · brand_desc · model_asc · model_desc · country_asc · country_descResult order. Every value was checked to change the DATA, not merely be accepted; 🔴 a value outside this list is accepted with HTTP 200 and then ignored, so it is validated here. Read the notes on `price_asc` and `hours_asc` first: both change WHICH rows you get, not only their order.
page = 1optional1–Page number, from 1. 🔴 `page x page_size` must stay at or below 10,000: past that the source answers HTTP 200 and serves PAGE 1'S ROWS under the page number you asked for (measured at four page sizes), so the combination is refused rather than letting a paging loop re-ingest the first page for ever. `meta.pagination` publishes `last_page`, `retrievable_max` and an honest `has_more`.
page_size = 40optional1–200Rows per page, 1-200 (the source's own default is 40). A large page is the cheap way to the 10,000-row ceiling: at 200 it takes 50 calls instead of 250.
Try in playground →
Built for volume
5M+ requests a day

Measured at 60 requests a second across the fleet, with no central bottleneck. Volume pricing is on request, and per-key limits are raised for high-volume accounts.

Missing a source?
We build it

Tell us a site we do not cover yet and it becomes an engine. A customer asked for bestprice.gr on a Sunday and it was in the catalog the next day.

Support
2 minute median reply

Median time from a question in the live chat to the first answer, measured across every answered conversation. Setup help included, no support tier to buy.

One key, one balance
Every API included

No per-site plans and no separate subscriptions. One key and one credit pool across the whole catalog, so adding a source costs nothing up front.

Planning something large? Tell us the volume and the sources and we will come back with what it costs and what we would have to build.