PopShops PHP API-V3 Library Documentation


Overview

PopShops provides a powerful RESTful API to our Data Pack subscribers.
This API exposes our products, offers, deals, brands, merchants, and categories through a JSON interface.
While it is entirely possible to use our API by itself, we also provide this PHP library which facilitates some common API functionality.

Getting Started

Before we begin, there's a few things you'll need to do:

  • Select at least one merchant in your catalog.
  • Ensure that your web server is configured to properly recognize and serve PHP files.
  • Download ps-v3-library.php and move it to the directory you want to serve your site from.
  • Find your API key and catalog key.
  • Enter them below and the demos on this page will become copy-paste runnable.

Hello, PopShops

    Create demo.php in the same directory as the library, and copy the following code into it:
<?php
  require('ps-v3-library.php');                               // Include the library
  $api = new PsApiCall('your_api_key',
                       'your_catalog_key'); 
  $api->call('products', array('keyword' => 'ipad'));         // Perform the call, searching for 'ipad'
  foreach ($api->getProducts() as $product) {                 // Iterate through the returned products
    print($product->getName() . '<br/>');                     // Print the name of each one
  }
?>

    Your page should render to something like this:

Apple - iPad with Retina display Wi-Fi - 16GB - Black
Apple - iPad with Retina display Wi-Fi - 16GB - White
Apple iPad 2 with Wi-Fi 16GB White MC979LL/A
Apple - iPad with Retina display Wi-Fi - 128GB - White
Apple - iPad with Retina display Wi-Fi - 128GB - Black
...

The PopShops APIs

The PsApiCall object can perform calls to four distinct APIs:
Products
Retrieve products and their associated offers, categories, merchants, deals, and brands.
Having instantiated a PsApiCall instance called $api, call this API as follows:
$api->call('products', $parameters);
where $parameters is an array of $param=>$value string pairs, such as: array('keyword'=>'ipad', 'category'=>'7000')
These $params can be any of the option request parameters listed here.

Merchants
Retrieve merchants and their associated merchant types, categories, and countries.
Having instantiated a PsApiCall instance called $api, call this API as follows:
$api->call('merchants', $parameters);
where $parameters is an array of $param=>$value string pairs, such as: array('alpha'=>'p', 'network'=>'2')
These $params can be any of the option request parameters listed here.

Deals
Retrieve deals and their associated merchants, deal types, and countries.
Having instantiated a PsApiCall instance called $api, call this API as follows:
$api->call('deals', $parameters);
where $parameters is an array of $param=>$value string pairs, such as: array('keyword'=>'laptop', 'deal_type'=>'6')
These $params can be any of the option request parameters listed here.

Categories
Retrieve categories and construct a hierarchical tree, starting at the most general and descending into the very specific.
Having instantiated a PsApiCall instance called $api, call this API as follows:
$api->call('categories');
PsApiCall->getCategoryTree() returns the topmost node of this tree.
Each node supports the methods getName(), getId(), and getChildren(), the last of which returns an array of zero or more child nodes.

Passing parameters via the URL string

To supplement the parameters (such as 'keyword' => 'backpack') passed to PsApiCall->call, the library searches through the GET query string for any parameters starting with 'psapi_' and incorporates them (stripped of their prefix) into the API call.
    Let's try it. Copy the following code into your demo.php file:
<?php
  require('ps-v3-library.php');                                               // Include the library
  $api = new PsApiCall('your_api_key',
                       'your_catalog_key');                   
  $api->call('products');                                                     // Note that no params are passed
  foreach ($api->getProducts() as $product) {                                 // Iterate through products
    print($product->getName() . '<br/>');                                     // Print the name of each
  }
?>
Now, append ?psapi_keyword=backpack to your request. The full request will look something like:

http://localhost/demo.php?psapi_keyword=backpack
This technique is useful for a variety of applications, such as accepting input from HTML forms.
The library can also do the "opposite": we can use it to generate query strings which,
having been served and then clicked, will later be read by the library.

