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!

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results
Suggest Edits

Introduction

 

Our APIs are designed to be REST-ful; URLs follow predictable patterns and responses carry appropriate HTTP response codes, among other features that characterize the REST architectural style.

All requests made must be URL encoded. All responses, including error messages, will be returned in the JSON format.

Suggest Edits

Authentication

 

Before you write any code, create a Semantics3 account to get 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.

We use the 1-legged OAuth model, as described in the IETF OAuth 1.0 Protocol RFC 5849, as the authentication mechanism for our APIs.

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.

We use 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 or sent in an invalid/unrecognizable format), and codes in the 5xx range indicate a server error.

400 Bad Request

Input JSON payload was either of an invalid format or was not URL encoded

401 Unauthorized

Authentication Failure.

429 Too Many Requests

API rate limit exceeded

5xx

Server-side errors

The response JSON payload for failed requests typically contains two fields: a numeric code and a message that provides additional information about the failure:

{
  "code": 8002,
  "message": "The given upc is invalid"
}
Suggest Edits

Playground

 

As you learn to use our APIs, we recommend that you use our handy Playground to construct requests and explore the data from within your Dashboard.

The Ecommerce data returned via the Match&Merged API 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 (cat_id). This is a 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 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.

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

/products

 
gethttps://api.semantics3.com/v1/products
import com.semantics3.api.Products;

Products products = new Products(
	"SEM3xxxxxxxxxxxxxxxxxxxxxx",
	"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
);

products.productsField( "search", "iphone" );

JSONObject results = products.getProducts();

System.out.println(results);
var api_key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
var api_secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
var sem3 = require('semantics3-node')(api_key,api_secret);

sem3.products.products_field( "search", "iphone" );

sem3.products.get_products(
   function(err, products) {
      if (err) {
         console.log("Couldn't execute request: get_products");
         return;
      }
      console.log( "Results of request:\n" + JSON.stringify( products ) );
   }
);
<?php

require('lib/Semantics3.php');

$key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
$secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

$requestor = new Semantics3_Products($key, $secret);

$requestor->products_field( "search", "iphone" );

$results = $requestor->get_products();

echo $results;
from semantics3 import Products

sem3 = Products(
	api_key = "SEM3xxxxxxxxxxxxxxxxxxxxxx",
	api_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

sem3.products_field("search", "iphone")

results = sem3.get_products()

print results
require 'semantics3'

API_KEY = 'SEM3xxxxxxxxxxxxxxxxxxxxxx'
API_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

sem3 = Semantics3::Products.new(API_KEY, API_SECRET)
sem3.products_field( "search", "iphone" )

productsHash = sem3.get_products()

puts productsHash.to_json
using Semantics3;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace MyApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Products products = new Products("APIKEY", "APISECRET");
            products.products_field( "search", "iphone" );
            JObject hashProducts = products.get_products();
            Console.Write(hashProducts.ToString());
        }
    }
}
A binary file was returned

You couldn't be authenticated

