AI Marketplace Monitor

An intelligent tool that monitors Facebook Marketplace listings using AI to help you find the best deals. Get instant notifications when items matching your criteria are posted, with AI-powered analysis of each listing.

Example notification from PushBullet:

Found 1 new gopro from facebook
[Great deal (5)] Go Pro hero 12
$180, Houston, TX
https://facebook.com/marketplace/item/1234567890
AI: Great deal; A well-priced, well-maintained camera meets all search criteria, with extra battery and charger.

Table of content:

• ✨ Key Features
• Usage
  • Prerequisites
  • Installation
  • Set up PushBullet (optional)
  • Sign up with an AI service or build your own (optional)
  • Configuration
  • Run the program
  • Updating search
• Advanced features
  • Setting up email notification
  • Multiple configuration files
  • Adjust notification level
  • Searching multiple cities and regions
  • Check individual listing
  • Multiple marketplaces
  • First and subsequent searches
  • Showing statistics
  • Self-hosted Ollama Model
  • Cache Management
  • Support for different layouts of facebook listings
• Troubleshooting
• Contributing
• Support
• License
• Credits

✨ Key Features

🔍 Smart Search

• Search multiple products using keywords
• Filter by price and location
• Exclude irrelevant results and spammers
• Support for different Facebook Marketplace layouts

🤖 AI-Powered

• Intelligent listing evaluation
• Smart recommendations
• Multiple AI service providers supported
• Self-hosted model option (Ollama)

📱 Notifications

• PushBullet notifications
• HTML email notifications with images
• Customizable notification levels
• Repeated notification options

🌎 Location Support

• Multi-city search
• Pre-defined regions (USA, Canada, etc.)
• Customizable search radius
• Flexible seller location filtering

Usage

Prerequisites

• Python 3.x installed.
• Internet connection

Installation

Install the program by

pip install ai-marketplace-monitor

Install a browser for Playwright using the command:

playwright install

Set up PushBullet (optional)

If you would like to receive notification through phone notification

• Sign up for PushBullet
• Install the app on your phone
• Go to the PushBullet website and obtain a token

Sign up with an AI service or build your own (optional)

You can sign up for an AI service (e.g. OpenAI and DeepSeek) by

• Sign up for an account
• Go to the API keys section of your profile, generate a new API key, and copy it

You can also connect to any other AI service that provides an OpenAI compatible API, or host your own large language model using Ollama (see Self-hosted Ollama Model for details.)

Configuration

One or more configuration file in TOML format is needed. The following example (minimal_config.toml) shows the absolute minimal number of options, namely which city you are searching in, what item you are searching for, and how you get notified with matching listings.

[marketplace.facebook]
search_city = 'houston'

[item.name]
search_phrases = 'Go Pro Hero 11'

[user.user1]
pushbullet_token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

The configuration file needs to be put as $HOME/.ai-marketplace-monitor/config.toml, or be specified via option --config.

A more realistic example using openAI would be

[ai.openai]
api_key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

[marketplace.facebook]
search_city = 'houston'
username = '[email protected]'
seller_locations = [
    "sugar land",
    "stafford",
    "missouri city",
    "pearland"
]

[item.name]
search_phrases = 'Go Pro Hero 11'
description = '''A new or used Go Pro version 11, 12 or 13 in
    good condition. No other brand of camera is acceptable.
    Please exclude sellers who offers shipping or asks to
    purchase the item from his website.'''
min_price = 100
max_price = 200

[item.name2]
search_phrases = 'something rare'
description = '''A rare item that has to be searched nationwide and be shipped.
    listings from any location are acceptable.'''
search_region = 'usa'
delivery_method = 'shipping'
seller_locations = []

[user.user1]
email = '[email protected]'
smtp_password = 'xxxxxxxxxxxxxxxx'

For a complete list of options, please see the configuration documentation.

Run the program

ai-marketplace-monitor

or use option --config for a non-standard configuration file.

Use Ctrl-C to terminate the program.

NOTE

1. You need to keep the terminal running to allow the program to run indefinitely.
2. You will see a browser firing up. You may need to manually enter username and/or password (if unspecified in config file), and answer any prompt (e.g. CAPTCHA) to login. You may want to click "OK" to save the password, etc.

Updating search

It is recommended that you check the log messages and make sure that it includes and excludes listings as expected. Modify the configuration file to update search criteria if needed. The program will detect changes and restart the search automatically.

Advanced features

