The Semantics3 API Developer Hub

Welcome to the Semantics3 API developer hub. You'll find comprehensive guides and documentation to help you start working with Semantics3 API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Suggest Edits

About the API

An introduction

 

This document details functionality of v1.0 of the Semantics3 Products API.

Semantics3’s API is designed to be REST-ful; its URLs follow predictable patterns and responses carry appropriate HTTP response codes, among other features that characterize the REST architectural style.

All requests made to the Semantics3 API must be URL encoded.

All responses from this API, including error messages, will be returned in JSON format.

For a video introduction, check out the Quick Start Video below:

This documentation covers requests to the following API resources:

  • Products: Returns product metadata for a given input request.
  • Categories: Returns data about the Semantics3 category tree.
  • Offers: Returns offers (price) history data for input products.
  • Webhooks: Enables push based retrieval of data based on pre-defined trigger conditions.

Each API resource has its own unique request parameters and protocol. To learn more about the construction of request parameters, refer to the resources specific sections of the documentation.

Suggest Edits

Your API Key and Secret

Access credentials for the Semantics3 API

 

Before you write any code, make sure you create your free Semantics3 account to retrieve your API credentials , i.e., your API key and API secret.

Be careful never to publish your API secret key as it uniquely identifies your account and will allow anyone with your API key to gain access to your account. If your API details are compromised, please contact us immediately.

Suggest Edits

API Requests

Components of a valid request

 

API requests are made up of three components:

  • The API Endpoint to which your requests should be directed, e.g., https://api.semantics3.com/v1/ or https://api.semantics3.com/test/v1/
  • An API Resource with which you wish to interact, e.g., products, categories, etc.
  • Query & Filter Parameters that define how you interact with these API resources, e.g., {"search":"apple iphone"}
Suggest Edits

Endpoints

Test and Production

 

You can skip this section if you plan to use one of the Semantics3 API Libraries.

API requests can be directed to one of two endpoints:

a. The Testing/Development Endpoint

https://api.semantics3.com/test/v1/ 

This endpoint allows for quick testing of your requests. It adopts a simplistic authentication protocol and can be directly tested through tools like curl.

This endpoint should not be used in production. Requests to this endpoint are restricted to 150 free API calls/day, regardless of the production paid plan you are on.

Sample curl request:

curl -G -H "api_key: YOUR_API_KEY" https://api.semantics3.com/test/v1/products --data-urlencode 'q={"search":"apple iphone"}'

b. The Production Endpoint

https://api.semantics3.com/v1/

This endpoint is meant for production use. It uses the 1-legged OAuth model, as described in the IETF OAuth 1.0 Protocol RFC 5849, as its authentication mechanism.

If you wish to construct your own OAuth requests, without using our API libraries, we suggest you use one of the popular OAuth client libraries. However, we insist that you use one of our officially supported client libraries.

All API calls that are added to your account upon upgrade to a higher plan are added to the production endpoint, not to the testing/development endpoint.

Suggest Edits

Errors

Recognizing the Semantics3 API response codes

 

Semantics3 uses conventional HTTP status codes to indicate success or failure of API requests. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate a network or server error.

The response text for error conditions typically contains two fields in the supplied JSON response, code and message, which describe in further detail the error that has occurred.

{
  "code": "BadQuery",
  "message": "Insufficient valid query fields."
}

400
Bad Request

JSON request was either of invalid format or was not URL encoded

401
Unauthorized

Failed to authenticate

429
Too Many Requests

API limit exceeded. Possible limit error codes : "APIQuotaLimitError", "APIRateLimitError", "APIEndpointLimitError"

500
Internal Server Error

Server side error

503
Gateway Error

Network error / server side error

Suggest Edits

Resources & Request Parameters

Various resources you can retrieve

 

This documentation covers requests to the following API resources:

  • Products: Returns product metadata for a given input request.
  • Categories: Returns data about the Semantics3 category tree.
  • Offers: Returns offers (price) history data for input products.
  • Webhooks: Enables push based retrieval of data based on pre-defined trigger conditions.

Each API resource has its own unique request parameters and protocol. To learn more about the construction of request parameters, refer to the resources specific sections of the documentation.

Suggest Edits

Playground

Test your queries without writing any code

 

As you learn to use the Semantics3 API, we recommend that you use our handy dashboard playground to construct requests and explore the data.

Semantics3 Playground

Semantics3 Playground

The playground is automatically hooked up to the testing/development endpoint of your account, so you can use this visual interface to construct and test-drive up to a 100 requests a day.

Suggest Edits

About Products Data

 

The e-commerce data returned via the Products resources is constructed by curating and merging data across multiple sources. API responses contain both static fields, i.e., product, brand and color, and site-specific fields, i.e., price, purchase URL and availability.

Disambiguation

Each product response returned from the API represents a unique product. In other words, URLs that represent the same product on different websites will be merged into a single sem3_id entry and the site-specific differences will be encapsulated in the sitedetails array (described in the next section). This merging procedure is performed algorithmically.

Categorization

All products are usually tagged with a category ID. This is an best-effort algorithmic service.

Variations

Product variations are returned as separate entries in the Semantics3 database. For example, if a particular model of shoes is sold in two colors and two sizes, the Semantics3 API will return up to four entries for this model of shoes. For the purpose of grouping, these variations will each be tagged with the same variation_id (described in the next section).

Refresh

The data that you receive from the API is regularly checked against its sources and refreshed. These refreshes are based on a metric called ProductRank (analogous to Google’s PageRank), calculated for each product, which estimates both the importance of a product and the likelihood that its price will change. Products with high ProductRank are updated several times a day, while unimportant products with low price volatility may be updated once every couple of weeks. If you come across a site with outdated prices but which is of critical importance to you, do drop us a note.

Discovery

In addition to refreshing existing data in our system, we also periodically check for new products that have entered the market. Such checks are typically run twice a month.

Sitedetails

All site-specific information is contained within the sitedetails array field in the API response. Each entry in the sitedetails array contains data unique to a particular URL on which the product is or was sold.

Latestoffers

An offer is a snapshot of the price of a product sold on a particular URL (when third-party sellers are involved, this is further nuanced by the condition of the product and seller name). When an offer price changes, the previous offer entry is marked as closed, and a new offer entry is inserted at the top of the latestoffers array. All offers associated with a sitedetails entry are stored in the latestoffers array field linked to that entry.

Suggest Edits

Request Structure

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.semantics3.com/test/v1/products
curl -G -H "api_key: SEM3xxxxxxxxxxxxxxxxxx" \
    https://api.semantics3.com/test/v1/products \
    --data-urlencode 'q={"search": "Samsung Galaxy"}'
{
    "code": "API_REQUEST_RATE_EXCEEDED",
    "message": "Calls to this API have exceeded the rate limit. Please try again in a few minutes"
}
{
    "code": "API_DAILY_QUOTA_EXCEEDED",
    "message": "You have reached your maximum API usage limit!"
}

Query Params

q
string

holds a json payload with query and filter fields. These fields are discussed in detail below

 

The products resource allows you retrieve data about e-commerce products.

Product requests take in three types of parameters:

  • Query fields determine which products from our database are returned to you. Every request must contain at least one query field.
  • Standard Filter fields allow you to narrow the product response set determined by the query fields. Standard filters are optional.
  • Special Filter fields allow you to modify the content of the documents that are returned, reorder these documents and retrieve additional data among others. Special filters are optional.