{
  "code":"OK",
  "offset":0,
  "results_count":1,
  "results":[
    {
      "size":"128 GB",
      "gtins":[
        "00885909971299"
      ],
      "sem3_id":"4AhyWrP65Qc6yQoCoCO44M",
      "color":"Silver",
      "cat_id":"9359",
      "width":"77.72",
      "length":"157.99",
      "height":"7.11",
      "price_currency":"USD",
      "variation_id":"1vgcfi1Gngyk8GUk4OE8E4",
      "brand":"Apple",
      "upc":"885909971299",
      "price":"614.69",
      "model":"iPhone 6 Plus",
      "created_at":1413454010,
      "name":"Apple iPhone 6 Plus, Silver, 128 GB (AT&T)",
      "mpn":"MGAQ2LL/A",
      "messages":[

      ],
      "geo":[
        "usa"
      ],
      "manufacturer":"Apple",
      "ean":"0885909971299",
      "updated_at":1497564924,
      "images":[
        "http://sem3-idn.s3-website-us-east-1.amazonaws.com/286f51f6be0ddab6862339a6941fe9b6,0.jpg"
      ],
      "weight":"172365.10",
      "sitedetails":[
        {
          "recentoffers_count":3,
          "name":"amazon.com",
          "url":"http://www.amazon.com/dp/B00NK6JCAK",
          "sku":"B00NK6JCAK",
          "latestoffers":[
            {
              "price":"614.69",
              "lastrecorded_at":1497564900,
              "isactive":1,
              "currency":"USD",
              "firstrecorded_at":1497564900,
              "id":"0gkClFcDdeQUQuWEKuGUG6",
              "condition":"new",
              "availability":"Fulfillment by Amazon",
              "seller":"Mobile XpertZ [AI9509PI3M8K5]"
            },
            {
              "price":"749.11",
              "lastrecorded_at":1497564900,
              "isactive":1,
              "currency":"USD",
              "firstrecorded_at":1497564900,
              "id":"0K9CBKR9lcegCIcGicWW6A",
              "condition":"new",
              "availability":"Available [FPO: Front Page Offer]",
              "seller":"MASTERTRONICS (LIGHTNING FAST SERVICE & SHIPPING)"
            },
            {
              "price":"749.11",
              "lastrecorded_at":1497564900,
              "isactive":1,
              "currency":"USD",
              "firstrecorded_at":1497564900,
              "id":"2N9XjnvlcKMOMcYsUgo4gC",
              "condition":"new",
              "availability":"Available [FPO: Front Page Offer]",
              "seller":"MASTERTRONICS (LIGHTNING FAST SERVICE & SHIPPING) [A19N59FKNWHX7C]"
            }
          ]
        }
      ],
      "crumb":"Unlocked Phones|Mobile Phones",
      "description":"Color:Silver | Size:128 GB. Display . Retina HD display 1920-by-1080-pixel resolution at 401 ppi1300:1 contrast ratio (typical)...",
      "features":{
        "Standby Time":"up to 390 hours",
        "Talk Time":"Up to 24 Hours",
        "Battery Cell Type":"lithium ion",
        "Assembly Details":"no assembly required",
        "Not Included":"Service Plan, Data Plan",
        "Includes":"Lightning-to-USB cable, Earphones",
        "Maximum Resolution":"1920 x 1080",
        "Phone Type":"Smartphone",
        "Operating System":"iOS 8",
        "Wireless Technology":"GSM",
        "Video Resolution":"720p",
        "Screen Size":"5.500",
        "Wired Connectivity":"USB",
        "Service Provider":"AT&T",
        "blob":"1080p HD video recording (30 fps or 60 fps); 5.5-inch (diagonal) LED-backlit widescreen Multi-Touch display with IPS technology; 8-megapixel iSight® camera with Optical Image Stabilization; A8 chip with 64-bit architecture. M8 motion coprocessor; Apple Pay: Pay with your iPhone using Touch ID in stores and in apps",
        "Megapixels":"8.000"
      },
      "images_total":11,
      "category":"Unlocked Phones"
    }
  ],
  "total_results_count":100000
}

Query Params

q
string

JSON payload containing query and filter fields. These fields are discussed in detail below

 

The Match&Merged API allows you retrieve data about Ecommerce 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.
 

The following is a skeleton of a typical product entry obtained from the Match&Merged 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

Integer

Unix timestamp 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

Object

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

Array<String>

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

Array<String>

Array of URLs pointing to images of the product.

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 field.

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

Integer

Unix timestamp 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

Array<String>

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).

Site-specific 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, Ecommerce 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

Domain of the website from which this data was obtained.

recentoffers_count

String

Number of active offers observed for this SKU as of the last refresh

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.

Offer 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.).

isactive

Boolean

Indicates whether the offer was active at the time at which it was recorded

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

Integer

Unix timestamp at which this offer was first recorded.

lastrecorded_at

Integer

Unix timestamp 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.

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
Description
Sample Request

search (Beta)

Run free-text search with any input string, a la Google search.

upc or gtins or ean

Retrieve products by their UPCs / EANs / GTINs.

sem3_id

Retrieve products by their Semantics3 IDs, up to 10 IDs at a time.

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.

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.

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 section to learn more about category IDs.

variation_id

Returns all variations that contain either a primary or a secondary variation ID that matches the input string.

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.

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
Description
Sample Request

geo

Identifies the country to which you wish to restrict your response results. Data from only one country can be requested at any point in time. It is set to usa by default. It can be one of usa or uk.

price

Filter products by a price range. Any of the following operators may be used: lt, lte, gt, gte to indicate a price range. 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.

activeproductsonly

Defaults to 0. 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.

variation_includeall

Defaults to 1. 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, all relevant variations are returned. To restrict your search space to approximately one variation from each group, set this filter to 0.

limit

Defaults to 10. Can be an integer between 0 and 10. Restrict the number of products shown in your response.

offset

Defaults to 0. Use this field to paginate through the 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.

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
Data Type
Description
Sample Request

activeoffersonly

Integer

Defaults to 0. When set to 1, each product in the response will only contain those offers that are deemed active.

activesitesonly

Integer

Defaults to 0. When set to 1, each product in the response will only include those sites that have at least one valid offer.

fields

Array<String>

Restrict API response results to only those product fields that you care about. sem3_id and name are included in all responses by default.

isotime

Integer

Defaults to 0. Setting this field to 1 converts all timestamps in your API response to ISO time, i.e., human readable time.

sitedetails_display

Object

If you are interested in only a specific set of sites, you can instruct the API to trim the sitedetails array according to your specifications. You can choose to either exclude or include specific sites.

sort

Object

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.

Suggest Edits

Premium Filter Fields

 

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

Premium Filter Field
Data Type
Supported Value
Sample Request

affiliatepartner

String

Supported value: twotap. Restrict responses to TwoTap supported sites.

This API is currently in Public Beta.

The data returned by the Match&Merged API 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. This API provides raw data on the SKU level as is provided at the source website 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 Match&Merged API would return only one result, 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.
  • the Raw Data API would return two results, one for SKU XA and one for SKU XB.

The Raw Data API only returns products that are active; if a URL goes dead, or the SKU goes out of stock, the corresponding SKU entry is no longer returned.

gethttps://api.semantics3.com/v1/skus
var api_key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
var api_secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
var sem3 = require('semantics3-node')(api_key,api_secret);

var endpoint = "skus";
var method = "GET";
var jsonStr = '{"site" : "walmart.com"}';

sem3.run_query(endpoint, jsonStr, method, function(err, result) {
    if (err) {
      console.error("Couldn't execute query");
      console.error(err);
      return;
    }
    var res = JSON.parse(result);
});
import com.semantics3.api.Products;

Products products = new Products(
  "SEM3xxxxxxxxxxxxxxxxxxxxxx",
  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
);

String endpoint = "skus";
Semantics3Request request = new Semantics3Request(apiKey, apiSecret, endpoint);
HashMap<String, Object> params = new HashMap<String, Object>();
params.site = 'walmart.com';
JSONObject results = request.runQuery(endpoint, "GET", params);
from semantics3 import Products

sem3 = Products(
  api_key = "SEM3xxxxxxxxxxxxxxxxxxxxxx",
  api_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

params = {
  site: "walmart.com"
}

res = sem3.run_query("skus", "GET", params)
require 'semantics3'

API_KEY = 'SEM3xxxxxxxxxxxxxxxxxxxxxx'
API_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

sem3 = Semantics3::Products.new(API_KEY, API_SECRET)

params = {
  "site" => "walmart.com"
}

res = sem3.run_query("skus", "GET", params)
<?php

require('lib/Semantics3.php');

$key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
$secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

$requestor = new Semantics3_Products($key, $secret);
$params = array(
    "site" => "walmart.com"
);
$results = $requestor->run_query('skus', $params, "GET");
using Semantics3;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace MyApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Products products = new Products("APIKEY", "APISECRET");
            JObject params = new JObject();
            params['site'] = 'walmart.com';
            JObject hashResponse = products.run_query('skus', params);
            Console.Write(hashResponse.ToString());
        }
    }
}
A binary file was returned

You couldn't be authenticated

{
  "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"
  }
}

Query Params

q
string

JSON payload containing query and filter fields. These fields are discussed in detail below

 
 

Basic Response Fields

Note

The presence of the following fields in the response from the Raw Data API is subject to the value for that field being available in the source site. In addition to the fields listed below, we also capture various other site-exclusive fields. If you need additional information from a given site for your use-case, talk to us.

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. Unique identifier of a product within the site.

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

Integer

Unix timestamp at which this product was indexed

description

String

Detailed description of the product

features

Object

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

Array<String>

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

Array<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

Array<String>

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

Integer

Unix Timestamp 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 list price. 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<Object>

A list of offers. Offer-specific fields are listed in the section below.

prev

String

Page identifier for the previous page. This value needs to be sent along with the page filter to fetch the previous page of results matching the query.

next

String

Page identifier for the next page. This value needs to be sent along with the page filter to fetch the next page of results matching the query.

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 mentioned 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

Query Fields

 

Note

When you make a site query, products with information refreshed most recently will show up first. Armed with the page filter you can scroll and fetch more products.

