Sign in
Listings V2

Search listings

Changed on

Search listings with filters

Searches active listings using full-text search, quality tier filters, price filters, and game item filters. Uses the listing_search view for optimized query performance.

Requirements:

  • 15.1: GET /api/v2/listings/search endpoint
  • 15.2: Accept text query parameter for full-text search
  • 15.3: Accept game_item_id parameter for item filtering
  • 15.4: Accept quality_tier_min and quality_tier_max parameters
  • 15.5: Accept price_min and price_max parameters
  • 15.6: Accept page and page_size parameters for pagination
  • 15.7: Return listings with price_min, price_max, quality_tier_min, quality_tier_max
  • 15.8: Return total count for pagination
  • 15.9: Support sorting by created_at, price, quality, seller_rating
  • 15.10: Include seller information in results
  • 15.11: Include variant_count in results
  • 15.12: Execute queries within 50ms performance target
get/listings/search

Request

  • Base URL: /api/v2 (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v2/listings/search
  • Auth: none required

Query parameters

textstring

Full-text search query

game_item_idstring

Filter by specific game item UUID

quality_tier_minnumber double

Minimum quality tier (1-5)

quality_tier_maxnumber double

Maximum quality tier (1-5)

quality_value_minnumber double
quality_value_maxnumber double
price_minnumber double

Minimum price filter

price_maxnumber double

Maximum price filter

pagenumber double

Page number for pagination (default: 1)

page_sizenumber double

Number of results per page (default: 20, max: 100)

item_typestring
quantity_minnumber double
status'active' | 'inactive' | 'sold' | 'expired' | 'cancelled'
sort_by'created_at' | 'updated_at' | 'price' | 'quality' | 'shop_rating' | 'quantity'

Sort field (default: created_at)

sort_order'asc' | 'desc'

Sort order (default: desc)

language_codesstring
listing_type'single' | 'bundle' | 'bulk'
shop_slugstring
pickup_method'delivery' | 'pickup' | 'any'
in_stockboolean
has_photosboolean
bulk_discountboolean

Response

Search results with pagination metadata

totalnumber double required

Total number of listings matching filters

pagenumber double required

Current page number

page_sizenumber double required

Number of results per page

Changes

  • 8e1023e85ab1Revision changes
    • ○

      added the new optional query request parameter bulk_discount

    • ○

      added the new optional query request parameter has_photos

    • ○

      added the new optional query request parameter in_stock

    • ○

      added the new optional query request parameter pickup_method

    • ○

      added the new optional query request parameter quality_value_max

    • ○

      added the new optional query request parameter quality_value_min

  • e0cd5d2dfa78Revision changes
    • ○

      added the required property // to the response with the status