Version 0.1

Documentation

Contents

Introduction 

Goodzer API will enable your mobile or web application to find products in local stores all over the U.S. Goodzer provides the most comprehensive coverage out there with more than 2,500,000,000 inventory items in 500,000 store locations.

The API is based on RESTful architecture. All API methods are accessible via HTTP GET requests and return responses in JSON format.

Notice: This API is in its early stage of development (version 0.1). As an early adopter please be prepared to face some potential teething troubles. You can help us improving the API by providing your feedback.

Authentication 

To begin using the Goodzer API, first you need to sign up for an API key. It is free and will take only a couple of minutes. Your API key must be included in every API request as a query parameter named apiKey. The usage of the API is subject to daily limits.

Data model 

Location
id
store_id
name
address
city
state
zipcode
lat
lng
phone
Store
id
name
website
realtime_availability
Product
id
store_id
title
price
url
image

Methods 

Search stores 

http://api.goodzer.com/products/v0.1/search_stores/

Returns a list of stores that sell products matching the search query and have locations within specified radius.

For each store the method returns up to 5 products and up to 3 locations. You can retrieve additional products by using Search in store method, and additional locations by using Store locations method.

ParameterRequiredDescriptionDefaultExample
queryYesSearch queryv-neck sweater
latYesLatitude40.714353
lngYesLongitude-74.005973
radiusNoSearch radius (in miles)10.05.0
offsetNoNumber of results to skip010
sortingNoSorting moderelevancerelevance
distance
price_asc
price_desc
priceRangeNoPrice filter30.0:120.0
apiKeyYesYour API key

Sample request:

http://api.goodzer.com/products/v0.1/search_stores/?query=v-neck+sweater&lat=40.714353&lng=-74.005973
&radius=5&priceRange=30:120&apiKey=<Your_API_key>

Sample response:

{
    "status": "ok",
    "stores_found": 71,
    "stores": [
        {
            "id": "Kq0VgUCg",
            "name": "Men's Wearhouse",
            "website": "http://menswearhouse.com/",
            "locations_found": 6,
            "locations": [
                {
                    "id": "fK1qKd45",
                    "address": "115 Broadway",
                    "city": "New York",
                    "state": "NY",
                    "zipcode": "10006",
                    "lat": 40.708616,
                    "lng": -74.011028,
                    "phone": "(212) 233-0675"
                },
                {
                    "id": "qqLK0dZR",
                    "address": "650 Avenue of the Americas",
                    "city": "New York",
                    "state": "NY",
                    "zipcode": "10010",
                    "lat": 40.741185,
                    "lng": -73.994079,
                    "phone": "(212) 675-2608"
                },
                ...
            ],
            "products_found": 64,
            "realtime_availability": false,
            "products": [
                {
                    "id": 1583262223,
                    "title": "Pronto Blue V-Neck Sweater, Pomegranite",
                    "price": 39.99,
                    "url": "http://www.menswearhouse.com/shop/p_pronto-blue-v-neck-sweater,-pomegranite_12001_700000551_12751_700134461_-1_700000551_____noSpecialSizes",
                    "image": "http://img.goodzer.com/peregimator/?size=medium&valign=center&sign=007352e3&image=http%3A//images.menswearhouse.com/is/image/TMW/602V_PRONTO_BLUE_SWEATERS_POMEGRANITE_MAIN%3F%24grid%24"
                },
                {
                    "id": 1583259803,
                    "title": "Pronto Blue V-Neck Sweater, Olive",
                    "price": 44.99,
                    "url": "http://www.menswearhouse.com/shop/p_pronto-blue-v-neck-sweater,-olive_12001_700000551BT_12751_700134459_-1_700000551BT_____BIG+%26+TALL",
                    "image": "http://img.goodzer.com/peregimator/?size=medium&valign=center&sign=98f493a0&image=http%3A//images.menswearhouse.com/is/image/TMW/602V_PRONTO_BLUE_SWEATERS_OLIVE_MAIN%3F%24grid%24"
                },
                ...
            ]
        },
        {
            "id": "KA00VSdX",
            "name": "J Crew",
            "website": "http://jcrew.com/",
            ...
        },
        ...
    ]
}

Search locations 

http://api.goodzer.com/products/v0.1/search_locations/

Returns a list of store locations within defined radius that sell products matching the search query. A typical use case for this method is displaying markers on a map. If there are more than 500 locations, only the closest 500 will be returned.

You can retrieve additional properties (such as address, phone number) by using Location details method.

ParameterRequiredDescriptionDefaultExample
queryYesSearch queryv-neck sweater
latYesLatitude40.714353
lngYesLongitude-74.005973
radiusNoSearch radius (in miles)10.05.0
priceRangeNoPrice filter30.0:120.0
apiKeyYesYour API key

Sample request:

http://api.goodzer.com/products/v0.1/search_locations/?query=v-neck+sweater&lat=40.714353&lng=-74.005973
&radius=5.0&priceRange=30:120&apiKey=<Your_API_key>

Sample response:

{
    "status": "ok",
    "locations": [
        {
            "id": "fq0UPA6f",
            "store_id": "VVfqWmHv",
            "name": "Macy's",
            "lat": 40.750338,
            "lng": -73.988645

        },
        {
            "id": "fqLVVyZn",
            "store_id": "Kq0VgUCg",
            "name":"Men's Wearhouse",
            "lat": 40.747943,
            "lng": -73.984717
        },
        {
            "id": "AVApjqaJ",
            "store_id": "VVfqWmHv",
            "name": "Macy's",
            "lat": 40.725897,
            "lng": -74.038921
        },
        ...
    ]
}

Search in store 