Query field
Description
Sample Request

url

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

site

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

sku

Use this field along with the site field to fetch raw data based on the SKU (stock keeping unit) code.

Suggest Edits

Filter Fields

 
Filter field
Description
Sample Request

page

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

fields

Restrict API response results to only those product fields that you care about.

isotime

Defaults to 0. Setting this field to 1 converts all timestamps in your API response to ISO time, i.e., human readable time.

The RealTime API allows you to fetch product, price, and availability information as present in a product URL in a structured format in real-time.

This API is currently in Private Beta. If you'd like to try it out, speak to your Customer Success Manager to get access.

Suggest Edits

/realtime/skus

 
gethttps://api.semantics3.com/v1/realtime/skus
var api_key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
var api_secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
var sem3 = require('semantics3-node')(api_key,api_secret);

var endpoint = "realtime/skus";
var method = "GET";
var jsonStr = '{"url" : "https://www.walmart.com/ip/FRAM-Motorcycle-Oil-Filter-PH6018-02/16817233"}';

sem3.run_query(endpoint, jsonStr, method, function(err, result) {
    if (err) {
      console.error("Couldn't execute query");
      console.error(err);
      return;
    }
    var res = JSON.parse(result);
});
import com.semantics3.api.Products;

Products products = new Products(
  "SEM3xxxxxxxxxxxxxxxxxxxxxx",
  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
);

String endpoint = "realtime/skus";
Semantics3Request request = new Semantics3Request(apiKey, apiSecret, endpoint);
HashMap<String, Object> params = new HashMap<String, Object>();
params.url = 'https://www.walmart.com/ip/FRAM-Motorcycle-Oil-Filter-PH6018-02/16817233';
JSONObject results = request.runQuery(endpoint, "GET", params);
require 'semantics3'

API_KEY = 'SEM3xxxxxxxxxxxxxxxxxxxxxx'
API_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

sem3 = Semantics3::Products.new(API_KEY, API_SECRET)

params = {
  "url" => "https://www.walmart.com/ip/FRAM-Motorcycle-Oil-Filter-PH6018-02/16817233"
}

res = sem3.run_query("realtime/skus", "GET", params)
from semantics3 import Products

sem3 = Products(
  api_key = "SEM3xxxxxxxxxxxxxxxxxxxxxx",
  api_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

params = {
  url: "https://www.walmart.com/ip/FRAM-Motorcycle-Oil-Filter-PH6018-02/16817233"
}

res = sem3.run_query("realtime/skus", "GET", params)
<?php

require('lib/Semantics3.php');

$key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
$secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

$requestor = new Semantics3_Products($key, $secret);
$params = array(
    "url" => "https://www.walmart.com/ip/FRAM-Motorcycle-Oil-Filter-PH6018-02/16817233"
);
$results = $requestor->run_query('realtime/skus', $params, "GET");
using Semantics3;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace MyApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Products products = new Products("APIKEY", "APISECRET");
            JObject params = new JObject();
            params['url'] = 'https://www.walmart.com/ip/FRAM-Motorcycle-Oil-Filter-PH6018-02/16817233';
            JObject hashResponse = products.run_query('realtime/skus', params);
            Console.Write(hashResponse.ToString());
        }
    }
}
A binary file was returned

You couldn't be authenticated

