DOCSEARCHbyAlgolia
Submit Docs

PriceBuddy Documentation

repository·main·Indexed 21 days ago

https://github.com/jez500/pricebuddy

An open-source, self-hostable price tracker for monitoring products across online stores. PriceBuddy allows users to track prices, availability, and unit costs with historical data and notifications via email, Telegram, Discord, and other services. It features a web UI, a CLI for automation, and optional AI-powered scraping using OpenAI, Anthropic, Gemini, or Ollama. The application is deployed via Docker and includes a dedicated scraper service and MySQL database.

Tokens
14K
Snippets
42
Records
92
Agent score
74%

What's inside PriceBuddy

  1. Overview of PriceBuddy features

    main

    PriceBuddy is an open-source price tracker that allows you to:

    • Track almost any store: Paste a product URL to scrape title, image, price, and availability. You can tune scrape strategies for difficult sites.
    • Compare listings: Track the same product across different retailers or multiple listings on a single marketplace.
    • Monitor price history: View highs, lows, and trends to identify real discounts.
    • Track availability: Monitor stock status (e.g., in stock, pre-order, back order, out of stock, discontinued).
    • Compare unit prices: Automatically calculate price per unit for fair comparison (e.g., 10-pack vs 3-pack).
    • Set notifications: Get alerted via email, Pushover, Gotify, Apprise, Telegram, Discord, or ntfy when target prices or percentage drops are met.
    • Use AI for scraping: Optionally use OpenAI, Anthropic, Gemini, or local Ollama to recover missing data or repair scraping rules.
    • Search via SearXNG: Connect a SearXNG instance to search for products directly within the app.
    • Organize with watchlists: Use tags, filters, and multi-user accounts to manage shared or private lists.

  2. Understand User roles

    main

    PriceBuddy uses roles to control access levels. New users default to the User role.

    RoleCapabilities
    AdminFull access. Can manage global settings and create, edit, or delete other users.
    UserStandard access. Can manage their own products, tags, and account, but cannot access Settings or manage other users.

    Note: The Users page prevents deleting the last remaining Admin to avoid lockouts, but the CLI command user:assign-role does not enforce this check. Use caution when demoting admins via CLI.

  3. Monitor availability and price history

    main

    PriceBuddy tracks both price and availability (when supported by the store) to help you distinguish between the cheapest price and the best available option.

    Availability States

    Common states include: In Stock, Pre-Order, Back Order, Special Order, Out of Stock, and Discontinued.

    Price History and Trends

    • Price History: Each URL maintains a list of historical prices. The dashboard displays the most recent price for each URL, sorted from lowest to highest.
    • Handling Unavailable Items: If a URL is unavailable and has no current price, PriceBuddy displays the availability status instead of a zero price.
    • Price Trends: PriceBuddy shows whether the current price has gone up, down, or stayed the same compared to the previous price.
    • Charts: Price history charts can toggle between viewing the retail price and the unit price.

  4. Manage Product URLs for tracking

    main

    A Product represents a single item (e.g., a book or computer) and can be associated with multiple URLs. Each URL represents a different retailer where the same product is available (e.g., Amazon, eBay).

    • Creating a Product: Start by providing a single product URL. PriceBuddy uses this to extract initial details and price.
    • Adding URLs: You can add additional URLs to an existing product to track the same item across different stores.

  5. Extract data using Schema.org (JSON-LD)

    main
    The Schema.org strategy is the most robust method. It reads the JSON-LD data embedded in the page. This is the recommended method if the retailer provides it. When a store is auto-created, PriceBuddy tests this strategy first.

  7. Understand Product Sources types and purposes

    main

    Product Sources are external websites used for automated product discovery. They are categorized into two types:

    1. Deals Site (Aggregator): Sites like OzBargain or Slickdeals that aggregate deals from various sources. URLs point to deal pages rather than direct products. These must not be linked to a Store record.
    2. Online Store: Sites like Amazon or eBay that sell products directly. URLs point to product pages. These must be linked to an existing Store record and can inherit its scraping settings.

    Use Product Sources to search multiple platforms, aggregate results, and automate product discovery.

  8. Choose a Scraper Service

    main

    Select the method PriceBuddy uses to fetch the HTML of a product page:

    1. Curl based HTTP request (HTTP): The default and fastest method. It performs a standard HTTP request (equivalent to "View Source"). Use this for most sites, but it will not work on sites that require JavaScript to render content.
    2. Browser based request (API): Uses a headless browser (via seleniumbase-scrapper) to execute JavaScript and render the page. Use this for modern, JavaScript-heavy websites.

  9. Define an Extraction Strategy

    main

    The extraction strategy tells PriceBuddy how to parse search results. It requires three components:

    1. List Container: Identifies the wrapper for each product item. To return full HTML (allowing easier title/URL extraction) instead of plain text, prefix the CSS selector with !.
      • Example: {"type": "selector", "value": "!.product-item"}
    2. Product Title: A selector to extract the title from within the list container.
    3. Product URL: A selector to extract the link. Use the pipe | syntax to target attributes.

    Supported Extraction Types

    • selector: CSS selectors (e.g., .price\|textContent or h2 a\|href).
    • xpath: XPath expressions (e.g., //div[@class="price"]/text()).
    • regex: Regular expressions (e.g., /\$([0-9.]+)/).
    • json: JSON path (e.g., data.products[0].title).

    CSS Attribute Extraction

    Use the pipe (|) character to specify which attribute to extract:

    • a|href - Extracts the href attribute.
    • img|src - Extracts the src attribute.
    • div - Extracts text content (default).
    {
  "list_container": {
    "type": "selector",
    "value": "!.product-item"
  },
  "product_title": {
    "type": "selector",
    "value": "h2.title a"
  },
  "product_url": {
    "type": "selector",
    "value": "a.product-link|href"
  }
}

  10. Use AI for Price Extraction and Self-Healing

    main

    If an AI provider is configured, you can leverage AI to improve scraping reliability.

    AI Price Extraction: This is an additive feature. If a standard scrape fails to find a price, the AI attempts to recover it. It only fills gaps and never overrides existing scraped prices.

    AI Self-healing: If a site changes its markup and your selectors break, you can use Heal with AI in the store test view. The AI will propose new selectors to repair the configuration. You must manually review and apply these fixes.

  11. Customize the PriceBuddy dashboard

    main

    The dashboard is highly customizable and organized by tags. Users can:

    • Reorder: Drag to reorder product groups (tags) or individual products within a group.
    • Re-tag: Drag a product from one group to another to change its tag.
    • Collapse: Collapse groups to simplify the view.
    • Toggle Sections: Use the Customize button to show or hide summary stats and smart sections:
      • What's good to buy now: Highlights products that are currently a good value.
      • Recently dropped: Shows products with recent price decreases.
      • Needs attention: Lists products where the latest price check failed.

    Layout preferences, group order, collapse states, and section choices are saved on a per-user basis.

  12. Install the PriceBuddy CLI

    main

    You can install the PriceBuddy CLI using Go, building from source, or downloading pre-built binaries.

    Go install

    Requires Go 1.26.3 or newer.

    Build from source

    git clone https://github.com/jez500/pricebuddy-cli.git
cd pricebuddy-cli
make build      # produces ./bin/pricebuddy
# or: make install

    Pre-built binary

    Download from the latest release.

    macOS Gatekeeper: If you download a binary on macOS, clear the quarantine attribute:

    xattr -d com.apple.quarantine <binary>

    Permissions: On Linux and macOS, ensure the binary is executable:

    chmod +x <binary>
    go install github.com/jez500/pricebuddy-cli/cmd/pricebuddy@latest