Suggestions API

Autocomplete suggestions for search inputs. Returns phrase suggestions and listing matches. Improves over time via behavioral learning when users select options.

GET `/v1/listings/suggestions`

Response Fields

suggestions: Phrase completions; user clicks to trigger a full search with that phrase.
listings: Listing matches; user clicks to navigate directly to a listing or search with its full title.

Recording Selections (Behavioral Learning)

When a user selects a suggestion, call POST /v1/listings/suggestions/select to improve future suggestions:

curl -X POST "https://api.example.com/v1/listings/suggestions/select" \
  -H "Content-Type: application/json" \
  -H "tenant_id: 1" \
  -d '{
    "query": "fly",
    "selection_type": "phrase",
    "selection": "flyease"
  }'

Field	Type	Required	Description
`query`	string	Yes	Query the user typed
`selection_type`	string	Yes	`"phrase"` or `"listing"`
`selection`	string/object	Yes	For phrase: selected string. For listing: `{ listing_id, title }`
`locale`	string	No	Locale context

Client Integration Flow

Debounce user input (e.g. 300ms)
Call GET /v1/listings/suggestions?q={input}
Display dropdown with phrases and listings
On click: call POST /v1/listings/suggestions/select (fire-and-forget), then search or navigate

Parameters

string

Required

The user's partial search input. Minimum 2 characters. Can also be passed as the query parameter.

locale

string

Filter suggestions to a specific locale (e.g., 'en', 'ar'). Defaults to null.

limit

number

Maximum number of phrase suggestions to return. Defaults to 10.

listings_limit

number

Maximum number of listing matches to return alongside phrase suggestions. Defaults to 5.

GET/v1/listings/suggestions

curl https://api-eu-aisearch.tradly.app/v1/listings/suggestions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR....." \
  -H "Content-Type: application/json" \
  -d '{"q":"fly","locale":"en","limit":10,"listings_limit":5}'

RESPONSE

{
  "success": true,
  "suggestions": [
    "flyease",
    "flyknit",
    "fly running"
  ],
  "listings": [
    {
      "listing_id": "prod_123",
      "title": "Air Jordan 1 Hi FlyEase"
    },
    {
      "listing_id": "prod_456",
      "title": "Nike Flyknit Running"
    }
  ]
}