Skip to content
HomeStar Docs

Search API

The Search API provides advanced search capabilities including semantic (natural language), multi-modal (text + images), and visual similarity search.

Section titled “Semantic Search”

Search properties using natural language descriptions.

POST /api/search/semantic

Request Body

Section titled “Request Body”
{
  "query": "modern kitchen with granite countertops",
  "city": "Twin Falls",
  "min_price": 200000,
  "max_price": 500000,
  "limit": 20
}
FieldTypeRequiredDescription
querystringYesNatural language search query
citystringNoFilter by city
min_pricenumberNoMinimum price filter
max_pricenumberNoMaximum price filter
min_bedsintegerNoMinimum bedrooms
limitintegerNoMax results (default: 20)

Example Request

Section titled “Example Request”
Terminal window
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "query": "family home with large backyard near schools",
       "city": "Twin Falls",
       "min_beds": 3
     }' \
     https://api.your-domain.com/api/search/semantic

Response

Section titled “Response”
{
  "query": "family home with large backyard near schools",
  "results": [
    {
      "listing_id": "202412345",
      "list_price": 375000,
      "address": "456 Oak Lane",
      "city": "Twin Falls",
      "beds": 4,
      "baths": 2.5,
      "similarity": 0.89,
      "matched_text": "...spacious backyard perfect for families..."
    }
  ],
  "total": 15,
  "search_type": "semantic"
}

The similarity score ranges from 0 to 1, with higher scores indicating better matches.

Section titled “Multi-Modal Search”

Combine text search with image description matching for richer results.

POST /api/search/multimodal

Request Body

Section titled “Request Body”
{
  "query": "open concept living room with vaulted ceilings",
  "include_images": true,
  "limit": 20
}

Response

Section titled “Response”
{
  "query": "open concept living room with vaulted ceilings",
  "results": [
    {
      "listing_id": "202412345",
      "list_price": 425000,
      "text_similarity": 0.82,
      "image_similarity": 0.91,
      "combined_score": 0.87,
      "matching_images": [
        {
          "url": "https://photos.mlsgrid.com/living-room.jpg",
          "description": "Spacious living room with 20-foot vaulted ceilings",
          "similarity": 0.91
        }
      ]
    }
  ],
  "search_type": "multimodal"
}

Compare Search Methods

Section titled “Compare Search Methods”

Run a search against all methods to compare results.

POST /api/search/compare

Request Body

Section titled “Request Body”
{
  "query": "modern kitchen with island"
}

Response

Section titled “Response”
{
  "query": "modern kitchen with island",
  "methods": {
    "semantic": {
      "results": [...],
      "count": 15,
      "avg_similarity": 0.76
    },
    "image_description": {
      "results": [...],
      "count": 12,
      "avg_similarity": 0.81
    },
    "visual_embedding": {
      "results": [...],
      "count": 10,
      "avg_similarity": 0.73
    }
  },
  "recommendation": "image_description"
}
Section titled “Image Search”

Search by Description

Section titled “Search by Description”

Find images based on automatically generated descriptions.

GET /api/admin/search/images?q=granite+countertops
ParameterTypeDescription
qstringSearch query (min 2 chars)
limitintegerMax results (default: 20, max: 50)

Response

Section titled “Response”
{
  "query": "granite countertops",
  "results": [
    {
      "image_id": 123,
      "listing_id": "202412345",
      "image_url": "https://photos.mlsgrid.com/kitchen.jpg",
      "image_index": 2,
      "description": "Modern kitchen featuring dark granite countertops...",
      "room_type": "kitchen",
      "similarity": 0.88
    }
  ],
  "total": 45,
  "search_type": "image_description"
}
Section titled “Visual Similarity Search”

Find images that look similar using SigLIP embeddings.

GET /api/admin/search/images-visual?q=modern+white+kitchen

Find Similar Images

Section titled “Find Similar Images”

Find photos similar to a specific property photo.

POST /api/search/similar-images

Request Body

Section titled “Request Body”
{
  "image_url": "https://photos.mlsgrid.com/kitchen.jpg",
  "limit": 10
}

Autocomplete

Section titled “Autocomplete”

Get search suggestions as the user types.

GET /api/search/autocomplete?q=twin
ParameterTypeDescription
qstringPartial search query
limitintegerMax suggestions (default: 10)

Response

Section titled “Response”
{
  "suggestions": [
    {"text": "Twin Falls", "type": "city", "count": 156},
    {"text": "Twin Falls County", "type": "county", "count": 245},
    {"text": "twin home", "type": "property_type", "count": 23}
  ]
}

Image Indexing (Admin)

Section titled “Image Indexing (Admin)”

Get Index Statistics

Section titled “Get Index Statistics”
GET /api/admin/embeddings/images/stats

Response

Section titled “Response”
{
  "total_properties": 1250,
  "properties_with_images": 1180,
  "total_images": 7500,
  "description_embeddings": 6800,
  "visual_embeddings": 5200
}

Trigger Reindex

Section titled “Trigger Reindex”
POST /api/admin/embeddings/reindex/images?limit=10
ParameterTypeDescription
limitintegerMax properties to process (1-100)
backgroundbooleanRun as background task
Section titled “Related”