A typical request has the following form:

GET https://api.semantics3.com/v1/products?q={"MANDATORY_QUERY_FIELD1":"QUERY_VALUE1","OPTIONAL_FILTER_FIELD1":"FILTER_VALUE1"}

To run your own queries using curl, refer to The Testing/Development Endpoint section.

Suggest Edits

Responses

 

The following is a skeleton of a typical product entry obtained from the Semantics3 Products API.

{
   "sem3_id":"<SEM3_ID>",
   "name":"NAME",
   "upc":"<UPC>",
   ......,
   ......,
   "sitedetails":
   [
      {
         "sku":"<SKU>",
         "name":"<NAME>",
         "latestoffers":
         [
            {
               "currency":"<CURRENCY>",
               "id":"<OFFER_ID>",
               "price":"<PRICE>"
            },
            ......,
            ......
         ]
        ......,
  ......
      }
   ]
}

Basic Response Fields

The following table lists all of the fields provided in the first level of the API response, including sem3_id, name and upc shown in the example above.

Response Field Data Type Description
sem3_id String Semantics3 ID of the product. Think of this field as the primary key which uniquely identifies each product in the database. All products will contain a sem3_id.
name String Name of the product. All products will contain a name.
sitedetails Array An array containing all site-specific product information.This field is explained more in detail below.
brand String Brand name of the product.
cat_id String Best estimate category ID of the product. Refer to the “Categories” section for more details.
category String Name of the category with which the product is associated.
color String Color of the product.
created_at Unix Timestamp Time at which this product was inserted into Semantics3’s database.
description String Detailed description of the product.
ean String 13-digit International Article Number (EAN) of the product. International Standard Book Numbers (ISBN) are also displayed against the ean field, since ISBN-13 is a subset of EAN. The “ean” field is included for quick and intuitive reference; we recommend that you utilize the “gtins” field, also described in this table, as far as possible.
features String (Hash) Features of the product, in hash (key-value) form. Values are always in scalar form, except when the key is “blob”; all unstructured features data is stored as a value of the blob key in either array or scalar form.
gtins String (Array) 14-digit Global Trade Item Numbers (GTINs) associated with the product. UPCs (GTIN-12) and EANs (GTIN-13) are subsets of the GTIN-14 system. A product may have multiple UPC/EAN/GTIN IDs associated with it; while the “upc” and “ean” fields display any one of these IDs for quick reference, the GTIN field displays all associated IDs in an array.
geo String Represents the country to which the product is linked. All products sold on USA stored are, for instance, tagged with the “geo” field “usa”.
height Double Approximate height of the product (in millimeters).
images String (Array) Array of URLs pointing to images of the product.
images_total Integer Number of image URLs contained in the images array.
length Double Approximate length of the product (in millimeters).
manufacturer String Manufacturer of the product.
model String Model of the product.
mpn String Manufacturer part number of the product.
price Double We capture several prices for each product, made available in the sitedetails field. You may, however, face the need to attribute a single quick-and-dirty representative price point to each product. This “price” is selected from among all the offers and list prices associated with the product. The currency associated with this field is reflected in the “price_currency”. Note that if you are not on one of our premium plans, the source of the “price” field may not be visible to you, since you will not have access to all sitedetails entries and associated offers.
price_currency String The ISO 4217 currency value associated with the “price” field.
size String Size of the product.
upc String 12-digit Universal Product Code (UPC) code of the product. The “upc” field is included for quick and intuitive reference; we recommend that you utilize the “gtins” field, also described in this table, as far as possible.
updated_at Unix Timestamp Time at which the data in this product response was last refreshed.
variation_id String Often, a product entry may be available in other combinations of color, format, size, etc. If a product returned by the API contains a variation_id field, you can query by this field to retrieve all variations grouped by that variation_id.
variation_secondaryids String (Array) Product entries may be a part of multiple variation groups. While the primary group is identified by the variation_id field, secondary groups are identified by IDs in the variation_secondaryids array. Note that variation_id is not a prerequisite of variation_secondaryids, i.e., a product entry may have variation_secondaryids but no variation_id.
weight Double Approximate weight of the product (In milligrams).
width Double Approximate width of the product (In millimeters).

Sitedetails Fields

All site-specific product information is contained within the “sitedetails” array field. Each entry in the sitedetails array contains data unique to a particular URL on which the product is or was sold. The following table lists all of the fields that can be found in the sitedetails array.

Response Field Data Type Description
listprice Double List price displayed on the site. Typically, e-commerce sites present this value as the reference price against which a marked-down price is contrasted.
listprice_currency String Currency associated with the listprice. Currency codes are returned in ISO 4217 format.
name String Name of the website from which this data was obtained.
recentoffers_count Integer Number of “active” offers recorded when this site was last refreshed. A value of “0″ indicates that the product is no longer available for purchase through that link. This field is almost never needed.
sku String Each sitedetails entry is uniquely identified by its “name”, i.e., its domain name, and its “sku”, i.e., a unique identifier extracted from its URL. If the page that this URL represents has multiple variations associated with it, then the SKU is appended with an underscore and a variation specific identifier.
url String URL pointing to the product page on the referenced site.
latestoffers Array An array of latest offers. This field is explained more in detail below.

Latestoffers Fields

An offer is a snapshot of the price of a product sold on a particular URL (further nuanced by the condition of the product and seller name, when third-party sellers are involved). When an offer price changes, the previous offer entry is marked as closed, and a new offer entry is inserted at the top of the latestoffers array. All offers associated with a sitedetails entry are stored in the latestoffers array field linked to that entry. The latestoffers array contains at most three entries, with the most relevant and recent offer as the first entry. Note that the first entry may point to an offer that is no longer valid; in order to hide discontinued offers, we recommend that you use the activeoffersonly special filter, described in the Special Filter Fields.

Response Field Data Type Description
availability String Status of the offer at the time at which it was recorded (e.g., available, out of stock, etc.).
condition String The condition of the item that is on offer (e.g., new, refurbished, used, etc.). This field is set only if explicitly mentioned in the source of the data; if this field is empty, the product can be assumed to be new.
currency String Currency code associated with the specified price (and shipping price, if present). Currency codes are returned in ISO 4217 format.
id String ID associated with the offer, which is unique in the context of a fixed sitedetails_name and sku.
firstrecorded_at Unix Timestamp Time at which this offer was first recorded.
lastrecorded_at Unix Timestamp Time at which this offer was last recorded. When a product is refreshed and the price is found to be the same, this is the only field that undergoes change, i.e., the lastrecorded_at field is updated to the refresh time.
price Double Price associated with the offer.
seller String Name of the seller who has put up this offer for the product. This field is particularly relevant to sites that offer the products of third-party sellers.
shipping Double Shipping price associated with the offer.

Category-Specific Fields

The following table lists category-specific fields that may be returned in the first level of the API response. Compared to the fields in Table 1, the following fields occur only occasionally.

Response Field Data Type Description
actor String Actor(s) of the movie/TV show.
artist String Arist(s) associated with the referenced product.
author String Author of the book.
department String Department under which the product falls.
director String Director(s) of the movie/TV show.
format String Format in which the product is delivered.
genre String Genre associated with the product.
label String Record (label) associated with the item of music.
language String Language in which the contents of the product are delivered.
operatingsystem String Operating system of the product.
platform String Platform (typically software/hardware) on which the product runs.
producer String Producer(s) of the movie/TV show.
publisher String Publisher of the product.
runningtime String Running time, in minutes, of the movie/TV show.
studio String Studio associated with the movie/TV show.
writer String Writer(s) of the movie/TV show.

