Properties API

The Properties API provides access to real estate listings, including search, filtering, and detailed property information.

List Properties

Retrieve a paginated list of properties with optional filters.

GET /api/properties

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
page_size	integer	Items per page (default: 20, max: 100)
city	string	Filter by city name
state	string	Filter by state (default: ID)
min_price	number	Minimum list price
max_price	number	Maximum list price
min_beds	integer	Minimum bedrooms
max_beds	integer	Maximum bedrooms
min_baths	number	Minimum bathrooms
max_baths	number	Maximum bathrooms
property_type	string	Property type (Residential, Land, Commercial)
status	string	Listing status (Active, Pending, Sold)
sort_by	string	Sort field (list_price, beds, baths, sqft, list_date)
sort_order	string	Sort direction (asc, desc)

Spatial Search

Spatial search provides accurate distance calculations on the Earth’s surface.

Bounding Box Search

Find properties within a rectangular area (ideal for map views).

GET /api/properties?min_lat=42.5&max_lat=43.0&min_lng=-114.5&max_lng=-114.0

Parameter	Type	Description
min_lat	number	Southwest latitude
max_lat	number	Northeast latitude
min_lng	number	Southwest longitude
max_lng	number	Northeast longitude

Example Request

curl "https://api.your-domain.com/api/properties?\
min_lat=42.5&max_lat=43.0&\
min_lng=-114.5&max_lng=-114.0&\
page_size=10"

Example Response

{
  "items": [...],
  "total": 58,
  "page": 1,
  "page_size": 10,
  "total_pages": 6,
  "search_type": "spatial",
  "query_time_ms": 12.5
}

Radius Search

Find properties within a circular area from a center point.

GET /api/properties?center_lat=42.5569&center_lng=-114.4602&radius_miles=10

Parameter	Type	Description
center_lat	number	Center point latitude
center_lng	number	Center point longitude
radius_miles	number	Search radius in miles (max: 50)

When using radius search, each result includes a distance_miles field showing the exact distance from the center point.

Example Request

curl "https://api.your-domain.com/api/properties?\
center_lat=42.622&\
center_lng=-113.68&\
radius_miles=5&\
sort_by=distance_miles&\
sort_order=asc"

Example Response

{
  "items": [
    {
      "listing_id": "98970171",
      "list_price": 425000,
      "city": "Rupert",
      "distance_miles": 0.072,
      "latitude": 42.622562,
      "longitude": -113.679565
    },
    {
      "listing_id": "98969862",
      "list_price": 385000,
      "city": "Rupert",
      "distance_miles": 0.243
    }
  ],
  "total": 58,
  "search_type": "spatial",
  "query_time_ms": 15.2
}

Sorting by Distance

When performing a radius search, you can sort results by distance:

Parameter	Value	Description
sort_by	distance_miles	Sort by distance from center point
sort_order	asc	Closest first (default for distance)
sort_order	desc	Farthest first

Example Request

curl "https://api.your-domain.com/api/properties?\
city=Twin%20Falls&\
min_price=200000&\
max_price=500000&\
min_beds=3&\
sort_by=list_price&\
sort_order=asc"

Example Response

