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

Swader\Diffbot\Api\Product::setDiscussion($bool = true)
Parameters:
  • $bool (bool) – Either true or false
Returns:

$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 a discussion field in the result. The field will have all the sub-fields of the usual Swader\Diffbot\Api\Discussion call; i.e. you will be able to access the Swader\Diffbot\Entity\Discussion entity and all its sub entities via the Swader\Diffbot\Entity\Product::getDiscussion method.

Swader\Diffbot\Api\Product::setColors($bool)
Parameters:
  • $bool (bool) – Either true or false
Returns:

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

Swader\Diffbot\Api\Product::setAvailability($bool)
Parameters:
  • $bool (bool) – Either true or false
Returns:

$this

If set to true, Diffbot will attempt to find out whether or not the product in question is available / in stock.

Swader\Diffbot\Api\Product::setSize($bool)
Parameters:
  • $bool (bool) – Either true or false
Returns:

$this

If set to true, Diffbot will attempt to find out which sizes the product is offered in. Similar to Swader\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

Swader\Diffbot\Entity\Product::__construct(array $data)
Parameters:
  • $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 or Swader\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 a Swader\Diffbot\Entity\Discussion sub-entity (see Swader\Diffbot\Entity\Product::getDiscussion).

Swader\Diffbot\Entity\Product::getType()
Returns:string

Will always return “product” for products:

// ... API setup ... //
$result = $api->call();

echo $result->getType(); // "product"

Swader\Diffbot\Entity\Product::getText()
Returns: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.

Swader\Diffbot\Entity\Product::getRegularPrice()
Returns: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.

Swader\Diffbot\Entity\Product::getRegularPriceDetails()
Returns: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)

**/

Swader\Diffbot\Entity\Product::getShippingAmount()
Returns:string

Returns shipping price as string, e.g. “$5.99”.

Swader\Diffbot\Entity\Product::getSaveAmount()
Returns:string

Returns difference between regular price and offer price, as string, e.g. “$5.99”.

Swader\Diffbot\Entity\Product::getSaveAmountDetails()
Returns: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

**/

Swader\Diffbot\Entity\Product::getProductId()
Returns: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.

Swader\Diffbot\Entity\Product::getUpc()
Returns:string | null

UPC number, if found.

Swader\Diffbot\Entity\Product::getMpn()
Returns:string | null

MPN number, if found.

Swader\Diffbot\Entity\Product::getIsbn()
Returns:string | null

ISBN number, if found.

Swader\Diffbot\Entity\Product::getSku()
Returns:string | null

Returns Stock Keeping Unit – store/vendor inventory number or identifier if available. If not, returns null.

Swader\Diffbot\Entity\Product::getSpecs()
Returns: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.

Swader\Diffbot\Entity\Product::getImages()
Returns: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 the Swader\Diffbot\Api\Product API, the image data returned with this method is minimal. For fuller details about images, use the Swader\Diffbot\Api\Image API.

Swader\Diffbot\Entity\Product::getPrefixCode()
Returns:string | null

Country of origin as identified by UPC/ISBN, e.g. “United Kingdom”. Null if not present.

Swader\Diffbot\Entity\Product::getProductOrigin()
Returns:string

If available, two-character ISO country code where the product was produced (e.g. “gb”). Null if not present.

Swader\Diffbot\Entity\Product::getPriceRange()
Returns: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.

Swader\Diffbot\Entity\Product::getQuantityPrices()
Returns: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.

Swader\Diffbot\Entity\Product::isAvailable()
Returns:bool | null

Tries to determine whether or not the product is available / in stock. Returns boolean if determined, or null if not.

Swader\Diffbot\Entity\Product::getOfferPrice()
Returns:string

Returns price as string, e.g. “£49.85” or “32 kn”.

Swader\Diffbot\Entity\Product::getOfferPriceDetails()
Returns: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)

**/

Swader\Diffbot\Entity\Product::getSize()
Returns: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.

Swader\Diffbot\Entity\Product::getColors()
Returns: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.

Swader\Diffbot\Entity\Product::getBrand()
Returns:string

The brand of the product, as determined by Diffbot.

Swader\Diffbot\Entity\Product::getDiscussion()
Returns:Swader\Diffbot\Entity\Discussion | null

Returns the Swader\Diffbot\Entity\Discussion found on the product’s page (review section). See Swader\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(); // 10

For other methods exposed on the Swader\Diffbot\Entity\Discussion entity, see its documentation.