FindA.Sale

Find current public sales (yard and garage sales, whole-house sales, auctions, flea markets, shops) by keyword, city, ZIP, map point, date range or sale type. Returns sale summaries with approximate location and a link to each sale page. Street addresses are never included.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Keywords to match in the sale title or description, e.g. \"mid-century\" or \"tools\"",
      "type": "string",
      "maxLength": 100
    },
    "city": {
      "description": "City name, e.g. \"Grand Rapids\"",
      "type": "string",
      "maxLength": 80
    },
    "zip": {
      "description": "5-digit US ZIP code",
      "type": "string",
      "pattern": "^\\d{5}$"
    },
    "lat": {
      "description": "Latitude for a radius search (use with lng)",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "lng": {
      "description": "Longitude for a radius search (use with lat)",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "radiusKm": {
      "description": "Radius in kilometers for lat/lng search (default 25)",
      "type": "number",
      "minimum": 1,
      "maximum": 200
    },
    "startDate": {
      "description": "Only sales starting on or after this date (YYYY-MM-DD)",
      "type": "string",
      "maxLength": 30
    },
    "endDate": {
      "description": "Only sales starting on or before this date (YYYY-MM-DD)",
      "type": "string",
      "maxLength": 30
    },
    "saleType": {
      "description": "Sale type code: ESTATE (whole-house sale), YARD (yard or garage sale), AUCTION, FLEA_MARKET, RETAIL (shop or storefront, incl. consignment), DORM_DASH (dorm move-out).",
      "maxItems": 6,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "ESTATE",
          "YARD",
          "AUCTION",
          "FLEA_MARKET",
          "RETAIL",
          "DORM_DASH"
        ]
      }
    },
    "limit": {
      "description": "Max results (default 20, max 50)",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "minConfidence": {
      "description": "Minimum listing confidence 0 to 1. 0.7 = organizer-verified, 0.4 = corroborated by a third party.",
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one public sale: dates, city, approximate location, description, photos, organizer name and rating, and up to 25 available items. Street addresses are never included; the sale page shows them to signed-in shoppers from the day before the sale.

{
  "type": "object",
  "properties": {
    "saleId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The FindA.Sale sale id, as returned by a search tool"
    }
  },
  "required": [
    "saleId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search items listed for sale across current public FindA.Sale sales by keyword, with optional category, condition, price range and city filters. Returns item title, price, condition, photos and links to the item and its sale.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Keywords, e.g. \"brass lamp\" or \"oak dresser\""
    },
    "category": {
      "description": "Category name from list_categories, e.g. \"Furniture\"",
      "type": "string",
      "maxLength": 100
    },
    "city": {
      "description": "Only items in sales in this city",
      "type": "string",
      "maxLength": 80
    },
    "priceMin": {
      "description": "Minimum price in US dollars",
      "type": "number",
      "minimum": 0
    },
    "priceMax": {
      "description": "Maximum price in US dollars",
      "type": "number",
      "minimum": 0
    },
    "condition": {
      "description": "Condition filter, e.g. \"NEW\", \"LIKE_NEW\", \"USED\"",
      "type": "string",
      "maxLength": 40
    },
    "limit": {
      "description": "Max results (default 20, max 50)",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "sortBy": {
      "description": "Sort order (default relevance)",
      "type": "string",
      "enum": [
        "relevance",
        "newest",
        "price_asc",
        "price_desc"
      ]
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one publicly listed item: title, description, price, condition, photos, and the sale it belongs to (title, city, dates, link).

{
  "type": "object",
  "properties": {
    "itemId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The FindA.Sale item id, as returned by a search tool"
    }
  },
  "required": [
    "itemId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List cities with current public sales on FindA.Sale, busiest first, with active sale counts and a browse link for each city. Filter by state to narrow the list.

{
  "type": "object",
  "properties": {
    "state": {
      "description": "State or province code, e.g. \"MI\" or \"ON\"",
      "type": "string",
      "minLength": 2,
      "maxLength": 3
    },
    "limit": {
      "description": "Max cities to return (default 100, max 500)",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the sale type codes FindA.Sale uses (yard sale, whole-house sale, auction, flea market, shop, dorm move-out) with a short description of each.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List item categories that currently have items for sale, with item counts. Use a name from this list as the category filter in search_items.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List current public sales with the most shopper interest and recent activity, optionally in one city or of one sale type.

{
  "type": "object",
  "properties": {
    "city": {
      "description": "City name, e.g. \"Grand Rapids\"",
      "type": "string",
      "maxLength": 80
    },
    "saleType": {
      "description": "Sale type code: ESTATE (whole-house sale), YARD (yard or garage sale), AUCTION, FLEA_MARKET, RETAIL (shop or storefront, incl. consignment), DORM_DASH (dorm move-out).",
      "type": "string",
      "enum": [
        "ESTATE",
        "YARD",
        "AUCTION",
        "FLEA_MARKET",
        "RETAIL",
        "DORM_DASH"
      ]
    },
    "limit": {
      "description": "Max results (default 10, max 25)",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List public sales starting in the next few days (default 7, max 14). Good for "what sales are this weekend near X" questions.

{
  "type": "object",
  "properties": {
    "city": {
      "description": "City name, e.g. \"Chicago\"",
      "type": "string",
      "maxLength": 80
    },
    "saleType": {
      "description": "Sale type code: ESTATE (whole-house sale), YARD (yard or garage sale), AUCTION, FLEA_MARKET, RETAIL (shop or storefront, incl. consignment), DORM_DASH (dorm move-out).",
      "type": "string",
      "enum": [
        "ESTATE",
        "YARD",
        "AUCTION",
        "FLEA_MARKET",
        "RETAIL",
        "DORM_DASH"
      ]
    },
    "daysAhead": {
      "description": "How many days ahead to look (default 7, max 14)",
      "type": "integer",
      "minimum": 1,
      "maximum": 14
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Find a specific thing someone wants to buy (furniture, a collectible, a tool) across current public sales, optionally in one city and price range. Returns up to 10 matches with links to cite.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "What the shopper is looking for, e.g. \"Hummel figurine\" or \"oak dresser\""
    },
    "city": {
      "description": "Only items in sales in this city",
      "type": "string",
      "maxLength": 80
    },
    "minPrice": {
      "description": "Minimum price in US dollars",
      "type": "number",
      "minimum": 0
    },
    "maxPrice": {
      "description": "Maximum price in US dollars",
      "type": "number",
      "minimum": 0
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}