Files

T

Hanson.xyz Dev 6556479417 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>

2025-12-14 21:24:38 -06:00

3.4 KiB

Raw Blame History

MLS by HansonXyz Plugin

WordPress plugin for syncing MLS Grid API data (NorthStar MLS) into local database.

Development Rules

No emojis - nowhere in code, commits, docs, or conversation
PHP 7.4+ compatible code
WordPress Coding Standards
Follow patterns from existing HomeProz theme

Quick Reference

Database Tables

All tables use {$wpdb->prefix}mls_ prefix:

Table	Purpose
`mls_properties`	Listing data
`mls_media`	Media files
`mls_sync_state`	Sync progress tracking
`mls_rate_limits`	API usage tracking
`mls_sync_log`	Debug logging

API Configuration

Credentials in wp-config.php:

define('MLSGRID_API_URL', 'https://api.mlsgrid.com/v2');
define('MLSGRID_ACCESS_TOKEN', 'your-token-here');

MLS Grid API Rate Limits

MUST comply with these limits:

2 requests/second
7,200 requests/hour
40,000 requests/day
4GB data/hour

Key Files

File	Purpose
`includes/class-mls-api-client.php`	API communication, auth, gzip
`includes/class-mls-sync-engine.php`	Sync orchestration
`includes/class-mls-media-handler.php`	Media download/storage
`includes/class-mls-query.php`	Public query API
`includes/class-mls-rate-limiter.php`	Rate limit compliance
`cli/class-mls-cli.php`	WP-CLI commands

WP-CLI Commands

# Test connectivity
wp mls test connection
wp mls test auth

# Show status
wp mls status
wp mls status rate-limits

# Run sync
wp mls sync full [--dry-run] [--limit=N]
wp mls sync incremental [--dry-run]
wp mls sync media [--limit=N]
wp mls sync resume --id=<sync_id>

# Statistics
wp mls stats

# Cache management
wp mls cache clear --confirm
wp mls cache cleanup

Public API Functions

Available for themes/plugins:

// Get properties with filters
$properties = mls_get_properties([
    'status' => 'Active',
    'city' => 'Albert Lea',
    'min_price' => 100000,
    'limit' => 20,
]);

// Get single property
$property = mls_get_property('NST123456');

// Get media
$media = mls_get_property_media('NST123456');
$image_url = mls_get_property_image('NST123456');

// Get distinct values
$cities = mls_get_cities('Active');

// Check data availability
if (mls_is_available()) { ... }

Sync Strategy

Initial Import: Full sync downloads all viewable properties
Incremental: Uses ModificationTimestamp to fetch only changes
Delete Handling: MlgCanView=false triggers local deletion
Media: Downloads to wp-content/uploads/mls-listings/
Recovery: Stores last_next_link for resume on failure

Testing After Changes

wp mls test connection
wp mls test auth
wp mls sync full --dry-run --limit=10
wp mls stats

Property Data Mapping

Key fields from API to database:

API Field	DB Column
ListingKey	listing_key
ListingId	listing_id
ListPrice	list_price
StandardStatus	standard_status
BedroomsTotal	bedrooms_total
BathroomsTotalInteger	bathrooms_total
LivingArea	living_area
City	city
ModificationTimestamp	modification_timestamp
PhotosChangeTimestamp	photos_change_timestamp
MlgCanView	mlg_can_view

Full API response stored in raw_data column as JSON.

3.4 KiB Raw Blame History