Skip to Content
ConceptsListingsListing search

How the listing search works

In Sharetribe, listings are searched by using the /listings/query  endpoint. Sharetribe has a powerful listing search engine, which can find listings based on multiple criteria. This article provides an overview of those criteria.

See the API reference documentation for a full list of available search parameters for the following endpoints:

Do note that for all search parameters created in custom code (i.e. outside Console configurations), you will need to create a search schema so that the data is indexed correctly for search.

The search can be used to find listings that have a certain keyword provided by the user. The search can find from listing title and description. You can also choose to index some public data fields so the search finds from them as well.

The keyword search works so that it matches the keywords parameter to text content of a listing. The listing attributes that are matched in keyword search by default are title and description. Listing public data fields can also be used in the keyword search by defining them to have type text in the marketplace’s listing public search schema. All text public data fields with defined schema are indexed for keyword search.

When the listing text content is indexed, in addition to indexing the actual word, it is also broken into subwords, n-grams. For words longer than 3 characters, n-grams of 3 and more characters are constructed from the beginning and end of the word. So if an indexed field contains the word local in addition to the actual word the following n-grams are indexed: loc, loca, ocal, and cal.

The search results are sorted so that a match with an actual word from the listing always weighs more than a match with an n-gram. The order in which matches in different fields of a listing effect the search score is the following: title > description > public data fields. However, the search score differences between the fields are substantially smaller than the difference between a match with an actual word in the listing and an n-gram. Listings that don’t match the search keywords at all are not included in the results.

The keywords parameter is a single string that is tokenized on non-alphanumeric characters. Therefore, passing local attractions as a value for the parameter will conduct a search with two keywords: local and attractions and those are then matched against the listing content. A listing will be included in the results, in case any of the keywords match.

If you are using Console configurations, you can configure your marketplace to use keyword search in Console. Read more in our Help Center:

The search can be used to display only listings that are within a provided radius from certain coordinates.

The listings search provides two parameters to modify the search by location: origin and bounds. origin parameter takes a single location. It does not limit the results in any way but it sorts the results from closest to the furthest from the given point. The origin parameter can not be combined with keywords.

In order to combine location and keyword search, the bounds parameter can be used. It takes north-east and south-west corners of a bounding box that limits the returned results to that area. It does not affect the sorting of results. The bounds can then conveniently be used to match search results to a map view.

The Sharetribe Web Template uses bounds search by default. You can also take the origin parameter to use in src/config/configMaps.js  if you are not using keyword search.

Custom filter search with extended data

In Sharetribe, only top-level extended data attributes can be indexed i.e. used for search. If you have a public data attribute where the value is a JSON object with nested attributes, it is not possible to create a search schema for the attribute.

So instead of using a nested attribute:

publicData: {
  instrumentProficiency: {
    // These attributes cannot be indexed for search in Sharetribe
    violin: 'professional',
    guitar: 'intermediate',
    tuba: 'beginner',
  },
}

you would need to set all attributes you want to query as top-level attributes:

publicData: {
  // These attributes can be indexed for search in Sharetribe
  violinProficiency: 'professional',
  guitarProficiency: 'intermediate',
  tubaProficiency: 'beginner',
}

This allows you to search for each attribute.

sdk.listings.query({
  pub_violinProficiency: 'professional',
  pub_guitarProficiency: ['beginner', 'intermediate'],
});

You would then index the attributes by adding a search schema according to the data type of the extended data attribute:

  • String values can be indexed for keyword search with schemaType: text, or for enum search, i.e. searching with the attribute name and exact values, using schemaType: enum
  • Arrays of strings can be indexed for multi-enum search, i.e. searching with the attribute name and exact values, using schemaType: multi-enum
  • Integers can be indexed for numeric search with start and end ranges using schemaType: long
  • Booleans can be indexed for boolean search using schemaType: boolean

Schema type multi-enum supports two types of query semantics: has_all i.e. AND semantics, and has_any i.e. OR semantics. The Sharetribe Web Template uses the default has_all querying when a multi-enum attribute is configured in Console. To configure a has_any attribute, you can follow the instructions in this article:

Prices can be searched with a single value, or with start and end parameters:

  • listings/query?price=2000 returns listings with the exact price of 2000 minor units of the listing’s currency (e.g. USD 20)
  • listings/query?price=2000,10000 returns listings with a price between 2000 and 10000 minor units of the listing’s currency (e.g. USD 20 - USD 100)
  • listings/query?price=2000, returns listings with a price at or above 2000 minor units of the listing’s currency (e.g. USD 20)
  • listings/query?price=,10000 returns listings with a price below 10000 minor units of the listing’s currency (e.g. USD 100)

The price filter does not consider the listing’s currency. This means that if you develop a multi-currency marketplace, listings costing e.g. USD 20 and HKD 20 will be returned with the same query.

Listings can be queried by their availability for booking. Listings can have either day-based or time-based availability, so availability filtering also has day-based and time-based options.

  • Day-based availability filtering matches listings with day-based availability plans. The corresponding query parameters are day-full and day-partial.
  • Time-based availability filtering matches listings with time-based availability plans. The corresponding query parametrers are time-full and time-partial. Queries using time-based availability filtering do not support pagination.

All bookable listings created with the Sharetribe Web Template use time-based availability plans by default. They therefore require time-based availability filtering, regardless of the unit type specified in the listing type.

Full availability queries, i.e. day-full and time-full, match listings that have the specified availability for the full duration of the queried time.

In the example below, a listing would be returned if it has at least three seats available for the full duration between the start and end time points.

sdk.listings.query({
  start: '2026-02-17T08:00:00.000Z',
  end: '2026-04-17T15:00:00.000Z',
  availability: 'time-full',
  seats: 3,
});

Partial availability queries, i.e. day-partial and time-partial, match listings that have the specified seats available for the specified minimum duration (days in day-partial, minutes in time-partial) at any point during the queried time. Partial queries using minDuration do not support pagination.

In the example below, a listing would be returned if it has at least three seats available for at least one hour at some point between the start and end time points.

sdk.listings.query({
  start: '2026-02-17T10:00:00.000Z',
  end: '2026-04-17T10:00:00.000Z',
  availability: 'time-partial',
  seats: 3,
  minDuration: '60',
});

In availability queries, the start and end moments must be at most 90 days apart. So to query intervals of more than 90 days at a time, you will need to combine results from multiple API calls.

Availability filtering typeday-fullday-partialtime-fulltime-partial
Match listings with availability plan typedaydaytimetime
Availability match typefullpartialfullpartial
Unit of minDuration parameter–days-minutes
Used in the Sharetribe Web Templatenonoyesyes
Supports result paginationyesnonono

Read more in the API reference:

You can filter your query to only return listings with positive stock using the minStock parameter.

sdk.listings.query({ minStock: 1 });

This query will only return listings where stock is defined and the value matches or exceeds minStock. This is because the API uses stockMode: strict by default.

On a marketplace with multiple listing types, you may also want to show listings that do not have defined stock, such as booking or free messaging listings. In that case, you can explicitly set the stockMode parameter to match-undefined alongside minStock:

sdk.listings.query({ minStock: 1, stockMode: 'match-undefined' });

The Sharetribe Marketplace API does not have an endpoint for querying users. This is because listings are modeled as the focus of the marketplace. If you do, however, want to implement a search functionality for users, you have a few options.

Users as listings

When modifying your listing creation flow, you can model the listings as service provider profiles. This means that the user entity is distinct from the user’s service provider entity. You can then use the default listing search to query the service provider profiles with all the query options described above.

This article in our Help Center has more detailed instructions on the option of using listings as user profiles:

Custom user search endpoint in the template server

The Sharetribe Integration API does have an endpoint for querying users. However, using the Integration API safely requires a secure environment, such as the template application server.

Never use Integration API from browser code! Integration API can only be securely used in server environments.

In addition, the Integration API /users/query  endpoint returns not only public user information but also non-public information.

This means that if you do want to use the Integration API user query, you need to create a custom server endpoint in the template’s server that calls the Integration API endpoint and only returns the user’s public information – public data and metadata – back to the browser. Otherwise, you risk revealing sensitive user information to everyone who visits your marketplace site.

You can see all of the available search parameters for the endpoint in our API reference:

Sorting your search results

Listing sorting order can be customized per query.

When a query uses keyword and origin parameters, the results are sorted based on those attributes as described above.

When using the sort parameter, sorting is supported by one or more of the following attributes:

  • listing price,
  • listing creation time,
  • or any numeric attribute in the listing’s public data or metadata.

The sort parameter supports up to three parameters in a single query.

Last updated on
Users and authenticationListings