All results returned via the SKUs API will contain atleast one active offer. If a once active SKU turns inactive, it will be removed from the SKUs API result set.

Suggest Edits

Query Fields

 

Query fields determine which products from our database are returned to you. Every request must contain at least one query field. Complex queries can be constructed by combining multiple query fields with each other.

Query Field Aliases* Description Sample Request
search[Beta] - Run free-text search with any input string, a la Google search. {“search”:”apple iphone”}
upc gtins, ean Retrieve products by their UPCs / EANs / GTINs. {“upc”:”885909599677”}
sem3_id - Retrieve products by their Semantics3 IDs, up to 10 IDs at a time. {“sem3_id”:” 1xXNQo9RkGkiymkoGegICq”} or {“sem3_id”:[“ 1xXNQo9RkGkiymkoGegICq”,” 3bmDHZ5lxI4IwAOmioWqkM”]}
url - Return products linked to a specific URL. The URL can handle multiple forms of the same URL, typically as long as the URL is not too mangled. {“url”:”abc.com/def”}
site - Return products that have at least one sitedetails entry from the input list of sites, up to 10 sites at a time. Note, this query affects the list of products that are returned to you; to restrict the list of sites shown to you in the sitedetails array of these products, refer to the sitedetails_display filter. {“site”:”abc.com”} or {“site”:[“abc.com”,”def.com”]}
name - Unlike the “search” query, the name query only runs against the product name, and is a logical AND query, i.e., all responses will contain all of the tokens that constitute your query value. This query is only meant for advanced users and is to be used in rare circumstances. If you would like fine-grained control over your result set, you can choose to add exclude and include options to this field and either necessitate the inclusion or force the exclusion of results that contain a specific set of words. {“name”:”iphone”} or {"name":{"include":"LCD","exclude":"stand protector accessory kit"}}
cat_id - Retrieve products by their category IDs, up to 10 IDs at a time. If the cat_id sent in the query includes child categories, then products associated with child cat_ids will also be included in the response. Refer to the categories resource section to learn more about category IDs. {“cat_id”:”13658”} or {“cat_id”:[“13658”,”915”]}
variation_id - Returns all variations that contain either a primary or a secondary variation ID that matches the input string. {“variation_id”:” 5VcVscjfRQoqCGiAIWqGoc”}
  • Keywords listed in the alias field perform the same functionality as their associated query field keywords.
Suggest Edits

Standard Filter Fields

 

Standard Filter fields allow you to further refine the product response set determined by the query fields. Standard filters are optional, i.e., valid requests can be constructed even without standard filters. Filters must be accompanied by at least one valid query field.

Standard Filter Field Permissible Values Description Sample Request
geo “usa” (default), “uk” Identify the country to which you wish to restrict your response results. Data from only one country can be requested at any point in time. The “usa” filter is set by default. {“geo”:”usa”}
price - Filter products by price range. Permissible range keywords include:“lt” -> less than“gt” -> greater than“lte” -> less than or equal to“gte” -> greater than or equal to.Since each product entry might contain multiple prices (across sites and their sellers), the intrinsic price of the product is subject to interpretation. To remedy this problem, we select a single representative price-point using a refined set of rules; the price filter applies to this chosen price. {“price”:{“lt”:”20.49”}} or {“price”:{“gt”:”10.49”}} or {“price”:{“gt”:”10.49, “lt”:”20.49”}}
activeproductsonly “0” (default), “1” When set to “1”, all products with no valid offers are filtered out. By default, this filter is turned off, i.e., set to “0”. {“activeproductsonly”:1}
variation_includeall “0”,“1” (default) Products may have several associated variations, differentiated by fields like color, size etc. Just one model of a shoe (the product) may be available in different size-color combinations (its variations). By default, product API requests return all relevant variations. To restrict your search space to approximately one variation from each group, set this filter to "0""." {“variation_includeall” :0}
limit Integer between 0 and 10 (maximum + default). Restrict the number of products shown in your response. {“limit”:1”}
offset Integer. Default is “0”. Use this field to paginate through your response space. For instance, to return response results 16-25, set offset to 15. You can use this field to retrieve as many as 2000 top results per request. {“offset”:15”}
affiliatepartner [Premium Feature] “twotap” If you wish to use this API in conjunction with services provided by of our partners, set the “affiliatepartner” field to the name of this partner, and we will restrict the response results to data supported by the partner. {“affiliatepartner”: ”twotap”}
Suggest Edits

Special Filter Fields

 

Special Filter fields allow you to modify the content of the documents that are returned, reorder these documents, retrieve additional data, and so on. Special filters are optional. Special filters must be accompanied by at least one valid query field.

Special Filter Field Description Sample Request
activeoffersonly When set to “1”, your product response will only contain those latestoffers entries that are valid. By default, this filter is turned off, i.e., set to “0”. Note that this filter only trims the document provided to you via the API. It does not affect the products returned to you. {“activeoffersonly”:1}
activesitesonly When set to “1”, your product response will only contain those sitedetails entries that have at least one valid offer. By default, this filter is turned off, i.e., set to “0”. Note that this filter only trims the document provided to you via the API. It does not affect the list or order of products returned to you. {“activesitesonly”:1}
fields Restrict API response results to only those fields that interest you, by specifying an array of desired fields. sem3_id and name are included in all responses by default. {“fields”: [“brand”]}
isotime Setting this field to 1 converts all timestamps in your API response to ISO time, i.e., human readable time. This filter is turned off by default. {“isotime”:1}
sitedetails_display If you are interested in only a specific set of sites, you can instruct the API to trim the “sitedetails” array to your specifications. You can choose to either exclude specific sites or include specific sites. Note that this filter only trims the document provided to you via the API. It does not affect the products returned to you - refer to the “site” query for this. {"sitedetails_display": {"include": ["costcentral.com", "appliancesconnection.com"]}} or {"sitedetails_display": {"exclude": ["costcentral.com", "appliancesconnection.com"]}}
sort By default, products in your API response are sorted by relevance and popularity. You can choose to reorder these response results in ascending (“asc”) or descending (“dsc”) order by specific fields. Currently, only "price" sort is supported. {“sort”:{“price”:”asc”}} or {“sort”:{“price”:”dsc”}}
Suggest Edits

Premium Queries and Filters

 

The following premium queries and filters are available only to our enterprise customers. To avail of these features, please contact us.

Affiliate Partner

Premium users who plan to integrate the TwoTap API into their apps can restrict their responses to TwoTap supported sites by adding the following filter to their API requests:

{“affiliatepartner”:”twotap”}
Suggest Edits

Transitioning from Deprecated Queries and Filters

 

You can skip this section if you are not a legacy user of the Semantics3 API.

Queries and filters against some fields have been deprecated and removed from the previous documentation. This list of fields includes all sitedetails and latestoffers queries, dimensions (height, width, length and weight), created_at, updated_at, images_total, all category-independent fields, exclude and include queries against product name, logical and and or operators, description, features, category, model, mpn, brand, manufacturer, color and size. The rationale behind deprecating these fields was that they were adding to the complexity of the API, their functionality could in most cases be replicated by other queries, they were seldom used, and critically, their behavior was often misconstrued by developers.

