Online shopping is easy, fast and convenient, but sometimes only the brick-and-mortar experience will do—like when you need modeling clay for your child’s science project due … tomorrow! Luckily, our mobile devices can still serve us well in the physical world, helping us compare prices and find inventory at the closest store.
Indeed, a recent study conducted by Local Corp, "Spotlight on the Mobile Local Shopper," revealed that smartphone use specifically for local store shopping has increased significantly during the past year. And a fundamental component of a great local shopping experience is a local shopping API that can be used to provide useful, timely data to mobile and Web applications.
In this article we’ll look at two local shopping APIs, from Goodzer, and Retailigence. We'll evaluate their ease of use, functionality and general ability to enable organizations to boost revenue.
I became familiar with Goodzer in 2011. At the time, it was a capable Web application that helped shoppers find products in brick-and-mortar local stores. I asked Dmitry Pakhomkin, the company’s president and co-founder, about the possibility that a Goodzer API might be released. He said an API was indeed in the works.
The Goodzer API has since been released.
According to Goodzer, the API is free to developers, and will enable online publishers, local-search sites, social communities and mobile apps to enrich their search inventory with results that were previously unavailable or difficult to find, particularly with goods from small businesses. The API can also be used by local check-in services and loyalty programs.
My tests show that the Goodzer API is easy to use, yet powerful and efficient. According to the company, the API covers more than 2.5 billion inventory items in 500,000 store locations, and is updated constantly. Goodzer's API can be used in stores across the United States, including Alaska and Hawaii.
The Goodzer API documentation, which can be found here, is very good Goodzer is simple to test out in a browser--all that’s needed for authentication and authorization is the passing of an API key that’s obtained for free here.
The number of API calls per day by key is initially limited to 1,000. The Goodzer Terms of Service specifically state that you "must not create duplicate accounts in order to evade the limitations." I've found that Goodzer will work with organizations to increase limits as required. The Terms of Service also prohibit storing the information that's returned from the API for any reason other than providing a cache to improve performance. In any case, data can be stored only for 24 hours.
Some of the methods limit the initial results to 10. In fact, any method that accepts an &offset parameter will automatically limit the results to an initial set of 10. The initial result set size not currently adjustable.
Although the results are limited to this window size, I found the use of &offset to be very reliable and predictable in the results that are returned. For example, I tried the following query:
The stores_found field indicated that there were 16 found, but results were returned only for the first 10. By specifying the &offset as 1, the results no longer included the first store, and a new store was added on the end. And by specifying an offset of &offset=10, the first 10 results were skipped altogether, and the results for the last 6 were returned instead, verifying that no surprises in the returned results occur when paging the results in this way.
The Search Stores function is very straightforward: It searches for any store within the radius of the specified location (latitude and longitude) that has products matching the search query. As the sample response in the documentation shows, there are sections in the returned JSON document for each store where the product is found. These include
- Website: The store's website
- Name: The store's name
- Products_found: number of products found for this store
- Locations_found: number of locations found for this store
- An array of locations, with each entry in the array containing store location information such as latitude and longitude, an id for the location, address and phone number
- An array of products, with each entry in the array containing product details, such as URL (a purchase URL that, when clicked on, takes a customer to the merchant’s website to purchase the item, add to a wishlist, and so on); image (an image of the product); product price; an ID that can be used in additional API calls; and a short product title
Search Stores returns all the stores within a radius for a particular product query. What if you wanted to search for a particular product from a specific retailer, regardless of the location? For that, Search in Store will search at the retailer level, regardless of your location. It can be used to answer the question of whether a retailer carries the products in a query at all. Search in Store returns the same results as Search Stores without the locations array.
An excerpt from the Search Stores result:
Search Locations takes most of the same query parameters as Search Stores, but it returns the set of locations where the product can be found, without all the details of the product information. As the documentation shows, each location in the result is identified by an ID field that signifies the physical location of a store, along with a store_id field, which signifies the company or merchant.
The location results from Search Locations doesn't have quite the level of detail as the results from Search Stores does. To get to additional information, such as detailed address and contact information, there's the Location Details call that takes a locationId parameter (the ID field from a location) and returns more in-depth location details.
Location Details returns detailed information about a single store location, but what if you wanted to find out all the locations for a particular retailer, within a certain radius of your location? For that, the Goodzer API provides the Store Locations query, which will return all locations for a specific storeId.
Search Locations output looks like this:
The Product Availability method is an interesting one. Notice the realtime_availability field returned from both the Search Stores and Search in Store methods. This is an indicator that Product Availability may be used to check if a particular product is available or in stock at one of the store’s locations.
For instance, here are the results from a Search Stores query for a retailer that provides real-time availability:
I've highlighted the ID field from the products sub-document in the results to specify the product to check on. I've also highlighted the ID fields from a couple of locations in the locations sub-document in the results from Search Stores, to specify the location to look at for availability.
Here is the Product Availability query using these as parameters:
For each location queried, the results are in, out or unknown.
Product Availability is a powerful feature, especially if your users are driving around looking for an item to be actually in-stock at a particular retailer. Not all retailers provide availability data at this time, but the hope is that additional merchants will capitalize on this feature in the Goodzer API over time.
The Retailigence Product Information API provides many of the same capabilities as the Goodzer API, with some unique differences:
- Product search is flexible; there are a variety of ways to specify what you're looking for. We'll cover the assortment and show some examples.
- Location search is also flexible, accepting latitude/longitude as well as ZIP code and IP address as the starting point.
- API response results are available in a choice of JSON or XML formats.
- Product and location searches both return links to turn-by-turn navigation provided by Scout.me.
- Location search also returns Google Maps link to the location.
- Retailigence provides a means to monetize applications that send customers to participating retailers.
Access to the Retailigence API can be requested by filling out the short form here.
There are no rate limits or daily call limits for the API, although there are controls in place to look for obvious abuses.
Retailigence documentation, while fairly extensive, can be frustrating. For one thing, the API documentation is not available at all until you apply for a key to the API. In addition, a good portion of the parameters and output fields in the documentation don't quite match the API at this time. On the other hand, Retailigence support is very eager to assist, and quite responsive.
For both Products and Locations there is a pagesize parameter to specify the number of results desired. This parameter has a default of 10 results per page. Experimenting with pagesize reveals the maximum to be 100 results. As with the Goodzer API, the entire set of results for a particular query can be easily navigated by using pagesize along with the page parameter to focus on a specific set of results.
In addition to pagesize and page, the Products query has a maxperretailer parameter to limit the number of responses for each retailer in the results. The default for maxperretailer is five per retailer.
Both Products and Locations calls must supply a parameter called requestorid that consists of a unique string that represents the current user. The requestorid should not change in subsequent calls, even across sessions. The documentation suggests that requestorid is associated with a user, or with a mobile phone device, and the documentation describes how to enable that association.
Both Products and Locations queries return a search result with an id field and a corresponding request sub-document with the same id value, along with all of the parameters used in the query, as shown in this excerpt. (Results are collapsed in this example.)
The Products query returns results for products found in a specified radius from a location. There are many ways in the Retailigence API to specify what to look for, including:
- Keywords, including AND, OR and NOT logic. (Appendix C of the API documentation has some examples of using AND, OR and NOT logic.)
- Barcode (This isn't mentioned in the list of parameters, but it does seem to work.)
- Product name. (While this may sound like a risky way to search, as it is often impossible to accurately predict the name of a product, the API provides a modifier to use along with product name searches: the strict parameter. You can specify strict as True, False or Semi. It actually worked pretty well, at least in my tests.)
- Productid (The standard product identifiers such as UPC, EAN, SKU)
The results are by product, with embedded location information. The results are delivered in either JSON or XML, and consist of several major parts. These include:
- Product name
- Barcode in numeric form
- An array of images of the product in various sizes
- A purchase url (called simply: url)
- A product type array
- Distance: a two-element array comprising numeric distance and the units of measure such as "miles" or "km"
- Scout.me link for turn-by-turn instructions
- Location in latitude and longitude
- Hours of operation for the location
- Location name - usually this is the retailer's name followed by the geographic location (town or city) in which this location resides
- Retailer sub-document including such elements as logo, name of the retailer
3. Retail price
4. Currency units to use for the price
5. Inventory: This is a ready-to-use URL to perform a real-time availability check for a specific product at a specific location. This real-time availability check is also available in the Retailigence API as the Inventory Lookup call. When included as part of the Products result, your API-key and relevant product ID and location ID are pre-populated in the URL.
Here's an excerpt of a Products query result. Some sections of the result have been collapsed for readability:
The category parameter can be used to differentiate keyword searches in a way that's not easy to do using just keywords. For instance, suppose that we're searching using the keyword "pods" to locate the "Despicable Me 2 Battle Pods Game":
The results of this search includes all manner of pods--everything from coffee pods to exercise equipment. We can use the category parameter to limit the search to the "Toys & Games" category to provide more useful results:
If instead you were indeed looking for the coffee pods, there's a "Home & Garden" category to concentrate the search on a more appropriate category:
Note: When using these in the query, the ampersand "&" in the category name needs to properly URL-encode. (Productcategory is a synonym for category parameter.)
While not listed in the API V2.1 documentation, Retailigence support replied with this list of the current top-level categories:
- Animals & Pet Supplies
- Apparel & Accessories
- Arts & Entertainment
- Baby & Toddler
- Cameras & Optics
- Food, Beverages & Tobacco
- Health & Beauty
- Home & Garden
- Luggage & Bags
- Office Supplies
- Sporting Goods
- Toys & Games
- Vehicles & Parts
Product category is a powerful way to focus generic search arguments into specific product categories. But there's also another parameter--rcategory or retailcategor--that focuses on the category of the retailer itself, regardless of the product category.
Retailigence supplied this list of retailer categories:
- Home Furnishings
- Home Improvement
- Office Supply
- Personal Care
The Locations query returns retailers and their locations carrying products matching the criteria.
The parameters for Locations are similar to those that are used for the Products query. The output is also similar to the Products output, with the difference being that only the retailer and location information is returned, and no product information.
In this case, the results are by retailer, with embedded location information.
Location for the search may be specified in a variety of ways: latitude/longitude, ZIP code or IP Address using the userlocation argument.
An excerpt from a Locations query is shown here:
As we saw in the section about the Products search, some retailers offer the ability to dig further and perform a real-time availability check for a product at a specific retailer location. If available, the inventory field in the result for Products search contains a nicely pre-populated URL to be used to perform the inventory check.
The Inventory Lookup call is available for this same purpose--to perform this inventory check independently, without using the URL from the inventory field, for instance.
An intriguing feature of the Retailigence API is the capability to monetize its usage: you can actually earn income based on sales that result from customers using your app. A percentage of the revenue that results from purchases made by users of your app is shared with you.
We're referring to online purchases, made using the URLs returned from the API, such as the url field from the Products call.
We thought the details about monetization in the documentation were very clear. However, Retailigence explained in an email that the details of the implementation--for example, the percentage of revenue share--is negotiated with developers on a case-by-case basis.
In summary, Goodzer and Retailigence both provide a good local shopping API.
Goodzer's documentation is outstanding, and I found it very easy to get up and running with the Goodzer API. Retailigence packs more features, but the API can be confusing if you go it alone with just the documentation.
Thankfully, both companies provide prompt responses to emailed support questions.