ItemMaster®

API Documentation

ItemMaster REST API v2

The ItemMaster API is a RESTful, resource-oriented, open-standards architecture that developers can use to work with ItemMaster maintained metadata and information. You can use just about any web language to access the API so long as it can make HTTPS requests and parse XML responses. The API adheres to REST standards. You reference particular resources by means of the URL path (the part of the URL after the host name).

The ItemMaster API is still in the early phases and will change based on data elements added to the schema as well as adding or removing different ways to extract the data. Every effort will be made to ensure 100% backwards compatibility of existing functionality.

Our images are free to use, but our servers are not setup for live linking. We ask that you do not link directly to our images. In order to provide you more control and eliminate the possibility of any issues that might interrupt your customer's access to the content, download the images, store them where you see fit, and link them appropriately.

API Documentation

An ItemMaster API request is an HTTP URL of the following form:

							https://api.itemmaster.com/v2/{service}?{parameters}
                        

Response Codes

The HTTP response should be checked after each success.

Status CodeReasonResponsibility
200 OKSuccessful request, no errorsNobody
400 Bad RequestThe API request was malformed, i.e. a required parameter was missing or a parameter value was invalid.Yours
403 ForbiddenHTTP Header credentials are missing or invalid.Yours
404 Not FoundThe API service does not existYours
405 Method Not AllowedThe API service does not allow a call to this URIYours
406 Not AcceptableYou have reached your daily limit for downloaded itemsYours
500 Internal Server ErrorThere was a bug in our code and the API call broke. If you see this, please let us know.Ours
503 Service UnavailableThe API server is down for temporary maintenance. When this occurs, try your call again in a few minutes.Ours

Service Calls

Manufacturer Search

Returns a listing of manufacturers (XSD) in the ItemMaster database.

Service:

                    			https://api.itemmaster.com/v2/manufacturer/{optional-path-parameter}
                            

Path parameter:

  • {manufacturerId} (optional) - manufacturer id to return data for single manufacturer (XSD)

Example

                    		$ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/manufacturer'
                 			<manufacturers>
                 				 <numberOfResults>2012</numberOfResults>
                 				 <resultsPerPage>2147483647</resultsPerPage>
                 				 <startIndex>0</startIndex>
                 				 <manufacturer id="a12137b1-3458-11e0-946b-005056957023">
                 				  <name>1-2-3 Gluten Free, Inc.</name>
                 				 </manufacturer>
                 				 <manufacturer id="45193851-6c5b-11e1-9afb-005056ab0051">
                 				  <name>14 Hands Winery</name>
                 				 </manufacturer>
                 			</manufacturers>
                            

Paging

                    		$ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/manufacturer?idx=1000'
                      <This will allow you to page through manufacturers 1000 at a time, starting from the 1000th manufacturer>
                            
                        $ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/manufacturer?idx=1000&limit=1000'
                      <This will show 1000 manufacturers at most, starting from the 1000th manufacturer>
                            

Brand Search

Returns a listing of brands (XSD) in the ItemMaster database.

Service:

                    			https://api.itemmaster.com/v2/brand/{optional-path-parameter}
                            

Path parameter:

  • {brandId} (optional) - brand id to return data for single brand (XSD)

Example

                    		$ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/brand'
                 			<brands>
                 				 <numberOfResults>3322</numberOfResults>
                 				 <resultsPerPage>2147483647</resultsPerPage>
                 				 <startIndex>0</startIndex>
                 				 <brand id="b79497d2-3458-11e0-946b-005056957023">
                 				  <name>1-2-3 Gluten Free, Inc.</name>
                 				 </brand>
                 				 <brand id="fde52ea2-e2dd-11e0-9852-005056957023">
                 				  <name>1-Day</name>
                 				 </brand>
                 			</brands>
                            

Paging

                    		$ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/brand?idx=1000'
                      <This will allow you to page through brands 1000 at a time, starting from the 1000th brand>
                            
                        $ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/brand?idx=1000&limit=1000'
                      <This will show 1000 brands at most, starting from the 1000th brand>
                            

Distributor Search

Returns a listing of distributors (XSD) in the ItemMaster database.

Service:

                                https://api.itemmaster.com/v2/distributor
                            