If you were reliant on queries and filters against these fields, here are some pointers to help you make the transition:

  • sitedetails.name: Queries against sitedetails.name can be substituted by the site query.

  • sitedetails.sku + sitedetails.name: Requests that combine sitedetails.sku and sitedetails.name can be replaced with the url query, i.e., {“url”:”name/sku”}.

  • sitedetails.recentoffers_count: Requests that involve sitedetails.recentoffers_count field can be substituted with the activeproductsonly filter.

  • sitedetails.latestoffers.availability: Queries that check for availability "in stock” or “out of stock” can be replaced with the activeproductsonly filter.

  • sitedetails.latestoffers.price and sitedetails.listprice: Queries against these fields can be substituted with the price filter.

  • brand, manufacturer, model, mpn, color, size, description, features, category and category-independent fields: Requests against any of these text fields are equivalent to running search queries. The search query ensures greater relevance of response results, and returns responses even when the target field does not contain data in structured form.

Currently, the API automatically maps many of the older queries and filters to their newer equivalents, but we recommend that you explicitly restructure your requests as soon as possible to avoid undesirable behavior. Please email us at support@semantics3.com if you need assistance with reformulating any of your requests.

Please note that support for deprecated queries referred to in this section will be removed on the 22nd of February, 2015.

Suggest Edits

About Categories

 

All products in the Semantics3 database are categorized and tagged with a cat_id.

Categorization is achieved through best-effort algorithmic means, therefore it is subject to errors. Hence, we recommend that you use cat_id as a general indicator and not as a driving force for your application.

Categories and their associated cat_id identifiers are laid out in the form of a multi-level category tree, in which each category possesses a parent, a child, or both. A full list of categories can be downloaded here .

On the right is a segment of the tree from the “Electronics” branch. The number provided in brackets is the unique cat_id that identifies the given category name.

In this example, “Electronics” is the highest parent category, categories with an index of “2” are immediate children, categories with an index of “3” are grand children and so on. The greater the confidence level of the categorization algorithm for a given input product, the further down the category tree the product in question will be categorized. Thus, products may lie at any level of the category tree.

To explore the category tree, you could either scroll through a text version of our category tree or run queries against the categories resource as described in the next section.

1.  Electronics (13658)
  2.  Television & Video (399)
  2.  GPS & Navigation (8461)
  2.  Computers & Accessories (4992)
    3.  External Data Storage (10562)
    3.  Desktops (4672)
    3.  External Components (2870)
    3.  Tablets (23042)
    3.  Scanners (14047)
    3.  Webcams (5858)
    3.  Printers (12091)
      4.  Laser Printers (23702)
      4.  Inkjet Printers (12151)
      ...
    ...
  ...
Suggest Edits

Request Queries / Response Fields

 

All requests to the categories resources have the following form:

GET https://api.semantics3.com/v1/categories?q={"QUERY_FIELD":"QUERY_VALUE"}

All fields in responses from the categories endpoint can be queried against. Queries cannot be used in combination with each other, i.e., each request to the categories resource must contain only one query field. The table below lists out all of the fields and queries associated with the categories resource.

Response / Query Field Data Type Description Sample Request
cat_id Integer Category ID of the entry. {“cat_id”:”4992”}
crumb String Entire crumb trail of the category entry. {“crumb”:”computer”}
name String Name of the category. {“name”:”computer”}
parent_cat_id Integer Category ID of the parent of this entry. Query against this field to return all children of a given cat_id. {“parent_cat_id”:”4992”}
parent_name String Name of the parent of this entry. {“parent_name”:”electronics”}
Suggest Edits

About Offers

 

The offers resource is currently in public beta and is still experimental in nature; we appreciate any feedback that you may have at contactus@semantics3.com.

We track and provide offer histories for the products in our database. Each product may contain multiple offer entries, differentiated by change in price over time, name of seller and website on which the product is sold and condition of the product. This data can be used to detect price changes patterns and monitor competitors, among other uses.

The difference between the offers resource and the sitedetails.latestoffers field in the products resource is that the latter contains at most three entries, while the former can be used to retrieve the rest of the offer entries.

Suggest Edits

Request Fields

 

All requests to the offers resource have the following form:

GET https://api.semantics3.com/v1/offers?q={"sem3_id":"SEM3_ID", “FILTER_FIELD1”, “FILTER_VALUE1”}

The list of supported request fields for the offers resource are as follows:

Request Field
Request Type
Description
Sample Request

sem3_id

Query [Required]

All offers resource requests must contain a sem3_id. Thus, in order to obtain the price history of a product, you must first identify its sem3_id from the products resource.

{“sem3_id”: ”7JAykYaFyiYscEmcAwYC64“}

firstrecorded_at

Standard Filter

Filter by time at which the offer was first recorded.

{"firstrecorded_at": {"gte":"1420070400"}}

lastrecorded_at

Standard Filter

Filter by time at which the offer was last recorded.

{"lastrecorded_at": {"lte":"1420060400"}}

sitedetails_name

Standard Filter

Filter the offers history response by a single site name, or an array of sites.

{"sitedetails_name":"abc.com"} or {"sitedetails_name":["abc.com","def.com"]}

offset

Standard Filter

Use this field to paginate through your response space. For instance, to return response results 16-25, set offset to 15.

{“offset”:15”}

limit

Standard Filter

Restrict the number of products shown in your response.

{“limit”:1”}

isotime

Special Filter

Setting this field to 1 converts all timestamps in your API response to ISO time, i.e., human readable time. This filter is turned off by default.

{“isotime”:1}

Suggest Edits

Response Fields

 

Offers responses contain the following fields:

Response Field
Data Type
Description

availability

String

Status of the offer at the time at which it was recorded (e.g., available, out of stock, etc.).

condition

String

The condition of the item that is on offer (e.g., new, refurbished, used, etc.). This field is set only if explicitly mentioned in the source of the data; if this field is empty, the product can be assumed to be new.

currency

String

Currency code associated with the specified price. Currency codes are returned in ISO 4217 format.

id

String

ID associated with the offer, which is unique in the context of a fixed sitedetails_name and sku.

price

Double

Price of the product in the referenced offer. The price field is returned in standard denomination, i.e., all prices in USD are returned in dollars.

firstrecorded_at

Unix Timestamp

Time at which this offer was first recorded.

lastrecorded_at

Unix Timestamp

Time at which this offer was last recorded. When a product is refreshed and the price is found to be the same, this is the only field that undergoes change, i.e., the lastrecorded_at field is updated to the refresh time.

seller

String

Name of the seller who has put up this offer for the product. This field is particularly relevant to sites that offer the products of third-party sellers.

shipping

Double

Shipping price associated with the offer.

sitedetails_name

String

Name of the site on which the offer was detected.

sku

String

Each product is uniquely identified by a domain name and a SKU identifier extracted from its purchase URL. If the page that this URL represents has multiple variations associated with it, the SKU is appended with an underscore and a variation specific identifier.

All offers resource responses are sorted is descending order of the lastrecorded_at field.

To limit your results to just those offers that are active, extract the first "N" offers for each sitedetails_name + sku pair, where "N" is the recentoffers_count value associated with the sitedetails_name + sku pair in the products response.

Suggest Edits

About SKUs Data

 

This resource is currently in public beta

