Introduction to the Semantic3 API

This short post describes how to work with the Semantics3 service, with whom I met during the development of a certain portal for online purchases.
The purpose of the service is to collect in one place all the goods in the world and give access to stores through the API to its database, where you can see the dynamics of prices, who sells what and so on (more than 35 million products are indexed at the moment). After the Google Search API for Shopping “retired,” Semantics3 is rapidly gaining momentum. Included in the top seven startups in the Y Combinator fund for the winter session of 2013.

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 the GitHub account - I received the API key and API secret, and chose a free plan, with a limit of 1000 requests per day.

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

The Endpoint API is the service version to use. It is divided into Production (https://api.semantics3.com/v1) and Test / Development (https://api.semantics3.com/test/v1). It differs in 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 100 call / day limit). For Production, OAuth v1.0 2 authentication and restriction are used depending on the chosen tariff plan.
')
Resource - API can be used to get products (/ products) and categories (/ categories). All products are organized by categories (cat_id) that 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 the 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 the development process, 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 has released several libraries to access the Production API.
implementations in Perl, Python, PHP, Node.js, Ruby, Java, and C #.
Here is an example of using semantics3 heme 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 

That will return a list of the first 10 products of the brand “Toshiba” from the category “Netbooks”. The list is in JSON format, for each product there are “name”, “price”, “img” fields (not available for the basic tariff plan), “url” (supplier's website address), 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 note fast and responsive support, even for a free data plan. When I had some questions in the process of developing a project, the guys from Semantic3 quickly helped in the solution.