http://api.goodzer.com/products/v0.1/search_in_store/

Returns a list of products from a specified store matching the search query.

ParameterRequiredDescriptionDefaultExample
storeIdYesStore IDfAfVfDCd
queryYesSearch queryipad case
offsetNoNumber of results to skip010
sortingNoSorting moderelevancerelevance
price_asc
price_desc
priceRangeNoPrice filter20.0:50.0
apiKeyYesYour API key

Sample request:

http://api.goodzer.com/products/v0.1/search_in_store/?storeId=fAfVfDCd&query=ipad+case&priceRange=20:50
&apiKey=<Your_API_key>

Sample response:

{
    "status": "ok",
    "realtime_availability": true,
    "products_found": 199,
    "products": [
        {
            "id": 1573967503,
            "title": "Harley-Davidson - Envelope Case for Apple iPad, iPad 2 and iPad (3rd Generation) - Black",
            "price": 34.99,
            "url": "http://www.bestbuy.com/site/Harley-Davidson+-+Envelope+Case+for+Apple%AE+iPad%AE%2C+iPad+2+and+iPad+(3rd+Generation)+-+Black/5422949.p?id=1218643212507&skuId=5422949&cmp=RMX&ky=2nOYnsgAdnUUUygixM6IZsxTJF3fsquqM",
            "image": "http://img.goodzer.com/peregimator/?size=medium&valign=center&sign=d4e70e4e&image=http%3A//images.bestbuy.com/BestBuy_US/images/products/5422/5422949_sc.jpg"
        },
        {
            "id": 1573970162,
            "title": "Samsonite - Shuttle Case for Apple iPad, iPad 2 and iPad (3rd Generation) - Black/White",
            "price": 39.99,
            "url": "http://www.bestbuy.com/site/Samsonite+-+Shuttle+Case+for+Apple%AE+iPad%AE%2C+iPad+2+and+iPad+(3rd+Generation)+-+Black/White/5763475.p?id=1218692161151&skuId=5763475&cmp=RMX&ky=2nOYnsgAdnUUUygixM6IZsxTJF3fsquqM",
            "image": "http://img.goodzer.com/peregimator/?size=medium&valign=center&sign=9ac997a0&image=http%3A//images.bestbuy.com/BestBuy_US/images/products/5763/5763475_sc.jpg"
        },
	...
    ]
}

Location details 

http://api.goodzer.com/products/v0.1/location_details/

Returns location details by location ID.

ParameterRequiredDescriptionDefaultExample
locationIdYesLocation IDVKW3QQKA
apiKeyYesYour API key

Sample request:

http://api.goodzer.com/products/v0.1/location_details/?locationId=VKW3QQKA&apiKey=<Your_API_key>

Sample response:

{
    "status": "ok",
    "location": {
        "id": "VKW3QQKA",
        "store_id": "fqKVKNVX",
        "name": "Apple",
        "address": "767 5th Ave",
        "city": "New York",
        "state": "NY",
        "zipcode": "10153",
        "lat": 40.763995,
        "lng": -73.973123,
        "phone": "(212) 336-1440"
    }
}

Store locations 

http://api.goodzer.com/products/v0.1/store_locations/

Returns a list of locations of a particular store within defined radius. You can retrieve up to 50 closest locations.

ParameterRequiredDescriptionDefaultExample
storeIdYesStore IDKA00VSdX
latYesLatitude40.714353
lngYesLongitude-74.005973
radiusNoSearch radius (in miles)10.05.0
offsetNoNumber of results to skip010
limitNoMaximum number of results5015
apiKeyYesYour API key

Sample request:

http://api.goodzer.com/products/v0.1/store_locations/?storeId=KA00VSdX&lat=40.714353&lng=-74.005973
&radius=5&apiKey=<Your_API_key>

Sample response:

{
    "status": "ok",
    "locations_found": 6,
    "locations": [
        {
            "id": "fK1qKd45",
            "address": "115 Broadway",
            "city": "New York",
            "state": "NY",
            "zipcode": "10006",
            "lat": 40.708616,
            "lng": -74.011028,
            "phone": "(212) 233-0675"
        },
        {
            "id": "qqLK0dZR",
            "address": "650 Avenue of the Americas",
            "city": "New York",
            "state": "NY",
            "zipcode": "10010",
            "lat": 40.741185,
            "lng": -73.994079,
            "phone": "(212) 675-2608"
        },
        ...
    ]
}

Product Availability 

http://inventory.goodzer.com/products/v0.1/product_availability/

Returns in-store availability for a specified product in specified locations. You can retrieve availability information for up to 10 locations. This method works only for stores that have positive realtime_availability property. Possible availability values: in (in stock), out (out of stock), and unknown (status is temporarily unavailable).

ParameterRequiredDescriptionExample
productIdYesProduct ID123456789
locationIdsYesLocation IDs (comma-separated values)KV0jAidH,AAKEVdmW
apiKeyYesYour API key

Sample request:

http://inventory.goodzer.com/products/v0.1/product_availability/?productId=<Product_ID>&locationIds=KV0jAidH,AAKEVdmW,
0AVPAUEu,AqfZVXwB,AAfZAT6k,0VKZWKgD,VKKEqFH9&apiKey=<Your_API_key>

Sample response:

{
    "status": "ok",
    "availability": {
        "AAKEVdmW": "in",
        "AqfZVXwB": "out",
        "AAfZAT6k": "out",
        "VKKEqFH9": "out",
        "KV0jAidH": "unknown",
        "0VKZWKgD": "in",
        "0AVPAUEu": "out"
    }
}

Getting help

Having trouble? We'd like to help! You may find an answer to your question in our FAQ, or submit a support request.