The parameters included in the generated query string come from two places:
  • The internal options passed to PsApiCall->call
  • The parameters passed to the library via the query string (includes both parameters with and without the 'psapi_' prefix)
This feature allows you to preserve any parameters that already exist in the URL string, while modifying others.
If you want to add to/edit the parameters included in the link, see PsApiCall->getQueryString() below.

Note that these link generators do not return API call strings: they generate URLs with the same domain, path, and page name as the PHP page being served, but with the query parameters modified.
    Let's add a link to the next page of results:
<?php
  require('ps-v3-library.php');                                               // Include the library
  $api = new PsApiCall('your_api_key',
                       'your_catalog_key'); 
  $api->call('products');                                                     // Note that no params are passed
  foreach ($api->getProducts() as $product) {                                 // Iterate through products
    print($product->getName() . '<br/>');                                     // Print the name of each
  }
  // Create a link to this page, but with the 'page' parameter incremented:
  print('<a href="' . $api->nextPage() . '">Next page</a>');      
?>
All in all, PsApiCall supports four such link generators:
nextPage()
Generates a link to the next page of results
prevPage()
Generates a link to the previous page of results
paginate($page)
Generates a link to the specified page of results (1-100)
getQueryString($mods)
Generates a link to the page with the $mods (map of $params=>$values) applied
  For example:
  $api->getQueryString(array('page' => 7))
  is equivalent to
  $api->paginate(7)
  This generator is much more powerful than the other three.
  It allows a link to be generated to a page with any set of parameters you want.

PsApiCall

― A one-shot call against the PopShops Products/Merchants/Deals/Categories API, and a container for the parsed response values
The central class of the PopShops API Library.
Allows you to construct, execute, and parse the results of a call against one of four APIs:
  • Products
  • Merchants
  • Deals
  • Categories

A PsApiCall instance has the following public methods:
call($call_type[, $arguments])
$call_type must be one of 'products', 'merchants', 'deals', or 'categories'.
$arguments may optionally be passed as an array of parameter=>value pairs, such as:
  • array('page'=>5, 'merchant'=>'1043')
  • array('results_per_page'=>10, 'page'=>4, 'category'=>'403')
  • array('merchant_type'=>4, 'results_per_page'=>25)
The library then uses the construct-time provided account key, catalog key, $call_type, and optional $arguments to perform a call against a PopShops Api.
getProducts()
Returns an array of PsApiProduct objects parsed from the API response.
getOffers()
Returns an array of PsApiOffer objects parsed from the API response.
getMerchants()
Returns an array of PsApiMerchant objects parsed from the API response.
getDeals()
Returns an array of PsApiDeal objects parsed from the API response.
getBrands()
Returns an array of PsApiBrand objects parsed from the API response.
getCategories()
Returns an array of PsApiCategory objects parsed from the API response.
getDealTypes()
Returns an array of PsApiDealType objects parsed from the API response.
getMerchantTypes()
Returns an array of PsApiMerchantType objects parsed from the API response.
getCountries()
Returns an array of PsApiCountry objects parsed from the API response.
getProduct($id)
Retrieves the PsApiProduct object from the API response with the specified string $id. Returns NULL on failure.
getOffer($id)
Retrieves the PsApiOffer object from the API response with the specified string $id. Returns NULL on failure.
getMerchant($id)
Retrieves the PsApiMerchant object from the API response with the specified string $id. Returns NULL on failure.
getDeal($id)
Retrieves the PsApiDeal object from the API response with the specified string $id. Returns NULL on failure.
getBrand($id)
Retrieves the PsApiBrand object from the API response with the specified string $id. Returns NULL on failure.
getCategory($id)
Retrieves the PsApiCategory object from the API response with the specified string $id. Returns NULL on failure.
getDealType($id)
Retrieves the PsApiDealType object from the API response with the specified string $id. Returns NULL on failure.
getMerchantType($id)
Retrieves the PsApMerchantType object from the API response with the specified string $id. Returns NULL on failure.
getCountry($id)
Retrieves the PsApiCountry object from the API response with the specified string $id. Returns NULL on failure.
nextPage()
Generates a link to the next page of results
prevPage()
Generates a link to the previous page of results
paginate($page)
Generates a link to the specified page of results (1-100)
getQueryString($mods)
Generates a link to the page with the $mods (map of $params=>$values) applied
  For example:
  $api->getQueryString(array('page' => 7))
  is equivalent to
  $api->paginate(7)
  This generator is much more powerful than the other three.
  It allows a link to be generated to a page with any set of parameters you want.
