Sign in
ProductListings

Simple product search via query parameters

Changed on

Performs canonical ProductListing search with query parameters. Text queries combine BM25 and embedding KNN retrieval when embedding generation succeeds; otherwise the backend falls back to BM25. Explicit non-score sorts use BM25. Any request with an Authorization header is private and not stored, including valid credentials that add user state. Anonymous successful 200 responses use public, max-age=0, s-maxage=60, stale-if-error=0; errors use private, no-store. Geographic predicates are AND; values in each country or subdivision set are OR. Missing geography never matches. Radius is inclusive in its supplied unit to the same recorded point used by distance ordering. Numeric origins never resolve from addresses/preferences. Distance ordering conflicts with sort and uses lexical text matching. Geographic responses are private, no-store and use eventually consistent OpenSearch projections; location updates can briefly lag in items, ordering, total and continuation. language defaults to en and currency defaults to EUR.

get/api/v1/product-listings

Request

  • Base URL: https://api.stage.aura-historia.com
  • URL: https://api.stage.aura-historia.com/api/v1/product-listings
  • Auth: one of:
    • HTTP bearer
    • none

Query parameters

countriesstring[]
subdivisionsstring[]
mode'STRICT' | 'APPROXIMATE'
distanceOrder'ASC' | 'DESC'

Advertised item geography; source defaults do not confirm individual physical custody.

{
  "countries": [
    "DE"
  ],
  "subdivisions": [
    "DE-BY"
  ],
  "radius": {
    "amount": 25,
    "unit": "KILOMETERS"
  }
}
language'de' | 'en' | 'fr' | 'es' | 'it' | 'zh' | 'pt' | 'pl' | 'tr' | 'nl' | 'cs' | 'ja' | 'ru' | 'ar'

Supported language codes (ISO 639-1 canonical values):

  • de: German (includes de-DE, de-AT, de-CH, de-LU, de-LI)
  • en: English (includes en-US, en-GB, en-AU, en-CA, en-NZ, and backend-specific accepted alias en_IE)
  • fr: French (includes fr-FR, fr-CA, fr-BE, fr-CH, fr-LU)
  • es: Spanish (includes es-ES, es-MX, es-AR, es-CO, es-CL, es-PE, es-VE)
  • it: Italian (includes it-IT, it-CH)
  • zh: Chinese (Simplified) (includes zh-CN, zh-Hans)
  • pt: Portuguese (includes pt-PT, pt-BR)
  • pl: Polish (includes pl-PL)
  • tr: Turkish (includes tr-TR)
  • nl: Dutch (includes nl-NL, nl-BE)
  • cs: Czech (includes cs-CZ)
  • ja: Japanese (includes ja-JP)
  • ru: Russian (includes ru-RU)
  • ar: Arabic (includes ar-SA, ar-EG, ar-AE)

de, en, fr, es, and it are fully supported localization/translation-target languages. zh, pt, pl, tr, nl, cs, ja, ru, and ar are ingestion-only languages: they can appear in stored/native content and are accepted anywhere LanguageData is used, but backend-generated translations and fallback localized strings are not produced in these languages.

Example:de

Language used for search matching and localized response fields; defaults to en

currency'EUR' | 'GBP' | 'USD' | 'AUD' | 'CAD' | 'NZD' | 'CNY' | 'BRL' | 'PLN' | 'TRY' | 'JPY' | 'CZK' | 'RUB' | 'AED' | 'SAR' | 'HKD' | 'SGD' | 'CHF' | 'ZAR' | 'SEK' | 'DKK' | 'NOK' | 'KRW' | 'INR' | 'TWD' | 'HUF' | 'RON' | 'MXN' | 'THB'

