Querying Apps

When a user is looking to browse apps on your marketplace, it’s useful to display all the apps that have been approved by marketplace administrators. We call this the “user view” and you can get this information using the List Apps API method. Without any parameters this method will just return all the live versions of apps regardless of whether their status is “suspended” or “approved”. However, we only want the “user view” to contain apps with a status of “approved” and we can achieve this by passing a Query Document to the API.

  All fields can be used to query apps except fields within the ownership object.

The standard API call for creating a simple “user view” for a user with id “123”:

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps? 
  query={'status.value':'approved'}& 
  userId=123

This standard API call will display the following:

  • Apps that have been approved by marketplace administrators
  • Apps that have a current status of “approved”

If the user is logged in then you’ll want to supply the userId to the OpenChannel API calls. This allows OpenChannel to return additional information about the app including the ownership status relative to the current user.

Sorting Apps

When retrieving a list of apps, a Sort Document can be passed to determine the order in which apps are returned.

  All fields can be used to sort apps except fields within the ownership object.

An example API call sorting app results by name in ascending order:

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps? 
  query={'status.value':'approved'}& 
  sort={'name':1}& 
  userId=123

Additional fields can be added to the sort document to further refine the order.

An example API call sorting app results by name in ascending order and by date in descending order:

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps? 
  query={'status.value':'approved'}& 
  sort={'name':1, 'created':-1}& 
  userId=123

The randomize field is a random number that is specially designed to allow apps to be sorted randomly. In addition, an app’s randomize value changes periodically and ensures that all apps get a fair chance to be seen at the top of search results.

An example API call sorting app results randomly:

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps? 
  query={'status.value':'approved'}& 
  sort={'randomize':1}

The statistics field is filled with stats about the app and is specially designed to allow apps to be sorted by popularity. Each tracked statistic like views, downloads or custom statistics are available from within the statistics field by the following values:

  • 30Day refers to the popularity over a 30 day period. Sorting using a 30 day value is most useful with highly trafficked marketplaces.
  • 90Day refers to the popularity over a 90 day period. Sorting using a 90 day value is most useful when starting out or operating marketplaces with lower traffic volumes.
  • Total refers to the popularity over the life of the app. The total value is not recommended for sorting but could be useful when evaluating the overall popularity of an app.

An example API call sorting app results by popularity:

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps? 
  query={'status.value':'approved'}& 
  sort={'statistics.views.90day':-1}

Sometime you might want promoted or featured apps to always be at the top of the page. The attributes field contains fields that you can create from the Management Dashboard and can only be edited by marketplace administrators. See Marketplace Settings for more details about attributes.

An example API call sorting app results randomly but with featured apps always at the top:

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps? 
  query={'status.value':'approved'}& 
  sort={'attributes.featured':-1, 'randomize':1}