Responses

For simplicity, the API produces a single schema for both LookupRequest and SearchRequest.

ItemsResponse


{
  "code": string,
  "total": number,
  "offset": number,
  "items": [ {item}, ... ]
}

Item

Description of item attributes:

Name	type	description
ean	string	EAN-13, 13-digit European Article Number (aka. GTIN-13). This is the unique number we used to identify each item in our database. If it starts with 0, the rest 12-digit is the UPC (aka. UPC-A, GTIN-12), ex. 0885909456017.
title	string	Item title
upc	string	[optional] UPC-A, 12-digit Universal Product Code (aka. GTIN-12). If item’s EAN does not start with 0, there is no corresponding UPC-A code, ex. 6009705662678.
gtin	string	[optional] GTIN-14, 14-digit number used to identify trade items at various packaging levels. The contained trade item’s EAN or UPC can be derived from it. Ex. GTIN-14 20008236914225 contains 20-Pack of item with UPC 008236914221.
elid^*	string	[optional] eBay Listing ID, aka. item ID or item number. Item ID is 9 to 12 digits in length. If item is found on eBay.com, you can simply locate the item by `http://www.ebay.com/itm/[eLID]`.
description	string	Item description with length < 515.
brand	string	Brand name or manufacture name with length < 64.
model	string	Item model number with length < 32.
color	string	Item color with length < 32, ex. for clothing, shoes.
size	string	Item size with length < 32, ex. for clothing, shoes.
dimension	string	Item model number with length < 32.
weight	string	Item weight with length < 16.
category	string	Google product taxonomy, https://www.google.com/basepages/producttype/taxonomy.en-US.txt.
currency	string	currency of the lowest_recorded_price. Can be “USD”, “CAD”, “EUR”, “GBP”, “SEK”. Default “” means “USD”.
lowest_recorded_price	number	[optional] Lowest historical price of the item since tracked by our system. Not available for books.
highest_recorded_price	number	[optional] Highest historical price of the item since tracked by our system. Not available for books.
images	array	array of image urls.
offers	array	`offer` objects.
user_data	string	[optional] For user to correlate the response with original request. The same value with max length of 32 will be returned with the response if user set it in the request.

* Product and offers information from Amazon and eBay are not included in API response. eLID is served as a reference if the item was ever found on eBay.

Offer

Description of offer attributes:

Name	type	description
merchant	string	Online store name.
domain	string	Online store domain.
title	string	Item name marketed by the merchant.
currency	string	currency of the list_price & price. Can be “USD”, “CAD”, “EUR”, “GBP”, “SEK”. Default “” means “USD”.
list_price	number\|string	Original price from the store or empty string if not available.
price	number	Sale price.
shipping	string	“Free Shipping” or other shipping information if not free.
condition	string	“New” or “Used”
availability	string	Default “” means available or “Out of Stock”
link	string	Shop link of the item.
updated_t	number	unix timestamp of the offer was last updated.

ErrorResponse

Error responses are in a single schema too,


{
  "code": string,
  "message": string
}

HTTP status	code	description
400	INVALID_QUERY	Required parameters is missing in the request.
400	INVALID_UPC	Not a valid UPC code.
401	AUTH_ERR	For paid plan only, `user_key` in the request header can not be authenticated.
404	NOT_FOUND	No matched item was found or wrong endpoint path.
429	EXCEED_LIMIT	Exceed daily request limits. Please check your Plan for the daily limits. The `X-RateLimit-Limit` in the response header also indicates your daily request limit.
429	TOO_FAST	Request exceeds burst rate limit. Please check your Plan for the rate limit. If you hit this error code, your application must sleep for a short period before sending the next request. Otherwise the server would extend the blocking period from your next request.
429	HTTP_TOO_MANY_REQUESTS	Our bad. Please shoot us an email with your sample request and the time it happened.
50x	SERVER_ERR	Our bad. If the problem persists, please shoot us an email with your sample request and the time it happened.