Example

                            $ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/distributor'
                            <distributors>
                                 <numberOfResults>3322</numberOfResults>
                                 <resultsPerPage>2147483647</resultsPerPage>
                                 <startIndex>0</startIndex>
                                 <distributor id="b79497d2-3458-11e0-946b-005056957023">
                                  <name>1-2-3 Gluten Free, Inc.</name>
                                 </distributor>
                                 <distributor id="fde52ea2-e2dd-11e0-9852-005056957023">
                                  <name>1-Day</name>
                                 </distributor>
                            </distributors>
                            

Paging

                        $ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/distributor?idx=1000'
                      <This will allow you to page through distributors 1000 at a time, starting from the 1000th distributor>
                            
                        $ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/distributor?idx=1000&limit=1000'
                      <This will show 1000 distributors at most, starting from the 1000th distributor>
                            

Item Search

Returns a listing of items (XSD) in the ItemMaster database. The data contains full HTTP URL values to the images to download. If you do not pass an itemId as a path parameter then at least one of the following request parameters MUST be present with a value (q, m, b, upc, since,before)

NOTE: You must pass one of the following parameters with a value to receive image urls for the requested items (pi, pip, ef, eip, epl, epf, epr, esi, allImg). See parameter information below for details regarding these parameters.

Service:

                    			https://api.itemmaster.com/v2/item/{optional-path-parameter}?{optional-request-parameters}
                            

Path parameter:

  • {itemId} (optional) - item id to return data for single item

Request parameter:

idxPagination: which item to start with (0-based). If not passed will be set to 0.Number
limitPagination: how many records to bring back.Number
qDescription: Retrieve all items that match the words in the descriptionString
mManufacturer Id: Retrieve all items for a particular manufacturerString
bBrand Id: Retrieve all items for a particular brandString
upcUPC Code: Retrieve all items for a particular UPC codeString
sinceUpdated Since Date: Return all items that have been updated since a particular date (inclusive). String (YYYYMMDD)
untilUpdated Until Date: Return all items that have been updated before a particular date (inclusive). String (YYYYMMDD)
piSpecifies if the planogram images returned should be the original (unedited) or the edited. Defaults to no images. String
Values:
  o - Original
  c - Edited
  b - Both
  none - None
ptgaSpecifies the file size for TGA-16 planogram images in kilobytes. Defaults to 100KB Number
Values:
  50 - (50KB)
  100 - (100KB)
pipThe resulting PPI of the planogram images. Specify only if you would like a different/lower PPI than the original image.Integer
efThe resulting format of the ecommerce images. String
Values:
  jpg, png, tif
eipThe resulting PPI of the ecommerce images. Specify only if you would like a different/lower PPI than the original image.Integer
epThe resulting size of the ecommerce planogram images. This parameter can be passed multiple times with different values to return multiple sizes for the image.
Note: Ecommerce images are square so passing a value of 150 will result in images of size 150x150.
Integer
Values:
  50, 100, 150
  200, 600, 900, 1000
eplThe resulting size of the ecommerce left image. This parameter can be passed multiple times with different values to return multiple sizes for the image.
Note: Ecommerce images are square so passing a value of 150 will result in images of size 150x150.
Integer
Values:
  50, 100, 150
  200, 600, 900, 1000
epfThe resulting size of the ecommerce front image. This parameter can be passed multiple times with different values to return multiple sizes for the image.
Note: Ecommerce images are square so passing a value of 150 will result in images of size 150x150.
Integer
Values:
  50, 100, 150
  200, 600, 900, 1000
eprThe resulting size of the ecommerce right image. This parameter can be passed multiple times with different values to return multiple sizes for the image.
Note: Ecommerce images are square so passing a value of 150 will result in images of size 150x150.
Integer
Values:
  50, 100, 150
  200, 600, 900, 1000
esiRequest scale image Boolean
Values:
  true, false
allImgRequest all additional images String
Values:
  Y, N
Default:
  N
vLimit to verified items Boolean
Values:
  true, false
profileLimit to record type (default complete) String
Values:
  complete
standard
listing
analytics

Example

 
                    		$ curl --header "username:xxx" --header "password:yyy" 'https://api.itemmaster.com/v2/item?idx=0&limit=500&epl=50&epl=100&epf=50&epf=100&ef=png'

