📘 MLS Grid API Integration Guide

Version: 1.0.0

Environment: Staging

Base URL: https://mlsgrid.gojjoapps.com

📑 Table of Contents

🚀 Quick Start

Get started with the MLS Grid API in 3 simple steps:

1 Request OTP - Login with your email and password
2 Verify OTP - Check your email for the 6-digit code
3 Make API Calls - Use the access token for all requests

🔐 Authentication

All API endpoints require JWT Bearer token authentication.

Step 1: Request OTP

POST /api/v1/auth/login
curl -X POST https://mlsgrid.gojjoapps.com/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "password": "your-password" }'

Step 2: Verify OTP

POST /api/v1/auth/verify-otp
curl -X POST https://mlsgrid.gojjoapps.com/api/v1/auth/verify-otp \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "otp_code": "123456" }'
✅ Success! You'll receive an access token valid for 60 minutes.

🏠 MLS Grid Endpoints

List Properties

GET /api/v1/mls-grid/properties/

Query Parameters:

curl -X GET "https://mlsgrid.gojjoapps.com/api/v1/mls-grid/properties/?city=Austin&status=Active" \ -H "Authorization: Bearer YOUR_TOKEN"

Get Property Details

GET /api/v1/mls-grid/properties/{public_id}/

Get Property Media

GET /api/v1/mls-grid/media/{property_public_id}/

📊 Analytics Endpoints

Market Trends

GET /api/v1/analytics/trends/

Query Parameters:

Neighborhood Statistics

GET /api/v1/analytics/neighborhoods/{geography_value}/

Price Distribution

GET /api/v1/analytics/price-distribution/

⚠️ Error Handling

All errors follow a consistent format:

{ "detail": "Error message description", "error_code": "RESOURCE_NOT_FOUND", "timestamp": "2025-01-15T10:00:00Z" }

Common HTTP Status Codes

Code Meaning Action
200 Success Request succeeded
401 Unauthorized Get new access token
404 Not Found Resource doesn't exist
429 Rate Limited Wait and retry
500 Server Error Contact support

🚦 Rate Limiting

Limits:

  • 100 requests per minute (per IP)
  • 1000 requests per hour (per user)

Rate Limit Headers:

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1642262400

💻 Code Examples

Python

import requests # Request OTP response = requests.post( "https://mlsgrid.gojjoapps.com/api/v1/auth/login", json={"email": "[email protected]", "password": "password"} ) # Verify OTP response = requests.post( "https://mlsgrid.gojjoapps.com/api/v1/auth/verify-otp", json={"email": "[email protected]", "otp_code": "123456"} ) token = response.json()["access_token"] # Get properties headers = {"Authorization": f"Bearer {token}"} response = requests.get( "https://mlsgrid.gojjoapps.com/api/v1/mls-grid/properties/", params={"city": "Austin", "status": "Active"}, headers=headers ) properties = response.json()

JavaScript/TypeScript

// Request OTP const loginRes = await fetch('https://mlsgrid.gojjoapps.com/api/v1/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: '[email protected]', password: 'password' }) }); // Verify OTP const otpRes = await fetch('https://mlsgrid.gojjoapps.com/api/v1/auth/verify-otp', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: '[email protected]', otp_code: '123456' }) }); const { access_token } = await otpRes.json(); // Get properties const propsRes = await fetch( 'https://mlsgrid.gojjoapps.com/api/v1/mls-grid/properties/?city=Austin', { headers: { 'Authorization': `Bearer ${access_token}` } } ); const properties = await propsRes.json();

🔧 Troubleshooting

401 Unauthorized

Problem: Token expired or invalid
Solution: Request new OTP and verify

429 Rate Limited

Problem: Too many requests
Solution: Wait for the retry-after period and implement exponential backoff

Empty Results

Problem: No properties found
Solution: Check filter parameters and try broader search criteria

📚 Additional Resources

← Back to Dashboard