Supported currencies (ISO 4217 codes):

  • EUR: Euro
  • GBP: British Pound
  • USD: US Dollar
  • AUD: Australian Dollar
  • CAD: Canadian Dollar
  • NZD: New Zealand Dollar
  • CNY: Chinese Yuan
  • BRL: Brazilian Real
  • PLN: Polish Złoty
  • TRY: Turkish Lira
  • JPY: Japanese Yen
  • CZK: Czech Koruna
  • RUB: Russian Ruble
  • AED: UAE Dirham
  • SAR: Saudi Riyal
  • HKD: Hong Kong Dollar
  • SGD: Singapore Dollar
  • CHF: Swiss Franc
  • ZAR: South African Rand
  • SEK: Swedish Krona
  • DKK: Danish Krone
  • NOK: Norwegian Krone
  • KRW: South Korean Won
  • INR: Indian Rupee
  • TWD: New Taiwan Dollar
  • HUF: Hungarian Forint
  • RON: Romanian Leu
  • MXN: Mexican Peso
  • THB: Thai Baht
Example:EUR

Currency used to select the indexed price field; defaults to EUR; no request-time currency conversion occurs

productQuerystring[]

Optional text queries for product-listings. Multiple entries are ORed together.

enhancedSearchDescriptionstring

Optional natural-language description used to refine matching.

excludeProductIdstring[]

Optional product IDs to exclude from results.

listingSourceIdstring[]

Optional ListingSource IDs to include. A result must belong to one of the supplied sources.

excludeListingSourceIdstring[]

Optional ListingSource IDs to exclude from results.

auctionIdstring[]

Exact resolved Auction membership IDs. Repeat up to 100 distinct strict auc_ TypeIDs; supplied IDs OR together and intersect all other filters. Listings without resolved membership do not match.

mininteger

Minimum price (inclusive) in minor currency units for the selected indexed currency

maxinteger

Maximum price (inclusive) in minor currency units for the selected indexed currency

Optional price range filter in minor currency units (e.g. cents for most supported currencies, whole yen for JPY). Use price[min] and/or price[max] to specify the range bounds.

{
  "min": 1000,
  "max": 50000
}
availabilityListingAvailabilityData[]

Optional exact availability assertions. Values are ORed.

[
  "IN_STOCK"
]
minstring date-time

Minimum creation datetime (inclusive, RFC3339 format)

maxstring date-time

Maximum creation datetime (inclusive, RFC3339 format)

Optional filter by product creation date range (RFC3339 format). Use created[min] and/or created[max] to specify the datetime bounds.

{
  "min": "2024-01-01T00:00:00Z",
  "max": "2024-12-31T23:59:59Z"
}
minstring date-time

Minimum last-updated datetime (inclusive, RFC3339 format)

maxstring date-time

Maximum last-updated datetime (inclusive, RFC3339 format)

Optional filter by product last-updated date range (RFC3339 format). Use updated[min] and/or updated[max] to specify the datetime bounds.

{
  "min": "2024-01-01T00:00:00Z",
  "max": "2024-12-31T23:59:59Z"
}
minstring date-time

Inclusive minimum exact lot bidding-open instant (RFC3339)

maxstring date-time

Exclusive maximum exact lot bidding-open instant (RFC3339)

Optional exact lot-bidding-open range (RFC3339 instants). Use lotBiddingOpens[min] and/or lotBiddingOpens[max] for [min, max) bounds. Date-only and absent lot times never match this filter.

{
  "min": "2025-05-01T00:00:00Z",
  "max": "2025-05-31T23:59:59Z"
}
minstring date-time

Inclusive minimum exact lot scheduled-close instant (RFC3339)

maxstring date-time

Exclusive maximum exact lot scheduled-close instant (RFC3339)

Optional exact lot-scheduled-close range (RFC3339 instants). Use lotScheduledCloses[min] and/or lotScheduledCloses[max] for [min, max) bounds. Date-only and absent lot times never match this filter.

{
  "min": "2025-05-01T00:00:00Z",
  "max": "2025-05-31T23:59:59Z"
}
sort'score' | 'updated' | 'created'