{
  "items": [
    {
      "listing_id": "202412345",
      "list_price": 325000,
      "beds": 4,
      "baths": 2.5,
      "sqft": 2100,
      "lot_size_acres": 0.25,
      "address": "123 Main Street",
      "city": "Twin Falls",
      "state": "ID",
      "zip": "83301",
      "property_type": "Residential",
      "status": "Active",
      "latitude": 42.5569,
      "longitude": -114.4602,
      "photos": [
        "https://photos.mlsgrid.com/photo1.jpg",
        "https://photos.mlsgrid.com/photo2.jpg"
      ],
      "list_date": "2024-12-15",
      "days_on_market": 13
    }
  ],
  "total": 156,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

Get Property Details

Retrieve complete details for a specific property.

GET /api/properties/{listing_id}

Path Parameters

Parameter	Type	Description
listing_id	string	MLS listing ID

Example Request

curl "https://api.your-domain.com/api/properties/202412345"

Example Response

{
  "listing_id": "202412345",
  "list_price": 325000,
  "beds": 4,
  "baths": 2.5,
  "sqft": 2100,
  "lot_size_acres": 0.25,
  "address": "123 Main Street",
  "city": "Twin Falls",
  "state": "ID",
  "zip": "83301",
  "county": "Twin Falls",
  "property_type": "Residential",
  "property_subtype": "Single Family Residence",
  "status": "Active",
  "latitude": 42.5569,
  "longitude": -114.4602,
  "year_built": 2018,
  "garage_spaces": 2,
  "stories": 2,
  "description": "Beautiful modern home with open floor plan...",
  "features": [
    "Granite Countertops",
    "Stainless Steel Appliances",
    "Hardwood Floors",
    "Smart Home Features"
  ],
  "photos": [...],
  "list_date": "2024-12-15",
  "list_agent": {
    "name": "Jane Smith",
    "phone": "208-555-0123",
    "email": "jane@example.com"
  },
  "list_office": "Sample Realty Co."
}

Find Nearby Properties

Discover properties near a specific listing. Perfect for “Similar Properties” or “Properties Nearby” sections.

GET /api/properties/{listing_id}/nearby

Path Parameters

Parameter	Type	Description
listing_id	string	MLS listing ID of the reference property

Query Parameters

Parameter	Type	Default	Description
radius_miles	number	5	Search radius in miles (max: 50)
limit	integer	10	Maximum properties to return (max: 50)

Example Request

curl "https://api.your-domain.com/api/properties/98970171/nearby?radius_miles=10&limit=5"

Example Response

[
  {
    "listing_id": "98944977",
    "list_price": 418500,
    "distance_miles": 0.105,
    "street_number": "1021",
    "street_name": "I",
    "street_suffix": "St",
    "city": "Rupert",
    "state_or_province": "ID",
    "bedrooms_total": 4,
    "bathrooms_total_integer": 4,
    "living_area": 2833,
    "primary_photo_url": "https://photos.example.com/98944977/photo-01.jpg"
  },
  {
    "listing_id": "98961102",
    "list_price": 399900,
    "distance_miles": 0.143,
    "city": "Rupert",
    "bedrooms_total": 3,
    "bathrooms_total_integer": 3
  }
]

Note

Results are always sorted by distance ascending (closest first). Only active listings with valid location data are returned.

Error Responses

Status	Condition
404 Not Found	Reference property doesn’t exist
400 Bad Request	Reference property has no location data

Generate Property PDF

Generate a downloadable PDF brochure for a property.

GET /api/properties/{listing_id}/pdf

Query Parameters

Parameter	Type	Description
agent_id	integer	Include agent branding (optional)

Example

curl -o property.pdf \
     "https://api.your-domain.com/api/properties/202412345/pdf"

Tip

The PDF includes property photos, details, a QR code linking to the listing, and optional agent contact information.

List Cities

Get a list of cities with active property counts.

GET /api/properties/cities/list

Example Response

{
  "cities": [
    {"city": "Twin Falls", "count": 156},
    {"city": "Jerome", "count": 89},
    {"city": "Burley", "count": 67},
    {"city": "Rupert", "count": 45}
  ]
}

Property Fields Reference

Core Fields

Field	Type	Description
listing_id	string	Unique MLS identifier
list_price	number	Current asking price
beds	integer	Number of bedrooms
baths	number	Number of bathrooms
sqft	integer	Living area in square feet
lot_size_acres	number	Lot size in acres
year_built	integer	Year of construction

Location Fields

Field	Type	Description
address	string	Street address
city	string	City name
state	string	State abbreviation
zip	string	ZIP code
county	string	County name
latitude	number	GPS latitude
longitude	number	GPS longitude

Status Fields

Field	Type	Description
status	string	Active, Pending, Sold, etc.
list_date	date	Date listed
sold_date	date	Date sold (if applicable)
days_on_market	integer	Days since listing

Spatial Search Fields

These fields are only populated when performing spatial searches.

Field	Type	Description
distance_miles	number	Distance from search center point (radius search only)
similarity_score	number	Semantic similarity score (semantic search only)

Error Responses

Property Not Found

{
  "detail": "Property not found"
}

Status: 404 Not Found

Invalid Filter

{
  "detail": "min_price must be a positive number"
}

Status: 422 Unprocessable Entity

Related

• Effective Property Search — Search best practices and strategies
• Search API — Semantic search capabilities