{
  "code": "OK",
  "results_count": 1,
  "results": [{
    "features_highlights": ["Fits specific motorcycle, ATV, snowmobile and powersports vehicles", "Keeps the engine oil clean", "Maintains optimal flow levels"],
    "gtins": [9100382122],
    "siterating": "4.5",
    "variation_id": "16817233",
    "brand": "FRAM",
    "upc": "9100382122",
    "model": "PH6018",
    "created_at": 1498582441,
    "name": "FRAM Motorcycle Oil Filter, PH6018",
    "mpn": "FPH6018WM",
    "reviews_number": "31",
    "url": "https://www.walmart.com/ip/16817233",
    "geo": ["usa"],
    "manufacturer": "FRAM Group Operations LLC",
    "offers": [{
      "seller": "Walmart",
      "availability": "Available",
      "price": "5.91",
      "currency": "USD",
      "lastrecorded_at": 1498582441,
      "isactive": 1
    }, {
      "currency": "USD",
      "price": "19.43",
      "seller": "PartsHawk",
      "availability": "Available",
      "lastrecorded_at": 1498582441,
      "isactive": 1
    }],
    "updated_at": 1498582441,
    "images": ["https://i5.walmartimages.com/asr/b11f58e3-b204-49e4-a59d-6242971c76c9_1.f17114eeeb1efe2b15cb3cc8a80f6ad0.jpeg", "https://i5.walmartimages.com/asr/a8e74d04-98a3-40c9-8019-9c9b9216d190_1.64c9c1a3d6099bac2ba31099c2a31ec9.jpeg", "https://i5.walmartimages.com/asr/b11f58e3-b204-49e4-a59d-6242971c76c9_1.f17114eeeb1efe2b15cb3cc8a80f6ad0.jpeg", "https://i5.walmartimages.com/asr/db3d0e1e-42f5-4bc9-836e-911da3ee712a_1.e42e8d58c82a47568b904f7a2e487417.jpeg"],
    "sitedetails": [{
      "name": "walmart.com",
      "sku": "16817233",
      "recentoffers_count": 2,
      "latestoffers": [{
        "seller": "Walmart",
        "availability": "Available",
        "price": "5.91",
        "currency": "USD",
        "lastrecorded_at": 1498582441,
        "isactive": 1
      }, {
        "currency": "USD",
        "price": "19.43",
        "seller": "PartsHawk",
        "availability": "Available",
        "lastrecorded_at": 1498582441,
        "isactive": 1
      }],
      "url": "https://www.walmart.com/ip/16817233"
    }],
    "crumb": "Auto & TiresAutomotive Replacement PartsAuto FiltersOil Filters",
    "description": "FRAM Motorcycle Oil Filters are specifically designed for flow rates consistent with OE requirements. The filtering media keeps the engine oil clean while maintaining optimal flow levels and the high-quality materials and construction keep your bike running at its best.",
    "features": {
      "Brand": "FRAM",
      "Manufacturer Part Number": "FPH6018WM",
      "Assembled Product Weight": "0.408 lb"
    },
    "sku": "16817233"
  }]
}

Query Params

q
string

JSON payload containing query and filter fields. These fields are discussed in detail below

 
Suggest Edits

Query Fields

 

All requests to the RealTime URL API must include the url field.

Query Field
Data Type
Description

url

String

Product URL from an Ecommerce store. This is the URL from which you want to fetch raw data from in real-time.

 

The response from the RealTime URL API will be similar to that from the Raw Data API.

This API is currently in Public Beta.

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

The difference between the Offers API and the sitedetails[].latestoffers field in the Match&Merged API is that the latter contains at most three entries, while the former can be used to retrieve the rest of the offers.

 
gethttps://api.semantics3.com/v1/offers
var api_key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
var api_secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
var sem3 = require('semantics3-node')(api_key,api_secret);

sem3.products.offers_field( "sem3_id", "7JAykYaFyiYscEmcAwYC64" );

sem3.products.get_offers(
   function(err, offers) {
      if (err) {
         console.log("Couldn't execute request: get_offers");
         return;
      }
    console.log( "Results of request:\n" + JSON.stringify( offers ) );
   }
);
import com.semantics3.api.Products;

Products products = new Products(
	"SEM3xxxxxxxxxxxxxxxxxxxxxx",
	"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
);

products.offersField( "search", "7JAykYaFyiYscEmcAwYC64" );

JSONObject results = products.getOffers();

System.out.println(results);
require 'semantics3'

API_KEY = 'SEM3xxxxxxxxxxxxxxxxxxxxxx'
API_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

sem3 = Semantics3::Products.new(API_KEY,API_SECRET)

sem3.offers_field( "sem3_id", "7JAykYaFyiYscEmcAwYC64" )

productsHash = sem3.get_offers()

puts productsHash.to_json
from semantics3 import Products

sem3 = Products(
	api_key = "SEM3xxxxxxxxxxxxxxxxxxxxxx",
	api_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

sem3.offers_field("sem3_id", "7JAykYaFyiYscEmcAwYC64")

offers = sem3.get_offers()

print offers
using Semantics3;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace MyApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Products products = new Products("APIKEY", "APISECRET");
            products.offers_field( "sem3_id", "7JAykYaFyiYscEmcAwYC64" );
            JObject hashOffers = products.get_offers();
            Console.Write(hashOffers.ToString());
        }
    }
}
<?php

require('lib/Semantics3.php');

$key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
$secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

$requestor = new Semantics3_Products($key, $secret);

