PriceBuddy

https://pricebuddy.jez.me/
Admin
PriceBuddy is an open source, self-hostable web application that allows users to compare prices of...
Tokens:7,725
Snippets:121
Trust Score:7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install PriceBuddy with Docker Compose

Source: https://pricebuddy.jez.me/installation

This snippet outlines the steps to download the docker-compose file, create a .env file, and start the PriceBuddy application in detached mode.

```bash
mkdir pricebuddy
cd pricebuddy
wget https://raw.githubusercontent.com/jez500/pricebuddy/main/docker-compose.yml
touch .env
docker compose up -d
```

--------------------------------

### OzBargain Configuration Example

Source: https://pricebuddy.jez.me/product-sources

Example JSON configuration for an OzBargain product source, including name, type, search URL, and extraction strategy.

```json
{
  "name": "OzBargain",
  "type": "deals_site",
  "status": "active",
  "search_url": "https://www.ozbargain.com.au/search/node/:search_term",
  "extraction_strategy": {
    "list_container": {
      "type": "selector",
      "value": ".node.node-ozbdeal"
    },
    "product_title": {
      "type": "selector",
      "value": "h2.title a"
    },
    "product_url": {
      "type": "selector",
      "value": "h2.title a|href"
    }
  },
  "settings": {
    "scraper_service": "http"
  }
}


```

--------------------------------

### Example Search URL for OzBargain

Source: https://pricebuddy.jez.me/product-sources

This is an example of a search URL for the OzBargain deals site. It uses the :search_term placeholder.

```text
https://www.ozbargain.com.au/search/node/:search_term
```

--------------------------------

### Example Search URL with Query Parameters

Source: https://pricebuddy.jez.me/product-sources

This is an example of a search URL that includes additional query parameters. It uses the :search_term placeholder.

```text
https://www.example.com/search?q=:search_term&type=products
```

--------------------------------

### Amazon Australia Configuration Example

Source: https://pricebuddy.jez.me/product-sources

Example JSON configuration for an Amazon Australia product source, detailing its settings and extraction logic.

```json
{
  "name": "Amazon Australia",
  "type": "online_store",
  "status": "active",
  "store_id": 1,
  "search_url": "https://www.amazon.com.au/s?k=:search_term",
  "extraction_strategy": {
    "list_container": {
      "type": "selector",
      "value": "div[data-component-type='s-search-result']"
    },
    "product_title": {
      "type": "selector",
      "value": "h2 a span"
    },
    "product_url": {
      "type": "selector",
      "value": "h2 a|href"
    }
  },
  "settings": {
    "scraper_service": "http"
  }
}


```

--------------------------------

### Example Search URL for Amazon

Source: https://pricebuddy.jez.me/product-sources

This is an example of a search URL for Amazon. It uses the :search_term placeholder.

```text
https://www.amazon.com.au/s?k=:search_term
```

--------------------------------

### Get Specific Product Source

Source: https://pricebuddy.jez.me/product-sources

Retrieve details for a single product source by its ID. You can include related data like 'store' or 'user'.

```http
GET /api/product-sources/{id}
```

--------------------------------

### Get Product Source

Source: https://pricebuddy.jez.me/product-sources

Retrieves a specific product source by its ID. Allows including related data such as store and user information.

```APIDOC
## Get Product Source (GET)

### Description
Retrieves a specific product source by its unique identifier. You can optionally include related 'store' and 'user' data in the response.

### Method
GET

### Endpoint
/api/product-sources/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the product source.

#### Query Parameters
- **include** (string) - Optional - Include relationships (store, user).

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the product source.
- **name** (string) - The name of the product source.
- **search_url** (string) - The base URL for searching products on this source.
- **type** (string) - The type of the product source (e.g., 'online_store', 'deals_site').
- **store_id** (integer) - The ID of the associated store, if applicable.
- **status** (string) - The current status of the product source (e.g., 'active', 'inactive', 'draft').
- **extraction_strategy** (object) - Configuration for extracting product data.
- **settings** (object) - Additional settings for the product source.
- **store** (object) - Included store details if requested.
- **user** (object) - Included user details if requested.
```