hasParameter($parameter)
Returns true if the PsApiCall instance has been passed a parameter called $parameter.
These parameters may have come from two places:
  • The array passed to PsApiCall->call
  • The HTTP GET parameters prefixed with 'psapi_' (see URL Parameters above)
getParameterValue($parameter)
Returns the value of the given $parameter (see hasParameter for more information on these parameters).
If no such parameter exists, returns NULL.
getOptions()
Returns an array of the parameters that the PsApiCall has been configured with. See hasParameter for more information on these parameters.
getUrlPrefix()
Returns the URL prefix (see URL Parameters). Defaults to 'psapi_'.
getResultsCount()
Returns an integer representing the number of matching results. For example, a products call may return "500", meaning that 500 products were found to match. Not all of these products are guaranteed to be included in the API response; you may have to paginate through to get them all.
resource($resource)
An alternate way to access the arrays of API response objects.
For example, instead of calling "$api->getProducts()", you can call "$api->resource('products')"
The valid arguments are 'products, 'offers', 'merchants', 'deals', 'categories', 'deal_types', 'merchant_types', and 'countries'
resourceById($resource, $id)
An alternate way to access individual API response objects.
For example, instead of calling "$api->getProduct('4412')", you can call "api->resourceById('product', '4412')"
See above method for the valid $resource values. $resource must be plural, as seen above.

PsApiProduct

― Represents and facilitates the use of returned API data for a single Product
In PopShops terminology, a Product is simply an item or service, like an iPad or a set of concert tickets.
An individual Product does not have a specific seller. Merchants such as Amazon.com or Barnes&Noble may have Offers for a given Product.
It is these Offers that may actually be linked to and purchased by the consumer.
A PsApiProduct instance has the following public methods:
largestImageUrl()
Returns a URL to the largest image that PopShops indexes for this product.
smallestImageUrl()
Returns a URL to the smallest image that PopShops indexes for this product.
getBrand()
Returns the PsApiBrand object corresponding to this product.
getBrandId()
Returns the string ID of this product's brand. Given a PsApiCall object $api and a PsApiProduct object $prod, the statements $api->getBrand($prod->getBrandId()) and $prod->getBrand() will return the same PsApiBrand object.
getCategory()
Returns the PsApiCategory object corresponding to this product.
getCategoryId()
Returns the string ID of this product's category. Given a PsApiCall object $api and a PsApiProduct object $prod, the statements $api->getCategory($prod->getCategoryId()) and $prod->getCategory() will return the same PsApiCategory object.
getOffers()
Returns an array of PsApiOffer objects corresponding to this product. The API will only return a maximum of one offer for each product normally; to get all of the offers for a given product, add 'product'=>'product_id' to your parameters. You will only recieve information for one product, but all known offers will be included.
getDescription()
Returns a string description of the product.
getId()
Returns the string ID of the product. Given a PsApiCall object $api and a PsApiProduct object $prod, the statement $api->getProduct($prod->getId()) will simply return the same PsApiProduct object that we started with.
getImageUrlLarge()
If it exists, returns a large image for the product. If you'd simply like the largest image that PopShops provides for this product, it's recommended that you use largestImageUrl() (see above).
getImageUrlMedium()
If it exists, returns a medium sized image for the product.
getImageUrlSmall()
If it exists, returns a small image for the product. If you'd simply like the smallest image that PopShops provides for this product, it's recommended that you use smallestImageUrl() (see above).
getName()
Returns the product's name in string form.
getOfferCount()
Returns the total number of offers indexed for this product. The API will only return a maximum of one offer for each product if more than one product is requested; to get all of the offers for a given product, add 'product'=>'product_id' to your parameters. You will only recieve information for one product, but all known offers will be included.
getPriceMax()
Returns the highest price among all of the offers for this product.
getPriceMin()
Returns the lowest price among all of the offers for this product.

