The Semantics3 APIs explained
What they do, and how to best utilize them.
First, let’s do a quick run-through of the basics.
[Readers familiar with APIs can skip the section below.]
What is an API?
An API (Application Programming Interface) is a set of tools for building software applications.
Semantics3's APIs are tools that allow users to access our e-commerce product database through simple queries.
Think of an API as a set of Lego blocks. There are many different types of bricks, and many other useful pieces that fit together
A good API provides all the building blocks one needs to create a useful software application.
For example, let's say a person (let’s call her Tara) wants to build an online fashion store. In the old days, building an online store wasn’t very easy. Tara would first have to put together a database of products, create pictures of the products she wants to sell, and present them on her website in a way that entices customers to buy her products.
Tara would have to build her website, set up online payment systems, figure out a way to handle shipping and returns and so on. In most cases, she would find building an online store pretty tough, and probably expensive.
Here’s where APIs simplify things.
Instead of having to build her own payment system, create a product database, and set up a logistics chain, Tara can just plug her store to APIs that can manage and automate these separate building blocks for her.
Stripe is a payment processing API that would allow her to handle transactions on their website.
Shipbeat offers a logistics-as-a-service API that would let her automate product shipping by providing basic information on what to ship, where from and where to.
Semantics3 offers a product database API that she can use to pull e-commerce product data for analytics, web-stores, inventory management, e-commerce applications and so on.
There! Using APIs, Tara’s online fashion store is up and running!
Put simply, APIs allows people to focus on building the product that they want, without forcing them to re-invent the wheel.
Now, let’s talk about what the Semantics3 APIs do
We realized a while ago that it is difficult to create one universal product API. Different customers have different use-cases for our data.
Typically, users want to:
- Search for and obtain structured product data for a website, for analytics or for applications.
- Receive notifications when prices change on a specific product and/or notify customers of these changes.
- Fetch product information as they appear on a retailer’s site at any instant.
In order to optimize data applications, we’ve created four separate APIs to meet these challenges
- The Products API(/v1/products) — PULL-type API
- The SKUs API (/v1/skus) — PULL-type API
- The Push API (/v1/webhooks) — PUSH-type API
- The RealTime API (/v1/realtime/skus) — REALTIME
Think of our APIs as Tony Stark’s Ironman collection.
Pull APIs — As the word ‘pull’ implies — this group of APIs can be used to pull product information from our database. There are two APIs that use the pull architecture — the Products API (/v1/products) and the SKUs API (/v1/skus):
The other types of APIs — namely Push and Realtime APIs are more specialized for distinct applications — these APIs are limited in scope, but very powerful in their specific use cases.
A Push API is used to push notifications to the user’s system when our database detects a change in any specific product’s metadata — e.g. price, availability or specifications.
A RealTime API is designed to allow the user to fetch live product data on demand from the original site without having to wait for our database to be updated.
Think of these two APIs as specialized Ironman armory — e.g. the Hulkbuster — very powerful, but niche.
Products API
Our first and flagship API is the Products API [v1/products]. This is like the iconic Mark III armor that pretty much embodies the Ironman persona — powerful, versatile, and useful for roughly 80% of typical data applications.
The Products API is our Flagship API— our Mark III armour.
This API allows access to the best of our product-centric database. It utilizes our proprietary Product Matching and Product Categorization algorithms, which when combined, provide for some very useful functionalities :
- Each unique product can be mapped with all available price points across retailers. Additionally, all available metadata is merged to that single unique product. For example, an iPhone 6 Gold 64gb from Amazon.com is matched up against the same product from Target.com, allowing the user to compare prices against both retailers. Additionally, if the Amazon iPhone has a UPC and the Target iPhone doesn’t, fetching the Target iPhone from our API will also fetch the UPC as extracted from Amazon.
- Each unique product is assigned a unique ID called the sem3_id to which all other identifying features are tagged (e.g. if a product comes with identifying features like a UPC, an EAN, model part number or SKU number, all these are tagged to the sem3_id).
- Variations of the same product are captured using the variation_id: variations of the same product share a variation_id but will have different sem3_ids.
- All products in this API are mapped to a single, master category taxonomy.
- Product metadata is normalized, i.e. converted to a single global standard. E.g. weights are converted from pounds to milligrammes, etc.
- Expanded UPC search: The UPC-specific query: {“upc”:1234567789} can be further enhanced to fetch UPC matches on any valid UPC, even if its not in the database.
SKUs API
The SKUs API allows a user to access from the Semantics3 database unmodified, structured data as seen on a retailer’s website.
This API was developed in response to customers who wanted raw, unmodified data as extracted from retailer websites.
Think of it as a powerful scraping engine created specifically to get pure structured data from e-commerce websites without any of the data enrichment magic that comes in the Product API.
This data is unmodified — weight in pounds is not converted to grams.
This data is structured — data on products is neatly organized by fields (name, dimension, weights, UPC etc.)
Advantages:
- Highly accurate (info as seen on retailer website from within 2 weeks prior).
- Rapid refresh rate — new products from prior week are captured.
- Higher limits on pagination — get access to more data from a single site.
Limitations:
- No data enrichment.
- Product metadata is not normalized.
Push API
As the word ‘push’ implies, this API, accessed via the endpoint (/v1/webhooks) can be used to push out alerts when any information on a specific product has changed.
This is how it works:
- Users specify which products they are interested in monitoring (products can be registered programmatically, or can be done manually by adding to wish-lists).
- We’ll mark those products for push notifications in our system.
- During price refreshes, when a price change occurrence is detected on those products, the API will automatically generate a push notification to send to the user’s application or database.
For a given sem3_id, the user can get a daily update on whether product prices have changed across all the retailers covered in the Semantics3 database.
Here’s our previous blog post explaining how the Push API works.
Advantages:
Track price changes for a given product across a host of retailers and get alerts with information whenever there is a price change.
Limitation:
Push API cannot be used on standalone basis — it has to be used in conjunction with the Pull API; i.e. the user will need to first obtain the product’s sem3_id via the Pull API.
RealTime API (private beta)
The RealTime API allows a user to extract information as seen in real time (live) on a particular retailer’s website.
This information is not from the Semantics3 database, but directly from the retailer.
This is how it works:
- User feeds a URL as an input
- The RealTime API then performs a live crawl of the product page and returns the product features (name, price, other details) as displayed on the original site.
Advantage:
Get real time, structured information for any product based on a URL input.
Limitation:
Information is as seen on retailer and not normalized.
Conclusions…
Semantics3's APIs offer, by far, the best access to the richest e-commerce product data across the industry.
We are constantly innovating and pushing out new features, APIs and functionalities, all driven by customer feedback. Customers matter a lot to us — they are our champions, and they are our biggest fans. We do what it takes to satisfy our customer— including customizing our APIs for them.
Like what you read? Try our APIs with a free 30-day trial
Don’t want to use an API? We offer Datascience-as-a-Service too!
Wanna talk to us about our data services? Pick a convenient time for us to call you!
As always, lovingly crafted in San Francisco and Bengaluru
by the data geeks at Semantics3