The data returned from the "products" resource is the result of the combination of data from multiple sources, followed by post-processing including disambiguation (i.e., product matching) and categorization. The impetus here is to give you the best data linked to each product.

At times though, you may want to retrieve raw data from our data sources, before it has been processed and merged. The SKUs resource provides raw data on the SKU level as is provided at the source from which this data was extracted.

Here's one way to think about this distinction. Consider a Product X sold on two websites, website A (with SKU XA) and website B (with SKU XB). For this set of information, the products resource would return only one result / sem3_id, the sitedetails array of which would contain two entries, one for each SKU. The data shown for this sem3_id would be the result of merging the data obtained from SKUs XA and XB. For the same set of information, the skus resource would return two results, one for SKU XA and one for SKU XB.

The SKUs resource only returns URLs that are active; if a URL goes dead, or the SKU goes out of stock, the corresponding SKU entry is no longer returned via the SKUs resource.

Suggest Edits

Retrieve SKUs

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.semantics3.com/test/v1/skus
curl --request GET \
  --url https://api.semantics3.com/test/v1/skus
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.semantics3.com/test/v1/skus' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.semantics3.com/test/v1/skus")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.semantics3.com/test/v1/skus",
  "method": "GET",
  "headers": {},
  "processData": false
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
import requests

url = "https://api.semantics3.com/test/v1/skus"

response = requests.request("GET", url)

print(response.text)
{
  "code": "OK",
  "scroll_count": 0,
  "results_count": 10,
  "results": [
    {
      "features": {
        "Swim Bottom Style": "Hipster swim bottom",
        "Lining Material": "100 % Polyester"
      },
      "listprice": "14.99",
      "offers": [
        {
          "currency": "USD",
          "availability": "Available",
          "seller": "target.com",
          "price": "14.00"
        }
      ],
      "variation_id": "16555646",
      "size": "Small",
      "description": "Get your festival ... (visit site URLs for full description)",
      "url": "http://www.target.com/p/women-s-bright-blue-embellished-bikini-bottom-xhilaration/-/A-16555646",
      "sku": "16555646_208017003",
      "name": "Women‘s Bright Blue Embellished Bikini Bottom Xhilaration",
      "crumb": "clothing|women's clothing|juniors|juniors' swimsuits|bottoms",
      "parent_sku": "16555646",
      "created_at": 1427293676,
      "updated_at": 1432281353,
      "site": "target.com",
      "images": [
        "http://scene7.targetimg1.com/is/image/Target/16555646",
      ],
      "geo": [
        "usa"
      ]
    }
  ],
  "next": {
    "page": "c09552fbd537314d2b352e6fb004aa920eb2ec36b2f69d6a81017ec681397d2cf2fc2159e82445b9d2005a3f1200907aac1458c5ebbf99f0415b70722921fab5e292a5f4606abcb9812485af14a286c755f3523f917533c1688dd8da12d1dc91"
  }
}
{
    "code": "API_ENDPOINT_LIMIT_EXCEEDED",
    "message": "You have crossed the limit of 100,000 records for scrolling. Please send an email to contactus@semantics3.com for any enquiries."
}
{
  "code": "INSUFFICIENT_ARGUMENTS",
  "message": "Insufficient valid query fields"
}

Query Params

q
string

Query fields determine which products from our database are returned to you. Every request must contain at least one query field.

 

Note that the SKU records you fetch using this API are always sorted in the descending order of time. In other words, the first SKU record is the most recent data collected from the respective source site.

Suggest Edits

Query Fields

 
Query field
Description
Sample Request

url

Use this field to fetch SKU data for a particular url.

site

Use this field to fetch SKU data records from a particular site.

{"site" : "target.com"}

page

Some responses come with a 'next' and 'prev' page identifiers for scrolling through the results. You can use this field to specify the identifier and navigate to other pages.

{"page" : "<page-identifier>"}

Suggest Edits

Filter Fields

 
Filter field
Description
Sample Request

sku

Use this field to fetch SKU data based on SKU (stock keeping unit) code.
Note that, this field must always be used along with the "site" query field.

{"site": "walmart.com" ,"sku" : "23980026" }

fields

Restrict API response results to only those fields that interest you, by specifying an array of desired fields

{"fields":["sku","updated_at"]}

isotime

Setting this field to 1 converts all timestamps in your API response to ISO time, i.e., human readable time. This filter is turned off by default.

{“isotime”:1}

Suggest Edits

Responses

 

Basic Response Fields

The following table lists all of the fields provided in the first level of the API response:

Response Field
Data Type
Description

sku

String

SKU ( Stock Keeping Unit ) of the product.

name

String

Name of the product. All products will contain a name.

brand

String

Brand name of the product

color

String

Color of the product

created_at

Unix Timestamp

Time at which this product was inserted into Semantics3’s database

description

String

Detailed description of the product

features

String (Hash)

Features of the product, in hash (key-value) form. Values are always in scalar form, except when the key is “blob”; all unstructured features data is stored as a value of the blob key in either array or scalar form

gtins

String (Array)

14-digit Global Trade Item Numbers (GTINs) associated with the product. UPCs (GTIN-12) and EANs (GTIN-13) are subsets of the GTIN-14 system. A product may have multiple UPC/EAN/GTIN IDs associated with it; while the “upc” and “ean” fields display any one of these IDs for quick reference, the GTIN field displays all associated IDs in an array

geo

String

Represents the country to which the product is linked. All products sold on USA stored are, for instance, tagged with the “geo” field “usa”

images

String (Array)

Array of URLs pointing to images of the product

manufacturer

String

Manufacturer of the product

model

String

Model of the product

mpn

String

Manufacturer part number of the product

size

String

Size of the product

updated_at

Unix Timestamp

Time at which the data in this product response was last refreshed

variation_id

String

Often, a product entry may be available in other combinations of color, format, size, etc. If a product returned by the API contains a variation_id field, you can query by this field to retrieve all variations grouped by that variation_id

listprice

Double

List price displayed on the site. Typically, e-commerce sites present this value as the reference price against which a marked-down price is contrasted

listprice_currency

String

Currency associated with the listprice. Currency codes are returned in ISO 4217 format

site

String

Name of the website from which this data was obtained

url

String

URL pointing to the product page on the referenced site

offers

Array

An array of latest offers. This field is explained more in detail below

prev

String

Page identifier for fetching the previous page

next

String

Page indentifier for fetching the next page

Offers Fields

An offer is a snapshot of the price of a product sold on a particular URL. The following table lists all of the fields available in the "offers" array described above.

Response Field
Data Type
Description

availability

String

Status of the offer at the time at which it was recorded (e.g., available, out of stock, etc.)

condition

String

The condition of the item that is on offer (e.g., new, refurbished, used, etc.). This field is set only if explicitly mentioned in the source of the data; if this field is empty, the product can be assumed to be new

currency

String

Currency code associated with the specified price (and shipping price, if present). Currency codes are returned in ISO 4217 format

price

Double

Price associated with the offer

seller

String

Name of the seller who has put up this offer for the product. This field is particularly relevant to sites that offer the products of third-party sellers

shipping

Double

Shipping price associated with the offer

Suggest Edits

Popular Sample Requests

 

Request 1: Get SKU records based on URL

curl -H "api_key : SEM3XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G https://api.semantics3.com/test/v1/skus \
--data-urlencode 'q={"url":"http://www.abercrombie.com/shop/us/womens-sweatpants/a-and-f-skinny-sweatpants-3284069"}'