PsApiOffer

― Represents and facilitates the use of returned API data for a single Offer
An Offer is a Product being sold by a given Merchant for a certain price.
Note that the API will only return a maximum of one offer for each product if more than one product is requested; to get all of the offers for a given product, add 'product'=>'product_id' to your parameters. You will only recieve information for one product, but all known offers will be included.
A PsApiOffer instance provides the following public methods:
largestImageUrl()
Returns a URL to the largest image that PopShops indexes for this offer.
smallestImageUrl()
Returns a URL to the smallest image that PopShops indexes for this offer.
getCondition()
Returns a string representing the condition of the product, such as "new" or "used".
getCurrencyIso()
Returns the ISO currency code for the currency this offer is being sold in.
getCurrencySymbol()
Returns a string representing the HTML entity for the offer's currency symbol.
getDescription()
Returns a string of the merchant-provided description for the offer.

PsApiMerchant

― Represents and facilitates the use of returned API data for a single Merchant
A Merchant is an organization which publishes Offers, such as Amazon.com, Footlocker.com, or COMPUSA.
A PsApiMerchant instance provides the following public methods:
getOffers()
Returns an array of PsApiOffer objects offered by this merchant, parsed from the API response. Of course, only the offers included in the response can be returned.
getDeals()
Returns an array of PsApiDeal objects advertised by this merchant, parsed from the API response. Only deals included in the response can be returned.
getMerchantType()
Returns the PsApiMerchantType object that this merchant belongs to.
getMerchantTypeId()
Returns the string id of the merchant type that this merchant belongs to.
getCountry()
Returns the PsApiCountry object corresponding to the country that this merchant operates in.
getCountryId()
Returns the string id of the country that this merchant belongs to.
getCategory()
Returns the PsApiCategory object that this merchant belongs to.
getCategoryId()
Returns the string id of the category that this merchant belongs to.
getDealCount()
Returns the number of deals provided by this merchant.
getId()
Returns the string id of this merchant.
getLogoUrl()
Returns a URL to a small (about 125 wide by 40 high) logo for the merchant.
getName()
Returns the name of this merchant.
getNetworkId()
Returns the string id of the network that this merchant belongs to.
getNetworkMerchantId()
Returns the string id of this merchant within its network. Note that this id is not globally unique, and is only valid within the affiliate network that the merchant belongs to. PopShops does not use this id, but instead uses the id that can be retrieved with PsApiMerchant->getId().
getUrl()
Returns a URL to a landing page for this merchant.
getCount()
In a deals/coupons call, getCount() will return the number of deals/coupons available from this merchant.

PsApiDeal

― Represents and facilitates the use of returned API data for a single Deal
A Deal is a coupon or savings provided by a Merchant, such as a percentage off or free shipping.

PsApiCategory

― Represents and facilitates the use of returned API data for a single Category
We've created a set of Categories to organize the vast array of Products that we index.

PsApiBrand

― Represents and facilitates the use of returned API data for a single Brand
A Brand is a vendor or manufacturer who produces a line of goods, such as Sony or Toshiba.

PsApiMerchantType

― Represents and facilitates the use of returned API data for a single MerchantType

PsApiDealType

― Represents and facilitates the use of returned API data for a single DealType