--------------------------------

### View Laravel Log File

Source: https://pricebuddy.jez.me/installation

Use this command to view the Laravel log file within the running Docker container, useful for debugging installation issues.

```bash
docker compose exec -it app cat /app/storage/logs/laravel.log
```

--------------------------------

### Extraction Strategy: Product Title (Plain Text)

Source: https://pricebuddy.jez.me/product-sources

Defines how to extract the product title from within a list container. This example extracts plain text.

```json
{
  "type": "selector",
  "value": "h2.title a"
}
```

--------------------------------

### Extraction Strategy: Product URL (Attribute)

Source: https://pricebuddy.jez.me/product-sources

Defines how to extract the product or deal URL from within a list container. This example extracts the 'href' attribute from a link.

```json
{
  "type": "selector",
  "value": "a.product-link|href"
}
```

--------------------------------

### Create Product Source

Source: https://pricebuddy.jez.me/product-sources

Create a new product source by sending a POST request with the source details. Requires name, search_url, type, and extraction strategy.

```http
POST /api/product-sources

{
  "name": "Example Store",
  "search_url": "https://example.com/search?q=:search_term",
  "type": "online_store",
  "store_id": 1,
  "status": "active",
  "extraction_strategy": {
    "list_container": {
      "type": "selector",
      "value": ".product-item"
    },
    "product_title": {
      "type": "selector",
      "value": "h2.title"
    },
    "product_url": {
      "type": "selector",
      "value": "a.product-link|href"
    }
  },
  "settings": {
    "scraper_service": "http"
  }
}
```

--------------------------------

### Build and Execute Search with Search Service (PHP)

Source: https://pricebuddy.jez.me/product-sources

Utilize the ProductSourceSearchService to build search URLs and perform searches for a given product source.

```php
use App\Services\ProductSourceSearchService;
use App\Models\ProductSource;

$source = ProductSource::find(1);
$service = ProductSourceSearchService::new($source);

$searchUrl = $service->buildSearchUrl('gaming laptop');
$results = $service->search('gaming laptop');


```

--------------------------------

### Search Products from a Source (PHP)

Source: https://pricebuddy.jez.me/product-sources

Find products using a specific product source instance. The results include title, URL, and content.

```php
use App\Models\ProductSource;

$source = ProductSource::find(1);
$results = $source->search('laptop');

// Results collection contains:
// [
//   ['title' => 'Product Name', 'url' => 'https://...', 'content' => '...'],
//   ...
// ]


```

--------------------------------

### Enable Debugging via Environment Variables

Source: https://pricebuddy.jez.me/installation

Set these environment variables to enable local development mode and detailed debugging output for PriceBuddy.

```bash
APP_ENV=local
APP_DEBUG=true
```

--------------------------------

### Create Product Source

Source: https://pricebuddy.jez.me/product-sources

Creates a new product source with specified details, including name, search URL, type, extraction strategy, and settings.