$requestor->offers_field( "sem3_id", "7JAykYaFyiYscEmcAwYC64" );

$results = $requestor->get_offers();

echo $results;
A binary file was returned

You couldn't be authenticated

{
  "code": "OK",
  "offset": 0,
  "results_count": 3,
  "results": [{
    "price": "168.88",
    "lastrecorded_at": 1498568100,
    "shipping": "599",
    "sitedetails_name": "amazon.com",
    "currency": "usd",
    "firstrecorded_at": 1498053500,
    "id": "4Kd2Nodp3ggUuw6gGuqUIE",
    "condition": "new",
    "availability": "Available",
    "sku": "B00J8DL78O",
    "seller": "ProElectroMart"
  }, {
    "price": "174.88",
    "lastrecorded_at": 1498568100,
    "sitedetails_name": "amazon.com",
    "currency": "usd",
    "firstrecorded_at": 1497317500,
    "id": "2l6tkieYvAyyC4246ogyKw",
    "condition": "new",
    "availability": "Available [FPO: Front Page Offer]",
    "sku": "B00J8DL78O",
    "seller": "iToyExpress"
  }, {
    "price": "179.99",
    "lastrecorded_at": 1498568100,
    "sitedetails_name": "amazon.com",
    "currency": "usd",
    "firstrecorded_at": 1497880900,
    "id": "0HK8Jy9nKLIgkKqme0q44e",
    "condition": "new",
    "availability": "Fulfillment by Amazon",
    "sku": "B00J8DL78O",
    "seller": "AME for Service"
  }],
  "total_results_count": "1371"
}

Query Params

q
string

JSON payload containing query and filter fields. These fields are discussed in detail below

 
 

Offers responses contain the following fields:

Note:

Recently recorded offers show up first in the response from the Offers API.

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 sitedetails_name and a SKU. If the product page has multiple variations associated with it, the SKU is appended with an underscore and a variation specific identifier.

Suggest Edits

Query Fields

 

The list of supported query fields for the Offers API are as follows:

Request Field
Description
Sample Request

sem3_id

All requests to the Offers API 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 Match&Merged API.

Suggest Edits

Filter Fields

 
Filter Field
Data Type
Description
Sample Request

firstrecorded_at

Object

Filter by the first recorded time of the offer. Any of the operators: gt, gte, lt, lte can be used.

lastrecorded_at

Object

Filter by the last recorded time of the offer. Any of the operators: gt, gte, lt, lte can be used.

sitedetails_name

String|Array

Filter by the site that the offer belongs to.

offset

Integer

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

limit

Integer

Restrict the number of products shown in your response.

isotime

Integer

Defaults to 0. Setting this field to 1 converts all timestamps in your API response to ISO time, i.e., human readable time.

All products in the Semantics3 database are categorized and tagged with a Category 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 from 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 or run queries against the Categories API.

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

/categories

 
gethttps://api.semantics3.com/v1/categories
var api_key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
var api_secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
var sem3 = require('semantics3-node')(api_key,api_secret);

sem3.products.categories_field( "cat_id", "9359" );

sem3.products.get_categories(
   function(err, offers) {
      if (err) {
         console.log("Couldn't execute request: get_offers");
         return;
      }
    console.log( "Results of request:\n" + JSON.stringify( offers ) );
   }
);
import com.semantics3.api.Products;

Products products = new Products(
	"SEM3xxxxxxxxxxxxxxxxxxxxxx",
	"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
);

products.categoriesField( "cat_id", "9359" );

JSONObject results = products.getCategories();

System.out.println(results);
require 'semantics3'

API_KEY = 'SEM3xxxxxxxxxxxxxxxxxxxxxx'
API_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

sem3 = Semantics3::Products.new(API_KEY,API_SECRET)

sem3.categories_field( "cat_id", "9359" )

productsHash = sem3.get_categories()

puts productsHash.to_json
from semantics3 import Products

sem3 = Products(
	api_key = "SEM3xxxxxxxxxxxxxxxxxxxxxx",
	api_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

sem3.categories_field("cat_id", "9359")

offers = sem3.get_categories()

print offers
<?php

require('lib/Semantics3.php');

$key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
$secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

$requestor = new Semantics3_Products($key, $secret);

$requestor->categories_field( "cat_id", "9359" );

$results = $requestor->get_categories();

echo $results;
using Semantics3;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace MyApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Products products = new Products("APIKEY", "APISECRET");
            products.categories_field( "cat_id", "9359" );
            JObject hashOffers = products.get_categories();
            Console.Write(hashOffers.ToString());
        }
    }
}
A binary file was returned