Request 2: Get SKU records based on SKU

curl -H "api_key : SEM3XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G  https://api.semantics3.com/test/v1/skus \
--data-urlencode 'q={"sku":"13092433", "site":"abercrombie.com"}'

Request 3: Get SKU records based on Site

curl -H "api_key : SEM3XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G  https://api.semantics3.com/test/v1/skus \
--data-urlencode 'q={"site":"abercrombie.com"}'

Results Limit

Note that the maximum number of results that you can paginate through to per query is 100,000 results.

Request 4: Pagination based on Page identifier

The response you receive for the SKU requests may contain page identifiers as shown in the sample response. You can use these to fetch the next and previous page of results.

{
    "code": "OK",
    "scroll_count": 0,
    "results_count": 10,
    "results": [...],
    "next": {
        "page": "<next-page-identifier>"
    },
    "prev": {
        "page": "<prev-page-identifier>"
    }
}
curl -H "api_key : SEM3XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G  https://api.semantics3.com/test/v1/skus \
--data-urlencode 'q={"page":"<page-identifier>"}'
Suggest Edits

About Realtime Data

 

This resource is currently in private beta

Products in the Semantics3 database are updated at a frequency determined by ProductRank, which ensures that products with higher importance and volatility are updated more frequently than products lower down the priority list.

While ProductRank practically works for most use-cases, you may at times wish to retrieve product, price and availability information at real-time, i.e., retrieve raw data as present in the source URL at the time of initiation of your request. The /realtime resource was setup to satisfy this need.

Currently, the only way to query the /realtime resource is by URL, as shown in the following example:

realtime/skus?q={"url":"http://www.abc.com/xyz/"}

When the above GET request is initiated, the HTML of the target URL is retrieved, parsed and presented in structured format to you as a response to your request.

Please contact us to get early access to the /realtime resource.

Suggest Edits

Request Structure

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.semantics3.com/test/v1/realtime/skus
curl -G -H "api_key: YOUR_API_KEY" https://api.semantics3.com/test/v1/realtime/skus --data-urlencode 'q={"url":"http://www.amazon.com/gp/product/B005BFZ5TU"}'
{
  "results": [
    {
      "height": "1230",
      "crumb": "Countertop Microwave Ovens:3741631|Microwave Ovens:289935|Small Appliances:289913|Kitchen & Dining:284507|Categories:1063498|Home & Kitchen:1055398|",
      "offers": [
        {
          "seller": "Amazon.com [ATVPDKIKX0DER]",
          "price": "119.99",
          "condition": "New",
          "availability": "In Stock. & FREE Shipping. Details  [BBX: Buy Box] [FBA: Fulfilled by Amazon]",
          "currency": "USD"
        },
        {
          "shipping": 18.99,
          "seller": "ejpfeifer86 [A3P0M3XNTJMZZH]",
          "price": "100.00",
          "condition": "Used - Very Good",
          "currency": "USD"
        },
      ],
      "manufacturer": "Panasonic",
      "model": "NN-SN651B",
      "name": "Panasonic 1200W 1.2 Cu. Ft Countertop Microwave Oven with Inverter Technology NN-SN651B Black",
      "mpn": "NN-SN651B",
      "upc": "887654951427",
      "brand": "Panasonic",
      "url": "http://www.amazon.com/gp/offer-listing/B005BFZ5TU",
      "width": "2090",
      "length": "1590",
      "features": {
        "Product Dimensions": "15.9 x 20.9 x 12.3 inches ; 25.3 pounds",
        "Shipping Weight": "29 pounds"
      },
      "description": "         1.2-cubic-foot microwave oven with Invert... (visit site URLs for full description)",
      "size": "1.2 cu. ft.",
      "sku": "B005BFZ5TU",
      "color": "Black",
      "weight": "2530",
      "gtins": [
        887654951427,
        132017584683
      ],
      "images": [
        "http://ecx.images-amazon.com/images/I/41tiuM%2BzACL._SX500_.jpg"
      ],
      "geo": [
        "usa"
      ],
      "created_at": 1436783271,
      "updated_at": 1436783271
    }
  ],
  "realtime": true,
  "status": "OK",
  "results_count": 1
}

Query Params

q
string

query string containing the url of the product

 
 

Notifications, or Webhooks, open up opportunities to a whole new breed of applications.

The traditional method of accessing our API is called "polling" - you will be hitting our API at regular intervals to get product information. You might also start hitting our APIs for price changes or product availability changes.

Over time, this method becomes highly inefficient, especially if you are looking at several thousand products and you seem to keep making several thousand calls just to detect changes on a handful of products.

The Notifications system handles this use case perfectly. Instead of you polling us at regular intervals to check for changes, we will notify you when there is a change in any of the products you want us to track.

This mechanism enables you to build more robust software by taking action only when there is a change notification.

Setting up a web hooks receiving system

Setting up a server to receive notifications is different from programming regular web application servers. If you are unfamiliar with setting up a listening server, we suggest the following reading material to get you started.

Links coming soon

Suggest Edits

Managing your Webhooks URI

 

The setting up and management of your registered URI will be via the Semantics3 dashboard.

Registering your Webhook URI

Step 1:

Click on the "Add new URI" button

Click on the "Add new URI" button

Step 2

Type in the URI of the receiver you have setup

Type in the URI of the receiver you have setup

Verifying your Webhook URI

All Webhook URIs have to be verified before they can be used with our Notifications system. Upon registration of your URI, the Semantics3 server will send a GET request to your web hook URI with a verification_code parameter similar to that shown in the following example:

GET http://www.yourdomain.com/webhooks?verification_code="6d495be3454763f76cf5f9405530a352"
6d495be3454763f76cf5f9405530a352

Upon receipt of this request, your server should respond to that request with the verification_code in the body of your response.

Upon successful receipt of the verification_code, your URI will be active and ready for setting up events.

When you get this page, you have successfully registered your URI and verified it

When you get this page, you have successfully registered your URI and verified it

Deleting your URI

Click on the delete button

Click on the delete button

Suggest Edits

Managing Events

 

Setting up your Webhooks URI

Before you register or manage your events, make sure you have already setup and verified your webhook URI.

For more information, jump here.

Registering your Events

Using the API

curl -X POST -H "api_key: SEM312345123451234512345123451234512" -H "Content-Type: application/json" -d '{
	"type": "price.change",
	"url"	:	"http://www.retailer.com/a/AB12345",
	"constraints": {
		"gte": 10,
		"lte": 100
			
	}
}' "https://api.semantics3.com/test/v1/webhooks/events"
{
  "code": "OK",
  "results": {
    "type": "price.change",
    "url": "http://www.retailer.com/a/AB12345",
    "constraints": {
      "gte": 10,
      "lte": 100
    },
    "id": "B1slbfWZx",
    "webhook_id": "SyChYbZZx",
    "webhook_uri": "http://www.yourdomain.com/webhooks",
    "created": 1476705737
  }
}

Required Fields

url

The URL may be any product URL from the web. A product URL is defined as a page that has product information as well as the ability to purchase on the site itself.

type

Events support the following valid values for the field type:

  • price.increase
    If there is an increase in price, the new price within the constraints
  • price.decrease
    If there is a decrease in price, the new price within the constraints
  • price.change
    If there is a change in price, the new price within the constraints
  • status.out_of_stock
    If a product tracked is no longer in stock
  • status.available
    If a previously inactive product is back in stock

