/suggest/autocomplete - Autocomplete suggestions

Overview

The /suggest/autocomplete endpoint provides autocomplete/typeahead suggestions for resort search queries.

Purpose

• Provide real-time search suggestions as users type
• Enable fast typeahead/autocomplete functionality
• Search across resort names
• Support instant resort discovery
• Improve search user experience

Endpoint

GET /suggest/autocomplete

Parameters

Query parameters

q (string, required)

Search query term for autocomplete suggestions. Searches against resort names only.

Minimum length: Typically 1-2 characters for useful results

Examples:

• q=Try - Returns resorts matching "Try" (e.g., Trysil)
• q=Oslo - Returns resorts with "Oslo" in name
• q=Hemse - Returns "Hemsedal"
• q=stor - Returns resorts with "stor" in name

Note: Search is case-insensitive and uses SQL LIKE matching with wildcards (%query%).

---

Response format

Success response structure

{
  "total": 12,
  "more_results": true,
  "result": [
    {
      "name": "Trysil",
      "site_path": "/trysil/"
    },
    {
      "name": "Trysilhøgda",
      "site_path": "/trysilhogda/"
    },
    {
      "name": "Oslo Vinterpark",
      "site_path": "/oslo-vinterpark/"
    },
    {
      "name": "Norefjell",
      "site_path": "/norefjell/"
    },
    {
      "name": "Kongsberg Skisenter",
      "site_path": "/kongsberg/"
    },
    {
      "name": "Varingskollen Alpinsenter",
      "site_path": "/varingskollen/"
    },
    {
      "name": "Hafjell",
      "site_path": "/hafjell/"
    },
    {
      "name": "Kvitfjell",
      "site_path": "/kvitfjell/"
    },
    {
      "name": "Gausdal",
      "site_path": "/gausdal/"
    },
    {
      "name": "Skeikampen",
      "site_path": "/skeikampen/"
    }
  ]
}

Error response (missing parameter)

{
  "error": "Missing required parameter: q"
}

---

Response fields

Top level fields

• total (integer): Total number of matching resorts found
• more_results (boolean): Whether there are more results beyond the returned set
  • true - More results exist (total > 10)
  • false - All matching results are included
• result (array): Array of matching resort suggestions (maximum 10)

Individual Result Fields

Each suggestion in result contains:

• name (string): Resort name
• site_path (string): URL path for the resort (e.g., "/trysil/")
  • Can be used to construct full URLs or navigate to resort pages
  • Always starts and ends with forward slash

Single Result Enhancement

When exactly one resort matches the query, each result object also includes:

• nearby (array): The 3 nearest resorts to help users discover alternatives
  • Each object contains: distance (integer, meters), name, site_path, id, sort

Example with single match:

{
  "total": 1,
  "more_results": false,
  "result": [
    {
      "name": "Trysil",
      "site_path": "/trysil/",
      "nearby": [
        {
          "distance": 45300,
          "name": "Sjusjøen",
          "site_path": "/sjusjoen/",
          "id": 89,
          "sort": "0"
        }
      ]
    }
  ]
}

---

Behavior details

Search logic

• Fields searched: Resort name only
• Match type: Priority matching - first tries "starts with" (query%), then "word starts with" (% query%), then falls back to "contains" (%query%)
• Case sensitivity: Case-insensitive
• Result limit: Maximum 10 suggestions returned
• Ordering: Relevance-based (exact/prefix matches first, then contains matches)

Performance

• Fast response: Optimized for real-time typeahead
• Database indexed: Uses indexed columns for quick lookup
• Limit enforced: Always returns max 10 results for speed

---

Example requests

Search for "Trysil"

GET /suggest/autocomplete?q=Trysil

Response:

{
  "total": 2,
  "more_results": false,
  "result": [
    {
      "name": "Trysil",
      "site_path": "/trysil/"
    },
    {
      "name": "Trysilhøgda",
      "site_path": "/trysilhogda/"
    }
  ]
}

---

Search for "Oslo"

GET /suggest/autocomplete?q=Oslo

Response:

{
  "total": 5,
  "more_results": false,
  "result": [
    {
      "name": "Oslo Vinterpark",
      "site_path": "/oslo-vinterpark/"
    },
    {
      "name": "Varingskollen Alpinsenter",
      "site_path": "/varingskollen/"
    }
  ]
}

(Note: May include resorts with "Oslo" in description even if not in name)

---

Search with many results

GET /suggest/autocomplete?q=ski

Response:

{
  "total": 35,
  "more_results": true,
  "result": [
    {
      "name": "Kongsberg Skisenter",
      "site_path": "/kongsberg/"
    },
    {
      "name": "Hemsedal Skisenter",
      "site_path": "/hemsedal/"
    }
    // ... 8 more results (10 total)
  ]
}

(Note: more_results: true indicates 25 additional matches not shown)

---

Single character search

GET /suggest/autocomplete?q=H

Response:

{
  "total": 18,
  "more_results": true,
  "result": [
    {
      "name": "Hafjell",
      "site_path": "/hafjell/"
    },
    {
      "name": "Hemsedal",
      "site_path": "/hemsedal/"
    }
    // ... up to 10 results
  ]
}

---

Use cases

1. Typeahead search box: Real-time suggestions as users type in a search field
2. Quick resort lookup: Fast resort finding without full search
3. Mobile autocomplete: Optimized for mobile search experiences
4. Resort discovery: Help users find resorts they may not know the exact name of
5. Navigation shortcuts: Quick navigation to resort pages
6. Search enhancement: Improve search UX with instant feedback
7. Form inputs: Autocomplete for resort selection in forms

---

Frontend integration example

// Debounced autocomplete handler
let timeout;
function handleAutocomplete(query) {
  clearTimeout(timeout);
  timeout = setTimeout(async () => {
    if (query.length < 2) return; // Wait for at least 2 characters

    const response = await fetch(`/suggest/autocomplete?q=${encodeURIComponent(query)}`);
    const data = await response.json();

    // Display suggestions
    displaySuggestions(data.result);

    // Optionally show "X more results" if data.more_results is true
    if (data.more_results) {
      showMoreResultsIndicator(data.total - data.result.length);
    }
  }, 300); // 300ms debounce
}

---

Notes

• The q parameter is required; omitting it returns an error
• Case-insensitive search works for all languages (Norwegian, English, etc.)
• Search matches name field only (not description)
• Results are limited to 10 to ensure fast response times
• When exactly 1 result is found, a nearby array with 3 nearest resorts is included
• The more_results flag indicates if the user should narrow their search
• The total count includes all matching resorts, not just the returned 10
• No pagination is supported - only first 10 results are returned
• Use /search endpoint for full-featured search with pagination and filtering
• The site_path can be appended to your base URL to link directly to resort pages
• Empty query (q=) returns an error (minimum 1 character required)
• Results include all resorts regardless of open/closed status
• For production use, consider implementing debouncing on the client side to reduce API calls
• The endpoint is optimized for sub-100ms response times for typical queries
• Matches are substring matches (e.g., "try" matches "Trysil", "Try", "try")