<?xml version="1.0" encoding="UTF-8"?>
<items xmlns="http://www.itemmaster.com/item" start="0" count="7"
	total="7">
	<item id="0168ad60-da49-11e0-aa6d-005056957023" status="P">
		<name>3 Musketeers Chocolate Candy Bar</name>
		<marketingDescription>3 Musketeers&#174; Bars. 45% less fat. 2 to
			go. Whipped up, fluffy chocolate-on-chocolate taste. 45% less fat
			than average of the leading chocolate brands. A lighter way to enjoy
			Chocolate&#174;.</marketingDescription>
		<otherDescription>We value your questions or comments. Call
			1-800-551-0698 or visit us at www.3musketeers.com. Please save the
			unused product and wrapper. 6g fat per 47g serving vs. 12g average
			for leading chocolate brands. Big on chocolate, not on
			fat!&#174;. www.3musketeers.com. &#174;/&trade;)
			trademarks &#169;Mars, Incorporated.</otherDescription>
        <ecommerceDescription>ecommerce description</ecommerceDescription>
        <manufacturerEcommerceDescription>content+ ecommerce description</manufacturerEcommerceDescription>
		<upcs>
			<upc type="UPC">00040000006039</upc>
		</upcs>
		<categories>
			<category type="GS1" id="10000046">Chocolate/Sugar Candy Combination
				Confectionery</category>
		</categories>
		<created id="ItemMaster">2011-09-08T00:00:00.000-05:00</created>
		<lastUpdated id="d29a023d-bf8c-11e0-b129-005056957023">2011-11-02T00:00:00.000-05:00
		</lastUpdated>
		<media>
			<medium type="edited" view="A1C1" mimeType="image/tga"
				imageSource="ITEMMASTER" added="2011-10-25T00:00:00.000-05:00">
				<description>Planogram Front</description>
				<url>http://media.itemmaster.com/0/0/0/793/4c2a60bb-2812-4a4d-a11a-5b6b1e231c06.tga
				</url>
			</medium>
			<medium type="edited" view="A2C1" mimeType="image/tga"
				imageSource="ITEMMASTER" added="2011-10-25T00:00:00.000-05:00">
				<description>Planogram Left</description>
				<url>http://media.itemmaster.com/0/0/0/793/63543e5d-26ce-4aac-b88d-dc139320b884.tga
				</url>
			</medium>
			<medium type="edited" view="A3C1" mimeType="image/tga"
				imageSource="ITEMMASTER" added="2011-10-25T00:00:00.000-05:00">
				<description>Planogram Top</description>
				<url>http://media.itemmaster.com/0/0/0/793/52104ebc-5b47-4f65-9daa-4f41d5ddd612.tga
				</url>
			</medium>
			<medium type="edited" view="A7C1" mimeType="image/tga"
				imageSource="ITEMMASTER" added="2011-10-25T00:00:00.000-05:00">
				<description>Planogram Back</description>
				<url>http://media.itemmaster.com/0/0/0/793/9aed4ac4-7828-4fe2-a423-e444dea59299.tga
				</url>
			</medium>
			<medium type="edited" view="A8C1" mimeType="image/tga"
				imageSource="ITEMMASTER" added="2011-10-25T00:00:00.000-05:00">
				<description>Planogram Right</description>
				<url>http://media.itemmaster.com/0/0/0/793/f22f0dfc-bf0d-4b86-bf93-b9023f2cedef.tga
				</url>
			</medium>
			<medium type="edited" view="A9C1" mimeType="image/tga"
				imageSource="ITEMMASTER" added="2011-10-25T00:00:00.000-05:00">
				<description>Planogram Bottom</description>
				<url>http://media.itemmaster.com/0/0/0/793/1fdd93cd-0cb6-4623-a39c-cf1108bdfe8b.tga
				</url>
			</medium>
			</media>
		<packageData type="Item" approximation="true">
			<packageType id="b884ce0c-08f0-11de-abfb-1e0ad616ea54">BAR</packageType>
		</packageData>
		<products>
			<product sequence="1" id="006aec70-da49-11e0-aa6d-005056957023"
				type="">
				<description>3 Musketeers Chocolate Candy Bar</description>
				<brand id="0dde8c90-bc18-11df-b90a-005056957023">3 Musketeers</brand>
				<manufacturer id="d384d7b0-a566-11df-9431-005056957023">Mars Chocolate North America, LLC.
				</manufacturer>
				<warnings>
					<warning />
				</warnings>
				<grocery>
					<ingredients>Milk Chocolate (Sugar, Chocolate, Cocoa Butter, Skim
						Milk, Lactose, Milkfat, Soy Lecithin), Sugar, Corn Syrup,
						Hydrogenated Palm Kernel Oil and/or Palm Oil, less than 2% Cocoa
						Powder Processed with Alkali, Salt, Egg Whites, Artificial and
						Natural Flavors.</ingredients>
					<kosherCodes>
						<kosherCode />
						<kosherCode />
					</kosherCodes>
					<containerRefunds>
						<containerRefund>
                                                    <local>CA</local>
                                                    <amount>$0.1</amount>
						</containerRefund>
						<containerRefund>
                                                    <local>IL</local>
                                                    <amount>$0.15</amount>
						</containerRefund>
					</containerRefunds>
					<nutritions>
						<nutrition sequence="1">
							<numberOfServings>2</numberOfServings>
							<servingSizes>
								<servingSize type="other">
									<measure>1.0</measure>
									<uom>bar</uom>
								</servingSize>
							</servingSizes>
							<energy>200</energy>
							<totalFat uom="g" dailyPct="9" calories="60">6</totalFat>
							<saturatedFat uom="g" dailyPct="20" calories="">4
							</saturatedFat>
							<transFat uom="g">0</transFat>
							<cholesterol uom="mg" dailyPct="2">5</cholesterol>
							<sodium uom="mg" dailyPct="4">85</sodium>
							<carbohydrates uom="g" dailyPct="12">36</carbohydrates>
							<dietaryFiber uom="g">1</dietaryFiber>
							<sugars uom="g">31</sugars>
							<chromium uom="g">1</chromium>
							<folate uom="g">2</folate>
							<manganese uom="g">3</manganese>
							<pantothenicAcid uom="g">4</pantothenicAcid>
							<selenium uom="g">5</selenium>
							<vitaminK uom="g">6</vitaminK>
							<vitaminA uom="g">31</vitaminA>
							<vitaminC uom="g">1</vitaminC>
							<calcium uom="g">2</calcium>
							<iron uom="g">3</iron>
							<copper uom="g">4</copper>
							<folicAcid uom="g">5</folicAcid>
							<iodine uom="g">6</iodine>
							<magnesium uom="g">31</magnesium>
							<niacin uom="g">1</niacin>
							<vitaminE uom="g">2</vitaminE>
							<zinc uom="g">3</zinc>
							<phosphorous uom="g">4</phosphorous>
							<riboflavin uom="g">5</riboflavin>
							<thiamin uom="g">6</thiamin>
							<vitaminB12 uom="g">4</vitaminB12>
							<vitaminB6 uom="g">5</vitaminB6>
							<vitaminD uom="g">6</vitaminD>
							<protein uom="g" dailyPct="">1</protein>
							<dailyPercentOfVitaminA>0</dailyPercentOfVitaminA>
							<dailyPercentOfVitaminC>0</dailyPercentOfVitaminC>
							<dailyPercentOfCalcium>2</dailyPercentOfCalcium>
							<dailyPercentOfIron>0</dailyPercentOfIron>
							<dailyPercentOfChromium>1</dailyPercentOfChromium>
							<dailyPercentOfFolate>2</dailyPercentOfFolate>
							<dailyPercentOfManganese>3</dailyPercentOfManganese>
							<dailyPercentOfPantothenicAcid>4</dailyPercentOfPantothenicAcid>
							<dailyPercentOfSelenium>5</dailyPercentOfSelenium>
							<dailyPercentOfVitaminK>6</dailyPercentOfVitaminK>
						</nutrition>
					</nutritions>
				</grocery>
			</product>
		</products>
		<packageDistributor>
			<name>Mars Snackfood US, LLC</name>
			<address>Hackettstown, NJ 07840-1503 USA</address>
			<email />
			<phone>1-800-551-0698</phone>
			<url>www.3musketeers.com</url>
		</packageDistributor>
		<packageImporter>
			<name>Mars Snackfood US, LLC</name>
			<address>Hackettstown, NJ 07840-1503 USA</address>
			<email />
			<phone>1-800-551-0698</phone>
			<url>www.3musketeers.com</url>
		</packageImporter>
		<attributes />
	</item>
</items>