Buy on Amazon ~ 0791413357An article of interest
Making use of the tools we offer
Data Feed API v3 - Access and Data Layout
This describes how to use version 3.x of the data feed. Version 2.x of the feed is still supported. Version 1.x of the feed is no longer supported in any way.
IMPORTANT: Starting with version 3.2, we have a new property and a new way of dealing with product images. Read about it here.
Accessing the data requires your account to have an active data feed. This switch can be turned on or off on the data feed page. This is also where you will be able to view your KEYCODE which is required to make calls to the feed.
Main changes from version 2.x to 3.x include (but not limited to)...
- The URL has changed /feed.php is now /feed/ (visit the data feed page for examples)
- The version number needs to be included in our request
- Much more control over the data you get back from your request
- New properties have been added with the flexibility for more to come over time
Calls to the data feed are made via HTTP GET or HTTP POST requests. There are only a few required parameters when making a call.
- keycode : 16 digit code (your app doesn't need to log in, it only needs the keycode)
- mode : json or xml
- V : 3 (if you omit this, the feed will fall back to v2.1)
Most other parameters are optional and they will alter the way data is returned to you and how your request is processed. You can also pass in your own values that you need carried through. Any parameter that the system doesn't recognize will be returned AS-IS in the status block. This can be handy in situations where you are pulling the data in an asyncronus manor and need extra information passed into your callback routine.
When performing a lookup...
- find : 8, 12 or 13 digits to search for (REQUIRED)
- comp : yes/no - if "no" skip the company lookup (defaults to "yes")
- pending : yes/no - if "yes" pending updates may be returned, otherwise only verified information is returned (defaults to "yes")
- get : what you want returned. "any" will return only the fields that have data and skip blank fields. "all" will return all available fields even if they are blank. You may also specify a specific list of fields to be returned and they will come back even if there is no data to fill them. (defaults to "any")
- has : you can provide any valid field name that you might use in the "get" property (except for all and any of course). when used, rather than getting back the actual field data, you get back a property with the same name prefixed with "has_" that contains either 0 (zero) or 1 (one) to let you know if data exists or not. This is most handy if you don't want to pull large blocks of data unless needed. For example the long description or company block.
- field_mod : yes/no - if "yes" the modified date for each field is returned in addition to the modified date of the over all product. (defaults to "no")
- search : fast/normal/deep - if this is omitted or any unexpected value, a normal search will be performed. In fast mode, we return only data we have on hand. In normal mode if we don't have any data on hand, we will do a quick search on a couple key websites to see if we can find the data which may add a small delay. In deep mode, we search as hard as we can to find what you are looking for when we don't already have the information on hand. In deep mode, it can take a several seconds or up to a minute to return data. Your app needs to be able to deal with this delay. (defaults to normal) NOTE: This is a premium feature. If you don't have a paid data feed, this will be forced to normal mode and any attempt to use fast or deep will be ignored.
- prettyjson : 1/0 - if 1 and only if you are returning JSON, your reults will be formatted in a more pretty way to make it more readable by humans. (also works when updating)
- barcodeExt: Either png or svg to set the format for the barcode image URL you want to get back (defaults to "png")
When updating data...
- update : 8, 12 or 13 digits to search for (REQUIRED)
- field : The product field to update (REQUIRED) [sorry, no company updates allows]
- value : The new value (REQUIRED) [will go into a pending area until validated]
- extra_id : Some fields use 2 fields to store the data. One being a numeric value and the second being a descriptor [such as a ounces, gallons, quarts] This extra value must match the list we keep in our database. You can include the text version of this extra information at the end of the "value" field but it still needs to match what we have. You can also split the value into two fields the way we do passing the number in the "value" field and the descriptor as an index id in this "extra_id" field. For more information, see the "get=extra" section just below.
- Only products information can be updated (no company info)
- Only update one field per request using this method. If you want to update many fields or even many products in one call, see the bulk update process.
- Update may be ignored if other pending updates exist
- Error result status is returned if updating a locked product
- To upload product images, see this blog article or use the bulk update process.
When deleting data...
- update : 8, 12 or 13 digits to search for (REQUIRED)
- delete : The product field to be deleted (REQUIRED)
There are some special "get" operations that need no other parameters. You would not use "find" or "update" when using these. Only use the "keycode", "mode" and "get" for these items. These operations are important because many of our elements are data driven and that data changes over time. We normally don't remove attributes or categories but we do often add to the collection.
- get=categories : This will return a list of all the product categories currently available on the system.
- get=attributes : This will return a list of all of the product attributes that are currently available. (more info)
- get=extra : This will return the extra values attached to fields. You can include include the field name field=???? if you want the extra information for a specific field. (more info)
The returned data can come back in JSON or XML format. In either case the structure of the data is the same. Because it is easier to read, we will be using XML to demonstrate the layout of the result. Here is the data layout. Notice that this is a complex object and some elements have child elements and some elements may be arrays with repeating content.
- status : This is returned after every call. It is important to investigate this section to make sure your request was properly processed.
- code : Always returned. Any value other than 200 indicates a problem.
- message : Always returned. This may be checked any time but should be checked when code is anything other than 200 to get more information about the problem.
- version : The current feed version being used to process your request. Only returned for "find" requests. This is not relevent for other requests.
- run : The number of seconds your request took. Only returned for "find" requests.
- find : What you were searching for during a "find" request.
- update : The product code you were trying to update during an "update" request.
- product : Only returned for "find" requests. What exactly is returned here depends on what you set the "get" parameter to in your call.
- EAN13 : The 13 digit EAN code
- UPCA : The 12 digit UPC-A code
- UPCE : The 8 digit UPC-E code
- ISBN10 : The 10 digit ISBN code (13 digit ISBN is the same as the EAN13)
- image : A url that points to an image of the product.
- modified : The date that the product was last modified.
- locked : 0/1 Indicates if this product can be modified or not.
- attributes : A collection attributes describing this product. The list of attributes can change and grow over time. Use the "get=attributes" request to see the full list
- field_mod : A collection of modification dates that indicate when each individual attribute was last modified. Only attributes with non-blank values will have modified dates. The elements in this collection are the same as those for the "attributes" collection.
- barcode : A collection of links to barcode images
- EAN13 : URL to the EAN13 barcode
- UPCA : URL to the UPC-A barcode
- UPCE : URL to the UPC-E barcode
- company : Only returned for "find" requests.
- name : Name of the company
- address : Address for the company
- phone : Telephone number for the company
- url : URL to the company web site
- logo : URL to the company logo
- locked : 0/1 Indicates if this company can be modified or not. Please note, you can not modify a company using the feed at this time.
- category : This array is only returned for get=categories requests.
- id : The unique numeric id for each category
- parent_id : The id of the category just above this one (if any)
- top_parent_id : The id of the root category this category belongs under
- category : The text name of this category
- cat_path : The text path showing all categories in the chain leading to this category
- attribute : This array is only returned for get=attributes requests. If you only want select attributes returned when you make your "find" request, the field_name parameter will identify which items can be placed in your "get=" parameter.
- field_name : The name of the data field
- group_name : The group that the data field belongs in
- title : The title of the field, often used as a label when displaying the data.
- data_type : The type of data stored in this field.
- data_type_description : A text description of the data type
- has_linked_text : 0/1 indicating if this field has two matching fields by the same name with "_text" and "_text_long" appended. These are often used as text versions of the data stored in the field. For example the category field will contain a number, _text will contain the text version of the category and _text_long will contain the entire category path.
- has_linked_extra : 0/1 indicating if this field has two matching fields by the same name with "_extra" and "_extra_long" appended. These are often used for measurements. For example, the field may contain the number 5.5 and the _extra field may contain "oz" and the _extra_long field may contain "ounces".
The easiest way to get the feel of the data is to make several requests using your web browser and ask for the data in XML format. Although JSON is often easier to work with in code, the XML output is often easier for people to read because of the nice markup tags that wrap around each element and the web browser will usually do a nice job of indenting to make it clear which elements are stored within other elements.