Fields available for sorting:

  • score: Sort by relevance score (default, only available when searching with text query)
  • updated: Sort by last updated timestamp
  • created: Sort by creation timestamp
Example:updated

Field to sort results by

order'asc' | 'desc'

Sort order (only valid when sort is specified)

searchAfterstring

Opaque ProductListing cursor for pagination. Pass the complete JSON object returned as searchAfter in the previous response as one query value. It pins the FX snapshot for the full cursor chain.

sizeinteger

Number of product-listings to return per page

Response

Simple search results returned successfully

sizeinteger required

Number of items returned in the current page.

totalinteger nullable

Total matching product-listings for BM25 search when the backend provides it. Hybrid BM25 plus KNN search omits this value because its fused candidate pool is not a reliable total.

Example response

{
  "items": [
    {
      "item": {
        "productListingTitleSlugId": "museum-cabinet-18-19-century-a1b2c3",
        "title": {
          "language": "de"
        },
        "displayPrice": {
          "currency": "EUR"
        },
        "availability": "IN_STOCK",
        "lifecycle": "ACTIVE",
        "images": [
          {
            "url": "https://my-listing-source.com/images/product-1.jpg"
          }
        ]
      },
      "userState": {
        "watchlist": {
          "watching": true
        },
        "searchFilter": {
          "matched": true,
          "userSearchFilterId": "sf_4hyqf0gyxveazss7nby5hve5x2",
          "userSearchFilterName": "Vintage Art Deco",
          "matchFeedback": true
        }
      }
    }
  ],
  "size": 21,
  "total": 127,
  "searchAfter": {
    "fxRateId": "fx_0cwktgjtwnf4tb6hf2f8zm0x5k",
    "searchAfter": [
      2999,
      "pl_5xdb465tg1enarx2knf04mxbxj"
    ]
  }
}

Changes

  • ba3dfa02ef63Revision changes
    • breaking

      the response property's min was decreased from 1.00 to 0.00 for the response status

    • warning

      deleted the query request parameter auctionEnd

    • warning

      deleted the query request parameter auctionStart

    • warning

      removed the optional property //////// from the response with the status

    • warning

      added the new DKK enum value to the ///////// response property for the response status

    • warning

      added the new HUF enum value to the ///////// response property for the response status

    • warning

      added the new INR enum value to the ///////// response property for the response status

    • warning

      added the new KRW enum value to the ///////// response property for the response status

    • warning

      added the new MXN enum value to the ///////// response property for the response status

    • warning

      added the new NOK enum value to the ///////// response property for the response status

    • warning

      added the new RON enum value to the ///////// response property for the response status

    • warning

      added the new SEK enum value to the ///////// response property for the response status

    • warning

      added the new THB enum value to the ///////// response property for the response status

    • warning

      added the new TWD enum value to the ///////// response property for the response status

    • warning

      added the new ZAR enum value to the ///////// response property for the response status

    • info

      added the new optional query request parameter auctionId

    • info

      added the new optional query request parameter geography

    • info

      added the new optional query request parameter lotBiddingOpens

    • info

      added the new optional query request parameter lotScheduledCloses

    • info

      added the new enum value DKK to the query request parameter currency

    • info

      added the new enum value HUF to the query request parameter currency

    • info

      added the new enum value INR to the query request parameter currency

    • info

      added the new enum value KRW to the query request parameter currency

    • info

      added the new enum value MXN to the query request parameter currency

    • info

      added the new enum value NOK to the query request parameter currency

    • info

      added the new enum value RON to the query request parameter currency

    • info

      added the new enum value SEK to the query request parameter currency

    • info

      added the new enum value THB to the query request parameter currency

    • info

      added the new enum value TWD to the query request parameter currency

    • info

      added the new enum value ZAR to the query request parameter currency

    • info

      for the query request parameter searchAfter, the type was generalized from object to string

    • info

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

    • info

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

  • 88693e4138a6Revision changes
    • warning

      removed the optional property //////// from the response with the status