OpenCommerceSearch Javascript SDK

Description

JS version of the ProductApi SDK to be used on the server and (eventually) client.

Common Tasks

Install

npm install opencommercesearch-ocs-sdk

Test

Run style and unit tests once.

npm test

or

grunt test

Develop

Continuosly run style and unit tests while watching for changes.

grunt develop

Basic Usage

All API methods make async requests and return promises which support .then() .done() and .fail() methods. Read more about promises here.

var productApiService = require('opencommercesearch-sdk-js');

productApiService.config({
  host: 'api.domain.com'
});

productApiService
  .searchProducts({
    q: 'a search term',
    site: 'your_site'
  })
  .then(function(data) {
    // do something
  });

Utility Methods

.config(options)

Configures the service, best used at application startup.

.getConfig()

Returns the current configuration settings.

API Methods

Available methods are grouped below by the type of item returned (product, category, etc). All methods accept a single options object requiring at least a site, and usually one or more additional properties. Additionally, there are several optional properties that can be passed to most endpoints:

• fields --- all endpoints have default fields that can be overridden with a comma separated list of field names
  • dot notation is supported for nested fields brand.name
  • during development fields: '*' can be used to return all fields but is not recommended for production
  • always request the least amount of data required
• metadata --- (string) used to specify what metadata is returned and is useful for reducing the size of the request
  • for a product search request where facets are not required, using metadata: found can significantly reduce the size of the response
• limit --- (int) number of items to return, search/browse endpoints have a max limit of 40
• offset --- (int) number of items to offset, used for pagination on search/browse endpoints
• preview --- (boolean) whether or not to return results from the preview environment
• outlet --- (boolean) whether or not to return products/categories in outlet
• filterQueries --- (string) filters (facets) to apply to search/browse endpoints, values can be found in metadata.facets.filters.filterQueries

Products

.findProducts(options)

Returns the specified product(s). Multiple products can be requested at once by passing a comma-separated string or array of productIds.

.searchProducts(options)

Returns all products that match the search query.

.browseCategory(options)

Returns all products belonging to a particular category.

.browseBrand(options)

Returns all products belonging to a particular brand.

.browseBrandCategory(options)

Returns all products belonging to a particular brand and category.

.findSimilarProducts(options)

Returns products similar to the product specified.

.findProductGenerations(options)

Returns all generations of the product.

.suggestProducts(options)

Returns products with brand and titles matching the query.

Categories

.findCategory(options)

Returns the specified category.

.categoryTaxonomy(options)

Returns the top level category taxonomy for the specified site. Use maxLevels: -1 to return the entire taxonomy (only as needed).

.findBrandCategories(options)

Returns all categories for the specified brand.

.suggestCategories(options)

Returns categories with titles that substring match the query.

Brands

.findBrands(options)

Returns the brand specified.

.allBrands(options)

Returns all brands for the specified site.

.suggestBrands(options)

Returns all brands with names that substring match the query.

.findCategoryBrands(options)

Returns all brands with at least one product in the specified category.

Suggestions

.suggestAll(options)

Returns suggestions for queries, products, brands, and categories that substring match the query.

Queries

.suggestQueries(options)

Returns suggestions for user search term queries that substring match query.