Introducing the Semantic3 API

This short post describes working with the Semantics3 service , which I met in the process of developing a certain portal for shopping on the Internet.
The goal of the service is to collect in one place all the goods in the world and give access to stores via API to their base, where you can see the price dynamics, who sells what, and so on (more than 35 million products are currently indexed). After the Google Search API for Shopping “retired,” Semantics3 is rapidly gaining momentum. He is one of the seven best startups in the Y Combinator fund for the 2013 winter session.

Beginning of work


First of all, you need to register an account with them on the site in order to get a key for using the API. Then you can choose any of 4 tariff plans. I logged in through GitHub account - I got an API key and an API secret, and chose a free plan with a limit of 1000 requests per day.

An API request consists of 3 components:
For example, URL:
(https://api.semantics3.com/v1 - API Endpoint
/ products? - Resource
q = {"cat_id": 13658, "brand": "Toshiba", " model ":" Satellite "}) - Query Parameters

API EndpointIs the version of the service to use. It is divided into Production (https://api.semantics3.com/v1) and Test / Development (https://api.semantics3.com/test/v1). It differs by the authentication method and the limit on the number of API calls per day. For Test, this is basic authentication (the ability to use Curl) and a limit of 100 calls / day). For Production, OAuth v1.0 2 authentication and restriction are used depending on the selected tariff plan.

Resource - API can be used to get products (/ products) and categories (/ categories). All products are organized into categories (cat_id), which have a tree structure -
For example, there is the category “Electronics” (cat_id 13658), which contains several child categories, including “Computers & Accessories” (cat_id 4992), which in turn includes a child category “Scanners” (cat_id 14047).

Query Parameters - search queries are expressed as a JSON string. You can build very flexible queries using up to 50 different fields.

API Libraries


During development, while testing search queries, you can use the Curl utility.
 curl -G -H "api_key: SEM3E892B8487C7EA8267E1B0C8CE8345157"
https://api.semantics3.com/test/v1/products
--data-urlencode 'q={"cat_id":13658,"brand":"Toshiba","model":"Satellite"}'

In general, Sematic3 released several libraries for accessing the Production API
implementation in Perl, Python, PHP, Node.js, Ruby, Java, and C #.
Here is an example using the semantics3 gem in Ruby:
require'rubygems'require'semantics3'
      API_KEY = 'SEM3xxxxxxxxxxxxxxxxxx'
      API_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxx'
      sem3 = Semantics3::Products.new(API_KEY,API_SECRET)
      sem3.products_field( "cat_id", 4992 )
      sem3.products_field( "brand", "Toshiba" )
      productsHash = sem3.get_products
      puts "Results of query:\n",productsHash.to_json

Which will bring back a list of the top 10 Toshiba brand products from the Netbooks category. The list is presented in JSON format, for each product there are fields “name”, “price”, “img” (not available for the basic tariff plan), “url” (address of the supplier’s website), etc. This can be displayed as a web product listing pages.

Examples of search queries can be found in the documentation.

I would also like to mention fast and responsive support, even for a free tariff plan. When I had some questions during the development of the project, the guys from Semantic3 quickly helped with the solution.

Also popular now: