Product API¶
The Product API is used to parse pages representing products. These can be anything from eBay auction pages and books on Amazon, to leashes and collars in “mom and pop’s pet web shop”.
The Product API will attempt to recognize some of the most popular product-related fields in any given product page, including but not limited to:
- price
- discount
- availability status
- stock level
- characteristics / stats (like smartphone capacity, battery life, network type...)
- reviews
- unique identification number like SKU / ISBN / MPN / UPC...
- and much more...
For a more thorough walk through the product API, see the official docs and demo.
The Product API part of the Diffbot PHP client consists of two main classes: the API class, and the Product Entity class. We’ll describe them in order. Note that the API class extends Swader\Diffbot\Abstracts\Api
, so be sure to read that first if you haven’t already.
Product API Class¶
-
class
Swader\Diffbot\Api\
Product
¶
Basic Usage:
use Swader\Diffbot\Diffbot;
$url = 'http://some-product-to-process.com';
$diffbot = new Diffbot('my_token');
$api = $diffbot->createProductApi($url);
setDiscussion¶
Swader\Diffbot\Api\Product::
setDiscussion
($bool = true)¶
Parametri:
- $bool (bool) – Either
true
orfalse
Vraća: $this
Whether or not to use the Discussion API to additionally process any detected comment or review threads on the product page. Behaves as if the
Swader\Diffbot\Api\Discussion
was set to process the page, and merges the returned data with the Product API’s results by means of adiscussion
field in the result. The field will have all the sub-fields of the usualSwader\Diffbot\Api\Discussion
call; i.e. you will be able to access theSwader\Diffbot\Entity\Discussion
entity and all its sub entities via theSwader\Diffbot\Entity\Product::getDiscussion
method.
setColors¶
Swader\Diffbot\Api\Product::
setColors
($bool)¶
Parametri:
- $bool (bool) – Either
true
orfalse
Vraća: $this
If set to
true
, the Product API will try to find out the color options of the product, if available. This feature is experimental and often fails even when color options are obvious.
setAvailability¶
Swader\Diffbot\Api\Product::
setAvailability
($bool)¶
Parametri:
- $bool (bool) – Either
true
orfalse
Vraća: $this
If set to
true
, Diffbot will attempt to find out whether or not the product in question is available / in stock.
setSize¶
Swader\Diffbot\Api\Product::
setSize
($bool)¶
Parametri:
- $bool (bool) – Either
true
orfalse
Vraća: $this
If set to
true
, Diffbot will attempt to find out which sizes the product is offered in. Similar toSwader\Diffbot\Api\Product::setColors
, this method is unreliable and highly experimental.
Product Entity Class¶
When the Product API is done processing a product (or several) the result will be a Product Entity (i.e. a collection of one Product Entities inside an instance of Swader\Diffbot\Entity\EntityIterator
).
For an overview of the abstract class all Entities build on, see Swader\Diffbot\Abstracts\Entity
.
Note that the Product entity can also be returned by the Swader\Diffbot\Api\Analyze
API in “product” mode, or in default mode when processing a URL that contains a product (auto-determined).
-
class
Swader\Diffbot\Entity\
Product
¶
__construct¶
Swader\Diffbot\Entity\Product::
__construct
(array $data)¶
Parametri:
- $data (array) – The data from which to build the Product entity
The Product entity’s constructor needs the data to populate its properties (see getters below). This class is automatically instantiated after a
Swader\Diffbot\Api\Product
orSwader\Diffbot\Api\Analyze
call. You probably won’t ever need to manually create an instance of this class.In the case of the Product entity, the constructor differs from the abstract one (
Swader\Diffbot\Abstracts\Api::__construct
) in that it also looks for the discussion key in the result, in order to build aSwader\Diffbot\Entity\Discussion
sub-entity (seeSwader\Diffbot\Entity\Product::getDiscussion
).
getType¶
Swader\Diffbot\Entity\Product::
getType
()¶
Vraća: string Will always return “product” for products:
// ... API setup ... // $result = $api->call(); echo $result->getType(); // "product"
getText¶
Swader\Diffbot\Entity\Product::
getText
()¶
Vraća: string | null Returns the plaintext content of the processed product page. HTML tags are stripped completely, images are removed. If the text property is missing in the result, returns
null
.
getRegularPrice¶
Swader\Diffbot\Entity\Product::
getRegularPrice
()¶
Vraća: string Returns regular price as string, e.g. “$23.99” or “32 kn”. If not found, returns offerPrice instead - see
Swader\Diffbot\Entity\Product::getOfferPrice
.
getRegularPriceDetails¶
Swader\Diffbot\Entity\Product::
getRegularPriceDetails
()¶
Vraća: array Separates regularPrice into components like currency, amount, and full string. If not found, serves as alias for
Swader\Diffbot\Entity\Product::getOfferPriceDetails
.Usage:
// ... API setup ... // $result = $api->call(); var_dump($result->getRegularPriceDetails()); /** array (size=3) 'amount' => float 49.85 'text' => string '£49.85' (length=7) 'symbol' => string '£' (length=2) **/
getShippingAmount¶
Swader\Diffbot\Entity\Product::
getShippingAmount
()¶
Vraća: string Returns shipping price as string, e.g. “$5.99”.
getSaveAmount¶
Swader\Diffbot\Entity\Product::
getSaveAmount
()¶
Vraća: string Returns difference between regular price and offer price, as string, e.g. “$5.99”.
getSaveAmountDetails¶
Swader\Diffbot\Entity\Product::
getSaveAmountDetails
()¶
Vraća: array Separates saveAmount into components like currency, amount, and full string, much like
Swader\Diffbot\Entity\Product::getRegularPriceDetails
. One of the array keys is also a flag indicating whether or not the save amount is a percentage value.Usage:
// ... API setup ... // $result = $api->call(); var_dump($result->getSaveAmountDetails()); /** array (size=4) 'amount' => float 13.5 'text' => string '£13.50' (length=7) 'symbol' => string '£' (length=2) 'percentage' => boolean false **/
getProductId¶
Swader\Diffbot\Entity\Product::
getProductId
()¶
Vraća: string | null Diffbot-determined unique product ID. If upc, isbn, mpn or sku are identified on the page, productId will select from these values in the above order. Null if none found.
getSku¶
Swader\Diffbot\Entity\Product::
getSku
()¶
Vraća: string | null Returns Stock Keeping Unit – store/vendor inventory number or identifier if available. If not, returns null.
getSpecs¶
Swader\Diffbot\Entity\Product::
getSpecs
()¶
Vraća: array If a specifications table or similar data is available on the product page, individual specifications will be returned in the specs object as name/value pairs. Names will be normalized to lowercase with spaces replaced by underscores, e.g. display_resolution.
If no specs table is found, an empty array will be returned.
getImages¶
Swader\Diffbot\Entity\Product::
getImages
()¶
Vraća: array An array of images found on the product page, with their details. The elements of the array are arrays like this one:
/** array (size=7) 'height' => int 512 'diffbotUri' => string 'image|3|-851701004' (length=18) 'naturalHeight' => int 727 'width' => int 749 'primary' => boolean true 'naturalWidth' => int 1063 'url' => string 'http://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2014/07/140624455201.png' (length=79) **/Unlike the
Swader\Diffbot\Api\Discussion
API which returns details about discussion posts even when used with theSwader\Diffbot\Api\Product
API, the image data returned with this method is minimal. For fuller details about images, use theSwader\Diffbot\Api\Image
API.
getPrefixCode¶
Swader\Diffbot\Entity\Product::
getPrefixCode
()¶
Vraća: string | null Country of origin as identified by UPC/ISBN, e.g. “United Kingdom”. Null if not present.
getProductOrigin¶
Swader\Diffbot\Entity\Product::
getProductOrigin
()¶
Vraća: string If available, two-character ISO country code where the product was produced (e.g. “gb”). Null if not present.
getPriceRange¶
Swader\Diffbot\Entity\Product::
getPriceRange
()¶
Vraća: array | null If the product is available in a range of prices, the minimum and maximum values will be returned. The lowest price will also be returned as the offerPrice (see
Swader\Diffbot\Entity\Product::getOfferPrice
). If no range is detected, returns null.
getQuantityPrices¶
Swader\Diffbot\Entity\Product::
getQuantityPrices
()¶
Vraća: array | null If the product is available with quantity-based discounts, all identifiable price points will be returned. The lowest price will also be returned as the offerPrice (see
Swader\Diffbot\Entity\Product::getOfferPrice
). If no range is detected, returns null.
isAvailable¶
Swader\Diffbot\Entity\Product::
isAvailable
()¶
Vraća: bool | null Tries to determine whether or not the product is available / in stock. Returns boolean if determined, or null if not.
getOfferPrice¶
Swader\Diffbot\Entity\Product::
getOfferPrice
()¶
Vraća: string Returns price as string, e.g. “£49.85” or “32 kn”.
getOfferPriceDetails¶
Swader\Diffbot\Entity\Product::
getOfferPriceDetails
()¶
Vraća: array Separates offerPrice into components like currency, amount, and full string.
Usage:
// ... API setup ... // $result = $api->call(); var_dump($result->getOfferPriceDetails()); /** array (size=3) 'amount' => float 49.85 'text' => string '£49.85' (length=7) 'symbol' => string '£' (length=2) **/
getSize¶
Swader\Diffbot\Entity\Product::
getSize
()¶
Vraća: array | null If product is available in different sizes, returns array of those sizes. Highly experimental and often unreliable. This field is optional, and needs to be set on the API. See
Swader\Diffbot\Api\Product::setSize
.
getColors¶
Swader\Diffbot\Entity\Product::
getColors
()¶
Vraća: array | null If the product is available in multiple colors, returns the color options. Highly experimental and often unreliable. This field is optional, and needs to be set on the API. See
Swader\Diffbot\Api\Product::setColors
.
getBrand¶
Swader\Diffbot\Entity\Product::
getBrand
()¶
Vraća: string The brand of the product, as determined by Diffbot.
getDiscussion¶
Swader\Diffbot\Entity\Product::
getDiscussion
()¶
Vraća: Swader\Diffbot\Entity\Discussion
| nullReturns the
Swader\Diffbot\Entity\Discussion
found on the product’s page (review section). SeeSwader\Diffbot\Api\Product::setDiscussion
for details and below for usage:use Swader\Diffbot\Diffbot; $url = "http://www.sportsdirect.com/slazenger-plain-polo-shirt-mens-542006?colcode=54200601"; $diffbot = new Diffbot("my_token"); $api = $diffbot->createProductApi($url); $result = $api->call(); echo $result->getDiscussion()->getNumPosts(); // 10 echo $result->getDiscussion()->getParticipants(); // 10For other methods exposed on the
Swader\Diffbot\Entity\Discussion
entity, see its documentation.