Setting up email notification

Sending email notifications requires recipient email addresses, which are specified in email of user. For example, you can send email notifications to multiple users with multiple email addresses as

[user.user1]
email = '[email protected]'

[user.user2]
email = ['[email protected]', '[email protected]']

You then need a SMTP server that helps you to send the email, for which you will need a smtp_server, smtp_port, smtp_username and smtp_password. Generally speaking, you will need to create an smtp section with the information obtained from your email service provider.

[smtp.myprovider]
smtp_server = 'smtp.soho.com'
smtp_port = 587
smtp_username = 'username'
smtp_password = 'mypassword'

If you have a GMAIL account,

• smtp_username is your gmail address, which is assumed to be the first email if left unspecified (assume that you are sending notification to yourself)
• smtp_server and smtp_port: Assumed to be smtp.gmail.com and 587 if smtp_username ends with gmail.com, and smtp.outlook.com for [email protected] etc.
• smtp_password: You cannot use your gmail password. Instead, you will need to go to your Google Account Manager, select Security, search for App passwords (you may need to enable two-step authentication first), create an app (e.g. ai-marketplace-monitor), and copy the app password.

That is to say, you smtp setting for your gmail account should look like

[smtp.google]
smtp_username = '[email protected]'
smtp_password = 'abcdefghijklmnop'

If you use an gmail account and only notify yourself, you can simply do

[user.me]
email = '[email protected]'
smtp_password = 'abcdefghijklmnop'

Multiple configuration files

You can use multiple configuration files. For example, you can add all credentials to ~/.ai-marketplace-monitor/config.yml and use separate configuration files for items for different users.

Adjust notification level

We ask AI services to evaluate listings against the criteria that you specify with the following prompt:

Evaluate how well this listing matches the user's criteria. Assess the description, MSRP, model year,
condition, and seller's credibility. Rate from 1 to 5 based on the following:

1 - No match: Missing key details, wrong category/brand, or suspicious activity (e.g., external links).
2 - Potential match: Lacks essential info (e.g., condition, brand, or model); needs clarification.
3 - Poor match: Some mismatches or missing details; acceptable but not ideal.
4 - Good match: Mostly meets criteria with clear, relevant details.
5 - Great deal: Fully matches criteria, with excellent condition or price.

Conclude with:
"Rating [1-5]: [summary]"
where [1-5] is the rating and [summary] is a brief recommendation (max 30 words)."

When AI services are used, the program by default notifies you of all listing with a rating of 3 or higher. You can change this behavior by setting for example

rating = 4

to see only listings that match your criteria well. Note that all listings after non-AI-based filtering will be returned if no AI service is specified or non-functional.

Searching multiple cities and regions

You can search an item from multiple cities and pick up from sellers from multiple locations using a list of search_city

[item.name]
search_city = ['city1', 'city2']
seller_locations = ['city1', 'city2', 'city3', 'city4']

and you can also increase the radius of search using

[item.name]
search_city = ['city1', 'city2']
radius = 50

However, if you would like to search for a larger region (e.g. the USA), it is much easier to define regions with a list of search_city and large radius.

ai-marketplace-monitor defines the following regions in its system config.toml:

• usa for USA (without AK or HI)
• usa_full for USA
• can for Canada
• mex for Mexico
• bra for Brazil
• arg for Argentina
• aus for Australia
• aus_miles for Australia using 500 miles radius
• nzl for New Zealand
• ind for India
• gbr for United Kingdom
• fra for France
• spa for Spain

Now, if you would like to search an item across the US, you can

[item.name]
search_region = 'usa'
seller_locations = []
delivery_method = 'shipping'

Under the hood, ai-marketplace-monitor will simply replace search_region with corresponding pre-defined search_city and radius. Note that seller_locations does not make sense and need to be set to empty for region-based search, and it makes sense to limit the search to listings that offer shipping.

Check individual listing

If you ever wonder why a listing was excluded, or just want to check a listing against your configuration, you can get the URL (or the item ID) of the listing, and run

ai-marketplace-monitor --check your-url

If you have multiple items specified in your config file, ai-marketplace-monitor will check the product against the configuration of all of them. If you know the name of the item in your config file, you can let the program only check the configuration of this particular item.

ai-marketplace-monitor --check your-url --for item_name

Option --check will load the details of the item from the cache if it was previously examined. Otherwise a browser will be started to retrieve the page.

