{
  "openapi": "3.0.1",
  "info": {
    "title": "Marktplaats.nl Scraper — Dutch Classifieds Search & Monitoring",
    "description": "Marktplaats.nl listings for AI agents and analysts: keyword + category (2,000 L1/L2) search with postcode radius, price, condition, delivery, seller type and raw facet filters; price, price type, city, coordinates, seller, date, attributes, photos, URL.",
    "version": "0.1",
    "x-build-id": "YTlLvbRsBdh4hRaEN"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/yadroo~marktplaats-nl/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-yadroo-marktplaats-nl",
        "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/yadroo~marktplaats-nl/runs": {
      "post": {
        "operationId": "runs-sync-yadroo-marktplaats-nl",
        "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/yadroo~marktplaats-nl/run-sync": {
      "post": {
        "operationId": "run-sync-yadroo-marktplaats-nl",
        "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": {
          "query": {
            "title": "Search query",
            "type": "string",
            "description": "Keyword(s) searched in title and description, e.g. \"racefiets\", \"iphone 15\", \"bakfiets elektrisch\". Optional when a category is given."
          },
          "category": {
            "title": "Category",
            "type": "string",
            "description": "L1 category key or id, optionally with an L2 subcategory: \"fietsen-en-brommers\", 445, \"fietsen-en-brommers/fietsen-racefietsen\", \"445/464\". Subcategory ids/keys are resolved live against the site. Full L1 list in the README; run mode \"categories\" for the complete tree."
          },
          "subcategory": {
            "title": "Subcategory (L2)",
            "type": "string",
            "description": "Alternative to the \"l1/l2\" notation: L2 key, id or (part of the) name, e.g. \"racefietsen\" or 464. Requires category."
          },
          "mode": {
            "title": "Mode",
            "enum": [
              "search",
              "categories",
              "facets"
            ],
            "type": "string",
            "description": "\"search\" returns listings. \"categories\" returns the whole category tree (no query needed): about 2,000 rows, billed as rows like listings — roughly $4 on the free plan; pass a category to get one branch. \"facets\" returns every filter value (condition, brand, delivery…) valid for the given query/category, with the exact ids to pass in attributeIds / attributesByKey / attributeRanges. maxItems applies to search only.",
            "default": "search"
          },
          "postcode": {
            "title": "Postcode",
            "type": "string",
            "description": "Dutch postcode used as the centre for distance filtering and sorting, e.g. 1012AB. Each listing then gets distanceMeters."
          },
          "distanceMeters": {
            "title": "Max distance (m)",
            "minimum": 1000,
            "maximum": 200000,
            "type": "integer",
            "description": "Radius around the postcode in metres. The site UI offers 3000, 5000, 10000, 15000, 25000, 50000, 75000, 100000; any value works. Requires postcode."
          },
          "priceFrom": {
            "title": "Price from (€)",
            "minimum": 0,
            "type": "integer",
            "description": "Minimum price in euro."
          },
          "priceTo": {
            "title": "Price to (€)",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum price in euro."
          },
          "condition": {
            "title": "Condition",
            "type": "array",
            "description": "Item condition (facet \"Conditie\"). Several values = OR.",
            "items": {
              "type": "string",
              "enum": [
                "new",
                "like-new",
                "used",
                "refurbished"
              ],
              "enumTitles": [
                "Nieuw",
                "Zo goed als nieuw",
                "Gebruikt",
                "Refurbished"
              ]
            }
          },
          "delivery": {
            "title": "Delivery",
            "enum": [
              "pickup",
              "shipping"
            ],
            "type": "string",
            "description": "Only listings offering this delivery method."
          },
          "sellerType": {
            "title": "Seller type",
            "enum": [
              "all",
              "private",
              "business"
            ],
            "type": "string",
            "description": "Cars (category auto-s) are filtered by the site itself. Other categories have no seller filter on the site: with detail: true the seller type is read from each listing page and filtered exactly (a listing whose page could not be read is dropped and counted). Without detail, \"private\" drops listings whose search data shows a business (website link, dealer tools, company logo) and keeps the rest unverified (sellerType null); \"business\" keeps only listings whose search data shows a business — about 1 in 3 business sellers shows none of these and is found only with detail: true.",
            "default": "all"
          },
          "offeredSince": {
            "title": "Offered since",
            "enum": [
              "Vandaag",
              "Gisteren",
              "Een week",
              "Altijd"
            ],
            "type": "string",
            "description": "Site filter \"Aangeboden sinds\". Passed to the site and additionally enforced client-side on the listing date (day precision)."
          },
          "sinceHours": {
            "title": "Only listings newer than (hours)",
            "minimum": 1,
            "maximum": 720,
            "type": "integer",
            "description": "Drop listings older than N hours. With detail: true the cut-off is exact (publish time from the listing page); a listing whose page could not be read, and every listing without detail, is judged by its list date label (whole days: kept when its day started less than N + 24 hours ago). Combine with sortBy SORT_INDEX for monitoring runs."
          },
          "priceTypes": {
            "title": "Price types to keep",
            "type": "array",
            "description": "Client-side filter on the price type. Empty = keep all.",
            "items": {
              "type": "string",
              "enum": [
                "FIXED",
                "MIN_BID",
                "SEE_DESCRIPTION",
                "NOTK",
                "FREE",
                "ON_REQUEST",
                "EXCHANGE",
                "RESERVED"
              ],
              "enumTitles": [
                "Fixed price",
                "Bid from (minimum bid)",
                "See description",
                "N.o.t.k. (negotiable)",
                "Free (gratis)",
                "On request",
                "Exchange (ruilen)",
                "Reserved"
              ]
            }
          },
          "attributeIds": {
            "title": "Attribute value ids (advanced)",
            "type": "array",
            "description": "Raw facet value ids (attributesById), e.g. [473] = fuel Benzine, [534] = Automaat in cars, [30] = Nieuw. Get them from mode \"facets\".",
            "items": {
              "type": "integer"
            }
          },
          "attributesByKey": {
            "title": "Attributes by key (advanced)",
            "type": "array",
            "description": "Raw key:value facet filters (attributesByKey), e.g. \"offeredSince:Vandaag\". Get keys/values from mode \"facets\".",
            "items": {
              "type": "string"
            }
          },
          "attributeRanges": {
            "title": "Attribute ranges (advanced)",
            "type": "array",
            "description": "Range facets as key:from:to, e.g. \"constructionYear:2018:2024\", \"mileage:0:100000\" (cars), \"engineHorsepower:150:\". Keys from mode \"facets\".",
            "items": {
              "type": "string"
            }
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "SORT_INDEX",
              "OPTIMIZED",
              "PRICE",
              "LOCATION",
              "ATTRIBUTE"
            ],
            "type": "string",
            "description": "SORT_INDEX + DECREASING = newest first (best for monitoring). PRICE + INCREASING = cheapest first.",
            "default": "SORT_INDEX"
          },
          "sortOrder": {
            "title": "Sort order",
            "enum": [
              "DECREASING",
              "INCREASING"
            ],
            "type": "string",
            "description": "Defaults to DECREASING, except PRICE and LOCATION which default to INCREASING."
          },
          "sortAttribute": {
            "title": "Sort attribute (with sortBy ATTRIBUTE)",
            "enum": [
              "constructionYear",
              "mileage"
            ],
            "type": "string",
            "description": "Only for category auto-s."
          },
          "includeSponsored": {
            "title": "Include sponsored (Admarkt) listings",
            "type": "boolean",
            "description": "Also return the paid \"topBlock\" listings shown above organic results (flagged sponsored: true).",
            "default": false
          },
          "detail": {
            "title": "Open each listing page",
            "type": "boolean",
            "description": "Open every listing's page for the full description, exact publish time, view/favourite counts, seller type & years active, bids, shipping and all photos. marktplaats.nl refuses listing pages from one IP after about 60 in a minute (HTTP 403, lifted within ~3.5 min), so the run opens at most 40 a minute (~1.5 s per listing: 100 listings ≈ 3 min, 300 ≈ 8 min). On a 403 it pauses 3.5 min (then 4 min), retries the same listing and goes on more slowly. If the block does not lift, the rest of the current results page is saved with list data only and detailError \"skipped: …\", the run stops early and the status says \"detail for N of M\".",
            "default": false
          },
          "maxItems": {
            "title": "Max items",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Stop after this many listings (search mode; 100 per search page, pagination automatic; the site stops at 5,000 results per query). Rows dropped by client-side filters do not count. Modes categories and facets return their whole list.",
            "default": 50
          },
          "maxPages": {
            "title": "Max pages",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Hard cap on search-result pages (100 listings each).",
            "default": 20
          },
          "fields": {
            "title": "Output fields",
            "type": "array",
            "description": "Keep only these top-level fields in each item, in this order (e.g. [\"id\",\"title\",\"price\",\"city\",\"url\"]). Every row keeps id (facets rows: facetKey and valueKey), and with detail: true also detailError when a listing page was not read; they come first unless you list them. A different letter case or a near miss (\"titel\") is read as the output field and noted in the status; detail-only fields without detail: true and unknown names are ignored with a note; if no name is an output field the run fails and lists the valid names. Empty = all fields.",
            "items": {
              "type": "string"
            }
          },
          "proxyConfiguration": {
            "title": "Proxy (turns on fast mode for detail)",
            "type": "object",
            "description": "Off (default) = the normal run: listing pages at most 40 a minute on one IP. On = fast mode for detail: true: several IPs open listing pages at once, each at that same pace (Apify Proxy RESIDENTIAL: 8 IPs, datacenter groups: 4). Apify Proxy: from 17 Oct 2026 $0.003 per listing instead of $0.002 (one price, not both). Own proxy URLs (one per IP, up to 10): normal price. Without detail the proxy is not used.",
            "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}