The Explore API delivers on-package and enriched product data to Label Insight customers.
\nThe list of products and the attributes returned for each product is controlled through a unique API configuration. Each configuration is tied to a single Product Type/Category (ex: Food & Beverage, Cosmetics, Pet Food). The data available per product varies by Product Type due to industry regulations and other factors. By limiting each API configuration to a single Product Type, Label Insight can guarantee what the response data will look like and prevent customers from having to write additional logic to parse the data.
\nEach configuration is associated to a unique identifier (the configurationKey). Additionally, each customer will receive a unique identifier which identifies the customer (the x-api-key). The two identifiers work together and act similar to a username and password. The two identifiers must be provided on all requests.
The configurationKey is passed as a path variable while the x-api-key is passed as a request header. Examples are provided in this documentation.
We have a 10MB response size limit per API request. You may need to decrease your page sizes to avoid reaching this limit. For most customers we recommend starting with a page size of 10.
\nThe API currently does not support CORS requests.
\nThe API currently supports the GET method. The GET method is used to retrieve data only and will never cause an update or change to the underlying data.
\nThe API only supports JSON at this time.
\nIf you are receiving our data via a monthly scheduled export then you can access it at the following FTP host: outbound-ftp.labelinsight.com
\nIn order to encrypt and protect data in transit we require FTPS connections (https://en.wikipedia.org/wiki/FTPS).
\nIf a graphical FTP client is needed,we recommend using FileZilla. FileZilla is free and easy to use. https://filezilla-project.org.
\nUpon logging in to the server you will see the following directory structure:
\n files/\n yyyy_MM_data.zip\nMonthly exports will be added to the files directory in the format shown above.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Configurations and Product Types","slug":"configurations-and-product-types"},{"content":"Access Keys","slug":"access-keys"},{"content":"Limits","slug":"limits"},{"content":"Response Codes","slug":"response-codes"},{"content":"Scheduled Exports","slug":"scheduled-exports"}],"owner":"1700817","collectionId":"a36e15da-b292-47a8-b104-3b94725379a5","publishedId":"RW84qqKJ","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2018-05-15T20:29:45.000Z"},"item":[{"name":"v2 - Data Endpoints","item":[{"name":"All Products","id":"47274c0c-57e1-40f7-b9e0-f79adcf37707","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"{{gatewayApiKey}}"}],"url":"https://enterprise-li-api.labelinsight.com/api/v2/{{configurationKey}}/data","description":"This is the endpoint for iterating through all of the products that are in a configuration.
\nAs described above, a cursor must be used to iterate over the data. However, if you provide an incremented page number (starting at 0) in your requests, then the Explore API will perform some basic arithmetic to respond with convenience values such as first and last.
Returns a single product with the provided ID.
\n","urlObject":{"protocol":"https","path":["api","v2","{{configurationKey}}","data","id","{{id}}"],"host":["enterprise-li-api","labelinsight","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"460fa3f4-862d-42e7-9b2a-35f2c2cf28a7"},{"name":"Product by UPC","id":"172dbb4c-a71f-411a-8d36-cb0f580a04ea","request":{"method":"GET","header":[{"key":"x-api-key","value":"{{gatewayApiKey}}"}],"body":{"mode":"formdata","formdata":[]},"url":"https://enterprise-li-api.labelinsight.com/api/v2/{{configurationKey}}/data/upc/{{upc}}","description":"Returns a single product with the provided UPC.
\n","urlObject":{"protocol":"https","path":["api","v2","{{configurationKey}}","data","upc","{{upc}}"],"host":["enterprise-li-api","labelinsight","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"172dbb4c-a71f-411a-8d36-cb0f580a04ea"},{"name":"All Products Consolidated","id":"ab780833-c95d-49e0-a409-860ad4e1b6a9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","type":"text","value":"{{gatewayApiKey}}"}],"body":{"mode":"raw","raw":"{\n \"customerApiKeys\": [\n {{configurationKey}}\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://enterprise-li-api.labelinsight.com/api/v2/data","description":"This endpoint should be used if you have licensed multiple Product Types or Configurations from Label Insight.\nThis endpoint will return products only for the configurations provided in the request body.
\nThis endpoint allows customers to iterate over all of the products in a configuration. It uses the concept of a cursor to iterate over a page. Standard paging is not used.
\nA cursor is a marker to a specific spot in the data set, allowing us to maintain previous levels of performance while guaranteeing results aren’t skipped or duplicated. It also allows us to better leverage our search datastore for multiple use cases.
\nCursors are provided using the cursor request parameter. If none is sent then a default value is used which provides the equivalent of page 0. All responses will return a nextCursor field. In order to get the next \"page\" of data, the nextCursor provided in the most recent response should then be used as the cursor request paramenter in the next request to the Explore API.
You have reached the end of the data set when the nextCursor in the response provided by the API equals the cursor that was provided in the request.
Important Note: The cursor request parameter must be URL encoded. More information about URL encoding can be found here: https://en.wikipedia.org/wiki/Percent-encoding.
\nResponses are structured based on Product Type and other filtering options in the customer API configuration. Due to this variability, it is impossible to provide examples for every unique type of response. This documentation provides examples of responses common for all product types and sample json objects which are similar across different product types.
\nPlease note that the following table displays the fields that will always be available across all product types.
\nExample Product:
\n {\n \"brand\": \"YOPLAIT\",\n \"distributor\": \"YOPLAIT USA, INC.\",\n \"importedBy\": \"\",\n \"manufacturer\": \"\",\n \"netWeight1\": \"6 oz\",\n \"netWeight2\": \"170 g\",\n \"netWeight3\": \"\",\n \"productSize\": \"6 oz\",\n \"productSize2\": \"170 g\",\n \"productSize3\": \"\",\n \"productTitle\": \"ORIGINAL LOW FAT YOGURT\",\n \"productId\": 4646052,\n \"productType\": \"Food\",\n \"upc\": \"070470464916\",\n \"dateCreated\": \"2018-04-16T00:00:00.000+0000\",\n \"dateLive\": \"2018-05-03T18:22:11.000+0000\"\n}\nWe treat Specs in a very dynamic fashion - we are constantly adding new \"standard\" Specs and also custom ones for our customers. We treat Specs as an object (map) and a specific Spec name is used as a key within the object.
\n\"specs\": {\n \"allergensAndIntolerances\": [\n {\n \"segment\": \"Allergens\",\n \"characteristic\": \"Egg Containment\",\n \"value\": \"Not Applicable\"\n },\n {\n \"segment\": \"Allergens\",\n \"characteristic\": \"Fish Containment\",\n \"value\": \"Fish Free\"\n }\n ]\n}\nBelow are just a few examples of other data that we can provide via the API.
\nMust be the x-api-key provided to you which uniquely identifies which customer you are.
\n"}],"url":"https://enterprise-li-api.labelinsight.com/api/v2/delta/:configurationKey?to&from&size&content&page","description":"This endpoint should be used if you have licensed or receive one Product Type or only one Configuration from Label Insight.\nThis endpoint will return delta events only for the configuration provided as a path variable, regardless of how many configurations or product types you have licensed.\nIf you have multiple configurations and would like to receive a consolidated feed of delta events for all configurations, please see the POST endpoint below.
\nReturns delta events ending at this date. Format yyyy-mm-dd. This field is required.
\n","type":"text/plain"},"key":"to","value":null},{"description":{"content":"Returns delta events starting from this date. Format yyyy-mm-dd. This field is required.
\n","type":"text/plain"},"key":"from","value":null},{"description":{"content":"The number of delta events to return.
\n","type":"text/plain"},"key":"size","value":null},{"description":{"content":"The type of Delta content you are requesting. Valid options are: PATCH, PRODUCT. Both delta types are returned by default.
\nPRODUCT: provides a copy of the product as it existed at the specific time the delta event occurred
\nPATCH: (DEPRECATED) provides a JSON patch (https://tools.ietf.org/html/rfc6902) of the exact delta
\n","type":"text/plain"},"key":"content","value":null},{"description":{"content":"The page number of the request. Default is 0.
\n","type":"text/plain"},"key":"page","value":null}],"variable":[{"description":{"content":"The unique identifier of the configuration that is being requested.
\n","type":"text/plain"},"type":"string","value":"","key":"configurationKey"}]}},"response":[],"_postman_id":"3bca173e-3b16-47b3-ac20-126c6f0a8619"},{"name":"Get Consolidated Deltas","id":"3d1df238-3577-4ba1-bd8b-bca2a23b0338","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"description":"Must be the x-api-key provided to you which uniquely identifies which customer you are.
\n","key":"x-api-key","value":""},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"configurationKeys\": [\n \"CONFIGURATION_KEY_1\",\n \"CONFIGURATION_KEY_2\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://enterprise-li-api.labelinsight.com/api/v2/delta?to&from&size&content&page","description":"This endpoint should be used if you have licensed multiple Product Types or Configurations from Label Insight.\nThis endpoint will return delta events only for the configurations provided in the request body.
\nReturns delta events ending at this date. Format yyyy-mm-dd. This field is required.
\n","type":"text/plain"},"key":"to","value":null},{"description":{"content":"Returns delta events starting from this date. Format yyyy-mm-dd. This field is required.
\n","type":"text/plain"},"key":"from","value":null},{"description":{"content":"The number of delta events to return.
\n","type":"text/plain"},"key":"size","value":null},{"description":{"content":"The type of Delta content you are requesting. Valid options are: PATCH, PRODUCT. Both delta types are returned by default.
\nPRODUCT: provides a copy of the product as it existed at the specific time the delta event occurred
\nPATCH: (DEPRECATED) provides a JSON patch (https://tools.ietf.org/html/rfc6902) of the exact delta
\n","type":"text/plain"},"key":"content","value":null},{"description":{"content":"The page number of the request. Default is 0.
\n","type":"text/plain"},"key":"page","value":null}],"variable":[]}},"response":[],"_postman_id":"3d1df238-3577-4ba1-bd8b-bca2a23b0338"}],"id":"1453d182-cfcf-43f2-ab39-a6dbdcf701b9","description":"The Delta API provides a mechanism for tracking what products have been modified over a period of time. The API provides the information necessary to track product-level changes without having to re-ingest the entire API. Further, the Delta API provides the most accurate way to know when products have changed since last ingestion.
\nIndicates that a new productId was created in the Label Insight database. There are typically two scenarios where this would occur: 1) a new UPC was submitted to Label Insight; 2) a newer version of an existing UPC was submitted to Label Insight. In the second scenario, the “ADDED” event would have a corresponding “REMOVED” event for the older productId.
\nIndicates that there has been a change to an existing UPC within our system that did not result in the addition of a new productId. The JSON Patch feature can be used to determine the exact modification.
\nIndicates that a productId has been removed from the Label Insight database. The most common scenarios where this would occur are: 1) a newer version of an existing UPC was submitted to Label Insight which resulted in the addition of a new productId and the removal of an older productId; 2) an existing UPC was discontinued by the manufacturer
\n","event":[{"listen":"prerequest","script":{"id":"c84cd7fd-a0c5-4643-9b2d-bc29719f629d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"5615b949-35bb-4636-8032-d46c63ba3c94","type":"text/javascript","exec":[""]}}],"_postman_id":"1453d182-cfcf-43f2-ab39-a6dbdcf701b9"},{"name":"Configuration Delta API","item":[{"name":"Get Configuration Deltas","id":"683c22d9-fa34-47dd-84f9-307299533a3f","request":{"method":"GET","header":[{"key":"x-api-key","value":"","description":"Must be the x-api-key provided to you which uniquely identifies which customer you are.
\n"}],"body":{"mode":"formdata","formdata":[]},"url":"https://enterprise-li-api.labelinsight.com/api/data-contract/delta/:configurationKey?from","description":"Returns configuration delta events starting from this date. Format yyyy-mm-dd.
\n","type":"text/plain"},"key":"from","value":null}],"variable":[{"description":{"content":"The unique identifier of the configuration that is being requested.
\n","type":"text/plain"},"type":"any","value":"","key":"configurationKey"}]}},"response":[],"_postman_id":"683c22d9-fa34-47dd-84f9-307299533a3f"}],"id":"606fd7c7-6424-4833-870c-e3c0b68395b0","description":"The Delta API is great for knowing when a specific attribute on a specific product has been modified. However, this does not account for when new attributes are added to your data and all products are modified with new data. The Configuration Delta API programmatically solves the problem of knowing when all data has been updated.
\nThis API will provide a history of the changes to a specific Explore API Configuration. For example, if it your API is created on day one and then new attributes are added on day two, the API would provide a CREATED and a MODIFIED event. It is also possible to receive an UNMODIFIED event which indicates that an administrative change occurred with no changes made to the data delivered by the API - UNMODIFIED events can effectively be ignored.
\nThis API can be called at any time interval and the consumers can trigger a full reingestion of data from the Explore API if they see a new MODIFIED since the last EVENT that they have tracked.
\n","event":[{"listen":"prerequest","script":{"id":"16d9a524-cd39-4c37-b9a8-3855b3ac931d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"847a2cdb-5b9e-43ac-8d97-6e2065e111cd","type":"text/javascript","exec":[""]}}],"_postman_id":"606fd7c7-6424-4833-870c-e3c0b68395b0"}],"event":[{"listen":"prerequest","script":{"id":"11f8f14f-a57a-41eb-8d18-30792d99aa4d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"a4080f08-5f62-49df-8483-b1d11ba46e4a","type":"text/javascript","exec":[""]}}],"variable":[{"value":""}]}