Add MLS by HansonXyz plugin for MLS Grid API integration
Features: - Full sync of NorthStar MLS properties via MLS Grid API v2 - Incremental sync using ModificationTimestamp - Local media download and storage - Rate limit compliance (2 req/sec, 7200/hr, 40000/day) - Sync state tracking with resume capability - WP-CLI commands: test, sync, status, stats, cache - Admin settings page with manual sync triggers - Public API functions: mls_get_properties, mls_get_property, etc. Database tables: - mls_properties: Listing data with full field mapping - mls_media: Downloaded images - mls_sync_state: Sync progress tracking - mls_rate_limits: API usage tracking - mls_sync_log: Debug logging Documentation: - docs/CLAUDE.md: AI development guide - docs/API.md: MLS Grid API reference - docs/USAGE.md: User documentation Tested: Connection, auth, sync 10 records, media download verified 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hanson.xyz Dev
@@ -0,0 +1,244 @@
|
||||
# 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
|
||||
|
||||
```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
|
||||
|
||||
# Download pending media
|
||||
wp mls sync media
|
||||
```
|
||||
|
||||
### Via Cron
|
||||
|
||||
Add to your system crontab for scheduled sync:
|
||||
|
||||
```bash
|
||||
# Run incremental sync every hour
|
||||
0 * * * * cd /var/www/html && wp mls sync incremental --allow-root
|
||||
```
|
||||
|
||||
## 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 '<img src="' . esc_url($image->local_url) . '">';
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## Support
|
||||
|
||||
For plugin issues: Check logs at Settings > MLS Settings
|
||||
|
||||
For API issues: Contact MLS Grid support at support@mlsgrid.com
|
||||
Reference in New Issue
Block a user