You couldn't be authenticated

{
  "code": "OK",
  "results_count": 1,
  "results": [{
    "cat_id": 9359,
    "name": "Unlocked Phones",
    "parent_name": "Mobile Phones",
    "crumb": "Unlocked Phones|Mobile Phones|Home",
    "parent_cat_id": 915
  }],
  "total_results_count": 1
}

Query Params

q
string

JSON payload containing query fields. These fields are discussed in detail below

 
Suggest Edits

Query Fields

 

All fields available in the response from the Categories API can be used to query against it. Queries cannot be used in combination with each other, i.e., each request to the Categories API must contain only one query field. The table below lists out all of the fields and queries associated with the Categories API:

Response / Query Field
Data Type
Description

cat_id

Integer

Category ID of the entry.

crumb

String

Entire crumb trail of the category entry.

name

String

Name of the category.

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_name

String

Name of the parent of this entry.

The Categorization API allows you to dynamically categorize products using the product metadata you may already have, against the Semantics3 Category Tree.

This endpoint is currently in Private Beta. If you'd like to try it out, speak to your Customer Success Manager to get access.

Suggest Edits

/categorize

 
posthttps://api.semantics3.com/v1/categorize
var api_key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
var api_secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
var sem3 = require('semantics3-node')(api_key,api_secret);

var endpoint = "categorize";
var method = "POST";
var jsonStr = '{"name" : "Apple iPhone"}';

sem3.run_query(endpoint, jsonStr, method, function(err, result) {
    if (err) {
      console.error("Couldn't execute query");
      console.error(err);
      return;
    }
    var res = JSON.parse(result);
});
require 'semantics3'

API_KEY = 'SEM3xxxxxxxxxxxxxxxxxxxxxx'
API_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

sem3 = Semantics3::Products.new(API_KEY,API_SECRET)

params = {
  "name" => "Apple iPhone"
}

res = sem3.run_query("categorize","POST", params)
from semantics3 import Products

sem3 = Products(
  api_key = "SEM3xxxxxxxxxxxxxxxxxxxxxx",
  api_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

params = {
  name: "Apple iPhone"
}

res = sem3.run_query("categorize", "POST", params)
import com.semantics3.api.Products;

Products products = new Products(
  "SEM3xxxxxxxxxxxxxxxxxxxxxx",
  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
);

String endpoint = "categorize";
Semantics3Request request = new Semantics3Request(apiKey, apiSecret, endpoint);
HashMap<String, Object> params = new HashMap<String, Object>();
JSONObject results = request.runQuery(endpoint, "POST", params);
<?php

require('lib/Semantics3.php');

$key = 'SEM3xxxxxxxxxxxxxxxxxxxxxx';
$secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

$requestor = new Semantics3_Products($key, $secret);
$params = array(
    "name" => "Apple iPhone"
);
$results = $requestor->run_query('categorize', $params, "POST");
using Semantics3;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace MyApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Products products = new Products("APIKEY", "APISECRET");
            JObject params = new JObject();
            params['name'] = 'Apple iPhone';
            JObject hashResponse = products.run_query('categorize', params, 'POST');
            Console.Write(hashResponse.ToString());
        }
    }
}
A binary file was returned

You couldn't be authenticated

{
   "results" : [
      {
         "crumb" : "Mobile Phones|Home",
         "parent_cat_id" : 1,
         "name" : "Mobile Phones",
         "cat_id" : 915,
         "parent_name" : "Home"
      }
   ],
   "code" : "OK",
   "results_count" : 1,
   "total_results_count" : 1
}

Body Params

q
string

JSON-encoded payload containing product data

 

Unlike our other Data APIs, this is a POST endpoint

Suggest Edits

Query Fields

 

A request to the Categorization API must be made with the name of the product to be characterized. If you have any of the other product attributes listed below, they can be sent along as well.

Request Field
Data Type
Description

name (required)

String

Name of the product

description

String

Detailed description of the product

brand

String

Brand name of the product

size

String

Size of the product

color

String

Color of the product

 

Seems Familiar?

You might notice that the response from this endpoint is identical in structure to what you will receive by querying against the Categories API

Response Field
Data Type
Description

cat_id

Integer

Category ID of the category that the input product was matched to