```APIDOC
## Create Product Source (POST)

### Description
Creates a new product source. Requires details such as name, search URL, type, and an extraction strategy to define how product information should be scraped.

### Method
POST

### Endpoint
/api/product-sources

### Parameters
#### Request Body
- **name** (string) - Required - The name of the product source.
- **search_url** (string) - Required - The base URL for searching products on this source. Use `:search_term` as a placeholder for the search query.
- **type** (string) - Required - The type of the product source (e.g., 'online_store', 'deals_site').
- **store_id** (integer) - Optional - The ID of the associated store.
- **status** (string) - Optional - The status of the product source (default: 'draft').
- **extraction_strategy** (object) - Required - Defines how to extract product details from the source page.
  - **list_container** (object) - Selector for the container of individual product listings.
    - **type** (string) - Type of the selector (e.g., 'selector').
    - **value** (string) - The CSS selector value.
  - **product_title** (object) - Selector for the product title.
    - **type** (string) - Type of the selector (e.g., 'selector').
    - **value** (string) - The CSS selector value.
  - **product_url** (object) - Selector for the product URL.
    - **type** (string) - Type of the selector (e.g., 'selector').
    - **value** (string) - The CSS selector value (e.g., 'a.product-link|href').
- **settings** (object) - Optional - Additional settings for scraping.
  - **scraper_service** (string) - The scraper service to use (e.g., 'http').

### Request Example
```json
{
  "name": "Example Store",
  "search_url": "https://example.com/search?q=:search_term",
  "type": "online_store",
  "store_id": 1,
  "status": "active",
  "extraction_strategy": {
    "list_container": {
      "type": "selector",
      "value": ".product-item"
    },
    "product_title": {
      "type": "selector",
      "value": "h2.title"
    },
    "product_url": {
      "type": "selector",
      "value": "a.product-link|href"
    }
  },
  "settings": {
    "scraper_service": "http"
  }
}
```

### Response
#### Success Response (201)
- **id** (integer) - The unique identifier of the newly created product source.
- **name** (string) - The name of the product source.
- **search_url** (string) - The base URL for searching products on this source.
- **type** (string) - The type of the product source.
- **store_id** (integer) - The ID of the associated store, if applicable.
- **status** (string) - The status of the product source.
- **extraction_strategy** (object) - Configuration for extracting product data.
- **settings** (object) - Additional settings for the product source.
```

--------------------------------

### Query Active Product Sources (PHP)

Source: https://pricebuddy.jez.me/product-sources

Retrieve all enabled product sources or filter them by type using static methods on the ProductSource model.

```php
use App\Models\ProductSource;
use App\Enums\ProductSourceStatus;

// Get all active sources
$sources = ProductSource::enabled()->get();

// Get active sources by type
$dealsSites = ProductSource::enabled()
    ->where('type', ProductSourceType::DealsSite)
    ->get();


```

--------------------------------

### Create Filament User via CLI

Source: https://pricebuddy.jez.me/users

Use this command to create a new user through the Filament interface via the CLI.

```bash
php artisan make:filament-user

```

--------------------------------

### Extraction Strategy: List Container (Full HTML)

Source: https://pricebuddy.jez.me/product-sources

Defines how to identify individual product items in search results, returning the full HTML for each item. Use '!' to ensure HTML is returned.

```json
{
  "type": "selector",
  "value": "!.product-item"
}
```

--------------------------------

### List Product Sources

Source: https://pricebuddy.jez.me/product-sources

Use this endpoint to retrieve a paginated list of product sources. You can filter, sort, and select specific fields.

```http
GET /api/product-sources
```

```http
GET /api/product-sources?filter[status]=active&include=store&sort=name
```

--------------------------------

### Create Filament User via Docker Compose CLI

Source: https://pricebuddy.jez.me/users

Use this command to create a new user through the Filament interface when running within a Docker Compose environment.

```bash
docker compose exec -it app php artisan make:filament-user

```

--------------------------------

### API Base URL for Product Sources

Source: https://pricebuddy.jez.me/product-sources

The base URL for accessing Product Sources via the RESTful API. Authentication is required using Laravel Sanctum tokens.

```text
/api/product-sources
```

--------------------------------

### Extracting Price using Regex

Source: https://pricebuddy.jez.me/stores

Demonstrates how to use a regular expression to extract price information from a JSON string. This method is flexible but requires understanding regex syntax.

```regex
~"price": "(.*?)"~
```

--------------------------------

### List Product Sources

Source: https://pricebuddy.jez.me/product-sources

Retrieves a paginated list of product sources. Supports filtering, sorting, field selection, and including related data like store and user information.