constraints

Constraints let you define the price ranges for which you will get notified.

  • gte/gt
    Greater than or equals/greater than
  • lte/lt
    Less than or equals/less than

Using the Dashboard

Alternatively, you may use the dashboard if the number of events you have registered is minimal

Alternatively, you may use the dashboard if the number of events you have registered is minimal

Listing all registered Events

Using the API

Listing events help you look at all the events you have registered. You will be using this to get the IDs of events you would like to delete as well.

curl -X GET -H "api_key: SEM312345123451234512345123451234512"
"https://api.semantics3.com/test/v1/webhooks/events"
{
  "code": "OK",
  "results_count": 1,
  "results": [
    {
      "type": "price.change",
      "url": "http://www.retailer.com/a/AB12345",
      "constraints": {
        "gte": 10,
        "lte": 100
      },
      "id": "H1ZuxMZbg",
      "webhook_id": "AyChYbZYx",
      "webhook_uri": "http://www.yourdomain.com/webhooks",
      "created": 1476705737
    }
  ]
}

Using the Dashboard

Alternatively, you may use the dashboard if the number of events you have registered is minimal

Alternatively, you may use the dashboard if the number of events you have registered is minimal

Receiving an Event

When our system notes a change in the metadata as defined in the events registration, you will get a incoming web hook to the listening server you had setup. The format is defined below.

{  
   "changes":[  
      {  
         "sem3_id":"SEM312345123451234512345123451234512",
         "sku":"AB12345",
         "site":"retailer.com",
         "current_price":"90",
         "url":"http://www.retailer.com/a/AB12345",
         "previous_price":"80"
      }
   ],
   "type":"price.change",
   "event_id":"B1slbfWZx",
   "notification_id":"a1598c5f615a017695202466cfd9600b",
   "webhook_id":"AyChYbZYx"
}

Deleting Events

Using the API

curl -X DELETE -H "api_key: SEM312345123451234512345123451234512"
"https://api.semantics3.com/test/v1/webhooks/events/B1slbfWZx"
{
  "code": "OK",
  "message": "Event deleted successfully",
  "id": "H1ZuxMZbg"
}

Required Fields

id

You will have to append the id to the URL when making the request in the format https://api.semantics3.com/test/v1/webhooks/events/<id>.

You may retrieve the ID by listing all events.

Using the Dashboard

Alternatively, you may use the dashboard if the number of events you have registered is minimal

Alternatively, you may use the dashboard if the number of events you have registered is minimal

Suggest Edits

Frequently Asked Questions

 

How frequently are the products checked for changes?

We continuously check for any changes in products status. We will check all products at least once every 12 hours.

How do I know if my listening server is setup correctly?

We currently do not have an automated method to handle this. If you are unsure, you may drop us a message at support@semantics3.com and we can help you with the verification of your system.

Suggest Edits

Zapier + Webhooks Integration

 

Semantics3 Push Notifications and Zapier Integration

This is a guide to integrating Semantics3 Push Notifications with Zapier to get price
change/drop/increase notifications via your favourite channel (Facebook/Gmail/Twitter).

Once you complete the setup of this one-time Zapier integration, you will be able add more products to track thorough your Semantics3 dashboard

For a detailed demonstration, do check out the demo below:

1. Zapier

Zapier connects Semantics3 Push Notifications with 270+ web services. When you ask us if you can
integrate a webapp with Semantics3 Push Notifications, Zapier allows us to say yes a whole lot more.

Zapier uses triggers/actions to automate work between our Push Notifications and other apps. A trigger is an
event that happens in one app and an action is the event that Zapier automatically performs in
another app.

An easy example? Send me an SMS (action) when there is a price drop of a product in your wish list (trigger). The SMS
is the action that Zapier automatically does for you and the price drop event from Semantics3 Push
Notification is what triggers the action to happen.

2. Available Semantics3 Push Notifications Triggers

Supported Triggers

  • Price change: Price of a particular product changes

  • Price decrease: Price of a particular product decreases

  • Price increase: Price of a particular product increases

Visit this page again soon for whole new range of triggers and possibilities

3. What are the most popular Zaps for Semantics3 Push Notifications

  • If you are a consumer, track when price of a product goes below your max budget

  • If you are ecommerce store owner, track price changes of your competitor and get
    the notification through 270+ services.

4. How do you setup a Semantics3 Push Notifications Zap

4.1 Create a zap

a. Visit semantics3 dashboard

b. Click Add URI button paste the zapier URL there.

c. Click Add Event button of the zapier URL and provide a product URL you wish to track

  • Step 4: Select your action service. Then hit continue.

    Select Action Service

  • Step 5: Create Filters. This step is optional, you could add filters by eventID to get notified only on
    a particular product among all products you have registered with Semantics3 Push Notifications
    system. Hit continue after this.

  • Step 6: Map the Trigger to Action

    This is where you are able to decide what the action will look like. You can type both static
    text as well as dynamic fields from the trigger service by clicking the "Insert Fields" button in
    the right of each field

    Fields inserted from the trigger service show up as little orange pills like so.

    This step depends on the action service that you have chosen. For gmail, typically you could just
    fill the following:

    • To
    • Subject
    • Plain Body

    Hit continue.

  • Step 7: Test this Zap

    This is where you could test if this zap is working. By loading samples, Zapier will pull in the
    most recent trigger items (in our case, a sample Semantics3 Push Notification) and let you test
    the action to see what it looks like.

    Click on Test Semantics3 Price Change Notifications trigger

    Test Semantics3 Price Change Notifications trigger

    In the pop-up dialog, copy the zapier hook URL

    Copy hook URL

    Visit semantics3 webhooks dashboard and
    perform a test trigger. Then come back to the zapier pop-up dialog and click Ok, I did this

    Test Semantics3 Trigger

  • Step 8: Name your zap and Turn On

    The last step is to name your zap and turn it on.

    Thats it, you will start receiving price change notifications of products in your wish list.

    If you want to add more products to track or stop tracking a product, just go back to
    Semantics3 Webhooks Dashboard and add
    or remove the corresponding events.

Suggest Edits

Freshness of Data

 

How often are prices updated?

We use a metric called ProductRank (analogous to Google’s PageRank) for each product, which estimates both the importance of a product and the likelihood that its price will change. Products with high ProductRank are updated several times a day, while unimportant products with low price volatility may be updated once every couple of weeks.

If you’re looking for specific update frequency SLAs for certain sites, do contact us.

How often are new products added?

Our database is rapidly growing and new products are added every single day.

Suggest Edits

Understanding the API

 

I ran a "site" search but the results included results from several other sites. Why so?

The site search (e.g. {"site":"xyz.com"}) ensures that all the products returned in the API results have atleast one sitedetails URL from the queried sites. To trim the document, you need to use the sitedetails_display filter.

Do I have to pay to get started? I want to test the API before I start paying.

Nope, just sign-up for our no strings attached risk-free trial.

Some of the prices I see are not up to date. Having up-to-date prices is critical for me.

The latestoffers array includes not only current prices but also historical prices. Use the activeoffersonly filters to get rid of historical prices.

I’m having trouble integrating the API into my code.

We’ve built libraries for several popular programming languages, including Python, Objective C, Ruby, Perl, PHP, Java, Node.js and others.

If you’re still having trouble, let us know and we’ll be glad to help.

What’s the difference between a “upc”, “ean” and “gtins” query?