crumb

String

Entire crumb trail of the matched category

name

String

Name of the matched category

parent_cat_id

Integer

Category ID of the parent of the matched category

parent_name

String

Name of the parent of the matched category

 

Push Notifications open up opportunities to a build a whole new breed of applications.

The traditional method of accessing our API is called "polling" wherein you hit our API at regular intervals for product price or availability changes.

Over time, this method becomes highly inefficient, especially when you see yourself making several thousand calls just to detect changes on a handful of products.

The Push Notifications system handles this use case perfectly. Instead of you polling us at regular intervals to check for changes, we will notify you when we detect price or availability changes in any of the products that you want us to track. This enables you to build more robust software by taking action only when there is a change notification.

Suggest Edits

Callback URL

 

The first step to start using Push Notifications is to register a callback URL. This is the URL to which we will be sending notifications to when we detect product price or availability changes. This URL from your application must be accessible over the Internet and be capable of receiving HTTP POST requests.

The setup and management of your callback URL can be done from your Dashboard.

Preparing your URL for verification

Before accepting your callback URL, we do a one-time verification to ensure that you own it. To complete this verification process successfully, your URL must expect to receive an HTTP GET request with the verification_code query parameter. Your application must read the verification_code query parameter and respond to this request with its value in the response body. Example:

GET http://yourapp.com/semantics3/webhook?verification_code=6d495be3454763
6d495be3454763

Registering your URL

Go to the Notifications tab on your Dashboard and click on Add new webhook URI.

Click on the "Add new webhook URI" button

Click on the "Add new webhook URI" button

Paste your callback URL and click on Add URL. Once the URL is successfully verified, it will be registered to receive notifications. You can now start adding events.

Type in the URI of the receiver you have setup

Type in the URI of the receiver you have setup

Before you start adding events, ensure that you have already registered your callback URL.

Adding an event

Add an event to express intent on receiving change notifications about a given product URL.

curl -XPOST -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 (string)

URL of any product sold online.

type (string)

The following events are supported:

  • 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 (object)

This field applies to the price change i.e. price.* events. You can set constraints to indicate that you wish to be notified only when the updated product price meets these constraints. You can use any of the following operators to specify price constraints:

  • gte
  • gt
  • lte
  • lt

Listing all events

Listing events helps you look up all the events you have added.

curl -XGET -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
    }
  ]
}

Removing an event

You can remove an event to stop receiving change notifications about the associated product URL. Find the event ID from the events list.

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

Receiving a notification

When we detect a change that meets the constraints of an event that you had added, we will push a notification (send an HTTP POST request) to your callback URL with a payload that looks like this:

{
  "changes": [
    {
      "image": "https://content.backcountry.com/images/items/medium/SHAGRE.jpg",
      "url": "http://www.backcountry.com/mountain-hardwear-backpack-rain-cover-50-70l",
      "sku": "backcountry_mountain-hardwear-backpack-rain-cover-50-70l",
      "site": "backcountry.com",
      "availability": "Available",
      "type": "price.increase",
      "previous_price": 22.46,
      "current_price": 30
    }
  ],
  "url": "http://www.backcountry.com/mountain-hardwear-backpack-rain-cover-50-70l",
  "event_id": "wh_e_xxxxxyyyyyzzzzz",
  "notification_id": "wh_n_xxxxxyyyyyzzzzz",
  "webhook_id": "whxxxxxyyyyyzzzzz"
}
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 APIs

 

I ran a site search against the Match&Merged API 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 at least one sitedetails entry from the queried sites. To trim the document, you need to use the sitedetails_display filter.

To get raw data from the site, you can run the site query against the Raw Data API.

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 inactive prices.

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

We’ve built libraries for several popular programming languages, including Python, 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 an upc, ean and a 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.

Can I retrieve more than 10 products at a 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. If it is really important for your use-case to be able to retrieve more than 10 results at a time, let us know.

Can I control the frequency of update of URLs for push notifications?

URLs against which push notifications 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 Push Notification 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 push 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 Push Notification events are registered. This, in turn, depends on seasonal variations, pricing strategies of your target retailers, the popularity of your target products and more. Therefore, we suggest that you do not make any assumptions over the frequency of notifications while building your application.

How do I know if my application that is listening for your push notifications is set up correctly?

We currently do not have an automated method to handle this. If you are unsure, let us know and we will help you out.

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 a 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 the source.

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. However, 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 web store 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 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.

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