```APIDOC
## List Product Sources (GET)

### Description
Retrieves a paginated list of product sources. Supports filtering by status, type, and store ID, as well as sorting by various fields and selecting specific fields. You can also include related 'store' and 'user' data.

### Method
GET

### Endpoint
/api/product-sources

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Results per page (max 100).
- **filter[status]** (string) - Optional - Filter by status (active, inactive, draft).
- **filter[type]** (string) - Optional - Filter by type (deals_site, online_store).
- **filter[store_id]** (integer) - Optional - Filter by store ID.
- **sort** (string) - Optional - Sort field (name, slug, type, status, created_at, updated_at).
- **include** (string) - Optional - Include relationships (store, user).
- **fields[product_sources]** (string) - Optional - Select specific fields for product sources.

### Request Example
```
GET /api/product-sources?filter[status]=active&include=store&sort=name
```
```

--------------------------------

### Common CSS Selectors for Product Data

Source: https://pricebuddy.jez.me/stores

Provides common CSS selectors for extracting title, price, and image from product pages, particularly for Open Graph metadata. Note that selectors may vary depending on the website's structure.

```text
meta[property=og:title]|content
```

```text
meta[property=og:price:amount]|content
```

```text
meta[property=og:image]|content
```

--------------------------------

### Update Product Source

Source: https://pricebuddy.jez.me/product-sources

Update an existing product source by its ID using a PUT request. Only include fields you wish to change.

```http
PUT /api/product-sources/{id}

{
  "name": "Updated Name",
  "status": "inactive"
}
```

--------------------------------

### Mount Custom JavaScript for Scraper

Source: https://pricebuddy.jez.me/faqs

Use this setting to mount custom JavaScript files into the scraper container. This is useful for advanced scenarios like handling stores that require user-defined scripts to extract prices.

```bash
user-scripts=/store-x-post-load-script.js
```

--------------------------------

### Delete Product Source

Source: https://pricebuddy.jez.me/product-sources

Remove a product source by its ID using a DELETE request.

```http
DELETE /api/product-sources/{id}
```

--------------------------------

### Extracting Price using JSON Path

Source: https://pricebuddy.jez.me/stores

Shows how to extract price data from a JSON object using a JSON Path-like notation. This is effective when the data is structured in a predictable JSON format, often from an API.

```jsonpath
product.price
```

--------------------------------

### Update Product Source

Source: https://pricebuddy.jez.me/product-sources

Updates an existing product source identified by its ID. Allows modification of fields like name, status, and other configurations.

```APIDOC
## Update Product Source (PUT)

### Description
Updates an existing product source identified by its ID. You can modify fields such as the name, status, and other configuration parameters.

### Method
PUT

### Endpoint
/api/product-sources/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the product source to update.

#### Request Body
- **name** (string) - Optional - The updated name of the product source.
- **status** (string) - Optional - The updated status of the product source (e.g., 'active', 'inactive', 'draft').
- **search_url** (string) - Optional - The updated base URL for searching products.
- **type** (string) - Optional - The updated type of the product source.
- **store_id** (integer) - Optional - The updated ID of the associated store.
- **extraction_strategy** (object) - Optional - The updated extraction strategy.
- **settings** (object) - Optional - The updated settings.

### Request Example
```json
{
  "name": "Updated Name",
  "status": "inactive"
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the updated product source.
- **name** (string) - The updated name of the product source.
- **status** (string) - The updated status of the product source.
- **search_url** (string) - The updated base URL for searching products.
- **type** (string) - The updated type of the product source.
- **store_id** (integer) - The updated ID of the associated store.
- **extraction_strategy** (object) - The updated extraction strategy.
- **settings** (object) - The updated settings.
```

--------------------------------

### Delete Product Source

Source: https://pricebuddy.jez.me/product-sources

Deletes a product source identified by its ID.

```APIDOC
## Delete Product Source (DELETE)

### Description
Deletes a specific product source using its unique identifier.

### Method
DELETE

### Endpoint
/api/product-sources/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the product source to delete.

### Response
#### Success Response (204)
No Content. Indicates the product source was successfully deleted.
```

--------------------------------

### Extracting Attribute Value with CSS Selector

Source: https://pricebuddy.jez.me/stores

Use the '|' symbol with a CSS selector to extract the value of a specific attribute from an HTML element. This is useful when the desired data is stored in an attribute rather than the element's text content.

```text
.product|price
```
Tokens:
Raw