Another way to check individual IDs is to enter interactive mode when the ai-marketplace-monitor is running. If you press Esc, then confirm with c when prompted, you can enter the URL and item_name interactively and check the URL. Enter exit to exit the interactive session after you are done. However, using this method requires OS to allow the program to monitor your keyboard. It would not work on a terminal accessed through SSH, and you have to allow the terminal that you use to run ai-marketplace-monitor to monitor keyboard from the Privacy and Security settings on MacOS.

Multiple marketplaces

Although facebook is currently the only supported marketplace, you can create multiple marketplaces such asmarketplace.city1 and marketplace.city2 with different options such as search_city, search_region, seller_locations, and notify. You will need to add options like marketplace='city1' in the items section to link these items to the right marketplace.

For example

[marketplace.facebook]
search_city = 'houston'
seller_locations = ['houston', 'sugarland']

[marketplace.nationwide]
search_region = 'usa'
seller_location = []
delivery_method = 'shipping'

[item.default_item]
search_phrases = 'local item for default market "facebook"'

[item.rare_item1]
marketplace = 'nationwide'
search_phrases = 'rare item1'

[item.rare_item2]
marketplace = 'nationwide'
search_phrases = 'rare item2'

First and subsequent searches

A list of two values can be specified for options rating, availability, date_listed, and delivery_method, with the first one used for the first search, and second one used for the rest of searches. This allows the use of different search strategies for first and subsequent searches. For example, an initial more lenient search for all listings followed by searches for only new listings can be specified as

rating = [2, 4]
availability = ["all", "in"]
date_listed = ["all", "last 24 hours"]

Showing statistics

ai-marketplace-monitor shows statistics such as the number of pages searched, number of listings examined and excluded, number of matching lists found and number of users notified when you exit the program. If you would like to see the statistics during monitoring, press Esc and wait till the current search to end.

Counters are persistent across program runs. If you would like to reset the counters, use

ai-marketplace-monitor --clear-cache counters

Self-hosted Ollama Model

If you have access to a decent machine and prefer not to pay for AI services from OpenAI or other vendors. You can opt to install Ollama locally and access it using the provider = "ollama". If you have ollama on your local host, you can use

[ai.ollama]
base_url = "http://localhost:11434/v1"
model = "deepseek-r1:14b"
timeout = 120

Note that

1. Depending on your hardware configuration, you can choose any of the models listed here. The default model is deepseek-r1:14b becaue it appears to work better than llama-3.1:8b.
2. You need to pull the model before you can use it.

Cache Management

ai-marketplace-monitor caches listing details, ai inquiries, and user notifications to avoid repeated queries to marketplaces, AI services, and repeated notification. If for any reason you would like to clear the cache, you can use commands such as

ai-marketplace-monitor --clear-cache listing-details

to clear the cache. The following cache types are supported

• listing-details
• ai-inquiries
• user-notification
• counters

--clear-cache all is also possible but not recommended.

Support for different layouts of facebook listings

Facebook marketplace supports a wide variety of products and use different layouts for them. ai_marketplace_monitor can extract description from common listings such as household items and automobiles, but you may encounter items that this program cannot handle.

Although I certainly do not have the bandwidth to support all possible layouts, I have listed detailed steps on how to debug and resolve the issue on issue 29.

Troubleshooting

1. Browser Login

   • You may need to manually enter credentials on first run
   • Answer any CAPTCHA prompts if presented
   • Consider saving password in browser if prompted

2. Notifications

   • Check rating level if receiving too many/few alerts
   • For email issues, verify SMTP settings and credentials
   • For PushBullet, verify token is correct

3. AI Services

   • Ensure API keys are valid
   • Check network connectivity
   • Verify model names if using custom models

For more issues, please check our Issues page.

Contributing

Contributions are welcome! Here are some ways you can contribute:

• 🐛 Report bugs and issues
• 💡 Suggest new features
• 🔧 Submit pull requests
• 📚 Improve documentation
• 🌍 Add support for new regions
• 🤖 Add support for new AI providers
• 📱 Add new notification methods

Please read our Contributing Guidelines before submitting a Pull Request.

Support

• 📖 Read the Documentation
• 🤝 Join our Discussions
• 🐛 Report Issues

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• Some of the code was copied from facebook-marketplace-scraper.
• Region definitions were copied from facebook-marketplace-nationwide, which is released under an MIT license as of Jan 2025.
• This package was created with Cookiecutter and the cookiecutter-modern-pypackage project template.