All three query types are now identical. You can use them interchangeably.

Do you distinguish between “new” and “refurbished” products?

This distinction is fleshed out at the offer level, not the product level. In other words, if Site A were to sell a "new" version of a product and Site B were to sell a "refurbished" version, we'd create only one sem3_id and push the individual sites in at the sitedetails level.

Do URLs need to be canonicalized in order to get results?

The URLs that you provide to the API need not be canonicalized as long as they are not too mangled, i.e., attached session IDs, tracking codes and other parameters are no trouble.

We tackle this problem by resolving every URL into two parts:

  • A domain name.
  • A SKU (stock-keeping unit).

While extracting the domain name is trivial, identifying a SKU is quite a challenge. For example, consider the URL http://www.costcentral.com/proddetail/Apple_MacBook_Pro_with_Retina_display/MD212LLA/11804567.

The domain name here is evidently “costcentral.com“, but the SKU could be
“Apple_MacBook_Pro_with_Retina_display“, “MD212LLA“, or “11804567“.

In this case, the correct SKU would be “11804567”. This is because while these permutations of the link under consideration point to the same target page:

http://www.costcentral.com/proddetail/Apple_iPhone_5/MD212LLA/11804567

http://www.costcentral.com/proddetail/Apple_MacBook_Pro_with_Retina_display/MD212XXX/11804567

but this does not:

http://www.costcentral.com/proddetail/Apple_MacBook_Pro_with_Retina_display/MD212LLA/11804568

Our system is capable of understanding these nuances of e-commerce links.

Can I retrieve more than 10 products at at time?

The maximum permissible value for the limit filter is 10, so you cannot retrieve more than 10 product results. This is to preserve the latency of the API.

What is the coverage of products for webhooks?

All products availably via the products resource are available through the webhooks resource.

Can I control the frequency of update of URLs for webhooks?

URLs against which webhooks are registered are crawled more frequently than the rest of the URLs in our database. If you'd like a URL crawled more frequently, simply register a webhook event against it. That said, we don't provide any frequency SLAs via our packaged plans. To learn more about SLAs, contact us.

How frequently can I expect webhooks notifications?

Aside from the frequency at which URLs are recrawled by Semantics3, the notification frequency depends on the behavior of the product on which your webhooks are registered. This in turn depends on seasonal variations, pricing strategies of your target retailers, popularity of your target products and more. Therefore, we suggest that you do not make any assumptions over frequency of notifications while building your application.

Can I register webhook events by URL rather than sem3_id?

This feature is coming soon.

Suggest Edits

Availability of Data

 

Where do you get your data from?

We extract data from leading online retailers like the IR500 list of top retailers. Extracted data is cleaned, organized and standardized across the database. Identical products from different sites are matched up and the various data points merged to create a unique, product-centric database.

Do you have UK/German/Indian/Australian merchant data?

Currently, we carry data only from US and UK retailers. To view data from UK retailers, drop the following tag into your API queries: {"geo":"uk"}. By default, all API queries return US retailer data.

I can’t find the products / merchants / domains / UPCs that I’m looking for. What do I do?

While this rarely happens, we can often fix this by actively gathering data from new additional sources. Contact us with details and we’ll help you out.
Note that for missing UPCs, the fault may lie in the input UPC number that you're using. Make sure that your UPC inputs both satisfy check digit requirements and are not local UPC numbers.

Why are some fields missing in some results?

We return fields like brand and color only if explicitly available in structured form in the source website.

Why does the name on the product URL differ from the name shown in your DB?

We return canonicalized data built from a combination of our data sources, hence the fields shown will differ from those shown at source.

Why do I see so few results in the Demo plan?

Our Demo plan is designed to allow you to test out our API with limited data to ensure that you can integrate our API easily in your applications. For production uses, we recommend the Start-up or Growth plans as these offer full access to our database.

Do you cover in-store prices?

We only gather prices from e-commerce stores. We currently don’t gather in-store prices.

Which categories of products do you cover?

We cover practically every category of products that you may conceive of purchasing online. We currently handle over 15,000 different categories.
We do not cover niche categories such as cars.

Suggest Edits

Monetization

Affiliate marketing strategies

 

How can I generate affiliate revenue from the Semantics3 API?

You can monetize our product database by utilizing affiliate networks. We offer frequently updated product feeds via our API, all of which come with complete product data, including URLs. These feeds can be more accurate than affiliate feeds, which depend on retailers providing updates (which go through multiple levels before reaching you). Since we extract our data directly from, and independently of retailers, we offer much more breadth and freshness.

You can modify these URLs by adding your affiliate ID to the URLs and adding these URLs into your webstore to instantly monetize your storefront. This is an excellent way to sell through your storefront without handling physical goods or breaking your app or store environment.

Alternatively, you can work with one of our integrated affiliate partners, TwoTap. You can send URLs extracted from the Semantics3 API to the TwoTap API, which will add an affiliate cookie to your link and subsequently take your users to the retailer's website where he or she can place a purchase order. If your user does make the purchase, you will receive revenue directly from the affiliate network. TwoTap has a stats backend where you can see all the purchases that successfully went through.

Two Tap API keys can be instantly generated by Semantics3 app developers directly in the dashboard. A new section is available under the Applications section that can release a Two Tap API key at the click of a button.

Here is a complete example showing how to purchase a product returned from the Semantics3 API with the Two Tap API. All in under 50 lines!

# A rails controller method that opens
# the Two Tap Checkout interface with a product from Abercrombie.
 
require 'semantics3'
 
# Open a popup or an iframe pointing to this action.
# It will pick a random product and redirect to the
# checkout interface.
def buy_abercrombie_product
  ##
  ## Semantics
  ##
 
  SEM_API_KEY = '#'
  SEM_API_SECRET = '#'
 
  # Set up a client to talk to the Semantics3 API
  sem3 = Semantics3::Products.new(SEM_API_KEY, SEM_API_SECRET)
 
  # Search through the abercrombie catalogue and pick one random product.
  sem3.products_field('site', 'abercrombie.com')
  sem3.products_field('sitedetails_display', 'abercrombie.com')
  products = sem3.get_products
  a_product = products['results'][0]
 
  ##
  ## Two Tap  
  ##
 
  # Using our public token we can start a checkout interface.
  TT_PUBLIC_TOKEN = '#'
  twotap_checkout_url = "https://checkout.twotap.com/?public_token#{TT_PUBLIC_TOKEN}&unique_token=#{rand(99999)}&callback_url=http://MY_SERVER/my_confirm_callback&product=" + a_product['url']
 
  redirect_to twotap_checkout_url
end
 
# This is called when the user presses confirm order.
def my_confirm_callback
  if params[:purchase_id].blank?
    render :nothing => true
    return
  end
 
  # Check that order is valid
  #
  # ....
  #
 
  api_call = "https://api.twotap.com/v1.0/purchase_confirm?private_token=#{TT_PRIVATE_TOKEN}"
 
  response = HTTParty.post(api_call, :body => 
    { :purchase_id => params[:purchase_id], :test_mode => params[:test_mode] }
  )
 
  render :json => response.body
end
Suggest Edits

HTTP Status Codes

 

Traditional HTTP status codes are used to indicate success / failure of the API request.

Code
Status

200

OK

204

No Content

400

Bad Request

401

Unauthorized

404

Not Found

500, 502, 503, 504

Server Errors