# MLS by HansonXyz - User Documentation ## Overview This plugin syncs property listing data from MLS Grid (NorthStar MLS) into your WordPress database, making it available for use by themes and other plugins. ## Installation 1. Upload the `mls-by-hansonxyz` folder to `/wp-content/plugins/` 2. Activate the plugin through the WordPress admin 3. Configure API credentials (see below) 4. Run initial sync ## Configuration ### API Credentials Add to your `wp-config.php`: ```php define('MLSGRID_API_URL', 'https://api.mlsgrid.com/v2'); define('MLSGRID_ACCESS_TOKEN', 'your-access-token-here'); ``` Alternatively, configure via Settings > MLS Settings in WordPress admin. ### Settings Navigate to **Settings > MLS Settings** to configure: - **Originating System**: MLS identifier (default: `northstar`) - **Auto Sync**: Enable automatic background sync - **Sync Interval**: How often to sync (30min to daily) - **Sync Media**: Whether to download listing photos ## Running Sync ### Via Admin Panel 1. Go to Settings > MLS Settings 2. Click "Run Incremental Sync" or "Run Full Sync" 3. Wait for completion ### Via WP-CLI #### Smart Sync (Recommended) The `wp mls run` command is the recommended way to sync. It automatically handles all scenarios: ```bash wp mls run # Smart sync with progress wp mls run --quiet # Status messages only wp mls run --verbose # Full API details wp mls run --silent # For cron (no output) ``` **What it does automatically:** - If a sync is already running: aborts (prevents duplicates) - If a previous sync failed/interrupted: resumes it - If no data exists: runs full sync - Otherwise: runs incremental sync Failed syncs are automatically resumed on the next run - no manual intervention needed. #### Manual Sync Commands For more control, use the individual sync commands: ```bash # Test connection first wp mls test connection wp mls test auth # Run initial full sync wp mls sync full # Run incremental updates wp mls sync incremental # Use --verbose for detailed output wp mls sync full --verbose wp mls sync incremental --verbose ``` #### Progress Indicators During sync, you'll see progress characters: - `.` = new property - `#` = updated property - `x` = deleted property - `P` = photo downloaded - `p` = photo skipped (exists) - `E` = photo error - `|` = page complete Use `--verbose` for detailed timestamped output showing API requests and individual items. ### Via Unix Cron Add to your system crontab (`crontab -e`) for scheduled sync: ```bash # Smart sync every 15 minutes (recommended) # Automatically handles: initial sync, incremental updates, and error recovery */15 * * * * cd /var/www/html && wp mls run --silent --allow-root >> /var/log/mls-sync.log 2>&1 ``` That's it! The `wp mls run` command handles everything automatically: - First run: performs full initial sync - Subsequent runs: performs incremental sync - After failures: resumes from where it left off - Concurrent runs: safely aborts if another sync is running **For more control**, use the individual commands: ```bash # Incremental sync every hour 0 * * * * cd /var/www/html && wp mls sync incremental --allow-root >> /var/log/mls-sync.log 2>&1 # Full sync weekly (Sunday at 3am) to rebuild from scratch 0 3 * * 0 cd /var/www/html && wp mls sync full --allow-root >> /var/log/mls-sync.log 2>&1 ``` **Important Notes:** - Use `--allow-root` when running as root user - Redirect output to a log file for debugging - MLS Grid requires refresh at least every 12 hours per IDX rules - The plugin handles rate limits automatically (waits if approaching limits) - Media images are fetched on-demand when properties are viewed (no separate cron needed) ### Via WP-Cron (Alternative) Enable auto-sync in Settings > MLS Settings to use WordPress's built-in cron system. This runs on page loads rather than true system cron, so may be less reliable for high-frequency syncs. ## Checking Status ### Via Admin Settings > MLS Settings shows: - Database statistics (property counts by status) - Last sync time and results - Rate limit usage ### Via CLI ```bash # Full status wp mls status # Just rate limits wp mls status rate-limits # Database statistics wp mls stats ``` ## Using the Data ### For Theme Developers The plugin provides global helper functions: ```php // Get active properties in a city $properties = mls_get_properties([ 'status' => 'Active', 'city' => 'Albert Lea', 'limit' => 20, ]); foreach ($properties as $property) { echo $property->list_price; echo $property->bedrooms_total; echo $property->city; } // Get a single property $property = mls_get_property('NST123456'); // Get property images $media = mls_get_property_media($property->listing_key); $primary_image = mls_get_property_image($property->listing_key); // Get cities with active listings $cities = mls_get_cities('Active'); // Check if data is available if (mls_is_available()) { // Show property search } ``` ### Query Parameters `mls_get_properties()` accepts these filters: | Parameter | Type | Description | |-----------|------|-------------| | status | string | Active, Pending, Closed | | property_type | string | Residential, Land, etc. | | city | string | City name | | county | string | County name | | postal_code | string | ZIP code | | min_price | int | Minimum price | | max_price | int | Maximum price | | min_beds | int | Minimum bedrooms | | max_beds | int | Maximum bedrooms | | min_baths | int | Minimum bathrooms | | min_sqft | int | Minimum square feet | | max_sqft | int | Maximum square feet | | search | string | Search address/remarks | | limit | int | Results per page | | offset | int | Pagination offset | | orderby | string | Sort field | | order | string | ASC or DESC | | include_media | bool | Include media array | ### Property Object Fields Each property object includes: ```php $property->listing_key // Unique ID $property->listing_id // MLS number $property->list_price // Price $property->standard_status // Active, Pending, Closed $property->street_number $property->street_name $property->street_suffix $property->city $property->state_or_province $property->postal_code $property->county $property->latitude $property->longitude $property->property_type $property->property_sub_type $property->bedrooms_total $property->bathrooms_total $property->living_area // Square feet $property->lot_size_area $property->year_built $property->garage_spaces $property->public_remarks // Description $property->directions $property->list_office_name $property->photos_count $property->days_on_market $property->modification_timestamp ``` ## Media Storage Downloaded images are stored in: ``` wp-content/uploads/mls-listings/{prefix}/{listing_key}/ ``` Images are named by order: `1.jpg`, `2.jpg`, etc. Access via: ```php $media = mls_get_property_media($listing_key); foreach ($media as $image) { echo ''; } ``` ## Troubleshooting ### Connection Failed 1. Verify API token is correct in wp-config.php 2. Check that MLSGRID_API_URL is set 3. Run `wp mls test connection` for details ### No Data After Sync 1. Check `wp mls status` for errors 2. Review rate limits - may need to wait 3. Check WordPress debug log for API errors ### Media Not Downloading 1. Verify `sync_media` is enabled in settings 2. Check upload directory is writable 3. Run `wp mls sync media` manually ### Rate Limit Exceeded The plugin automatically waits when approaching limits. If suspended: 1. Wait for the rate limit window to reset 2. Reduce sync frequency 3. Contact MLS Grid support if persistent ### Clearing Data To start fresh: ```bash wp mls cache clear --confirm ``` This removes all synced data but keeps settings. ### Missing Media Log Failed media downloads are logged for review: ```bash # View missing media log wp mls cache missing # View first 20 entries wp mls cache missing --limit=20 # Clear the log wp mls cache missing --clear ``` Log location: `wp-content/uploads/mls-missing-media.log` The log shows listing key, media key, error type, and original URL for each failed download. Media downloads automatically retry with exponential backoff (up to 5 attempts) for rate limit and server errors. ## Support For plugin issues: Check logs at Settings > MLS Settings For API issues: Contact MLS Grid support at support@mlsgrid.com