Categories API BOM Tool FAQ Octopart for Business

Datafeed Format

The Octopart Datafeed Format is the format manufacturers and distributors must use to send us data.

Every file must have a header row that conforms to the values defined in supported column headers. Each row after the header row represents a single part and its corresponding information.

The following is a detailed explanation of our datafeed format. If you're having trouble creating a datafeed file, please see Advanced Troubleshooting or send us an email (contact@octopart.com).

Requirements

Here are the basic requirements for each file:

  • The file must be either tab-delimited (.tsv), comma-separated (.csv), or Excel (.xls or .xlsx)
  • The first line of the file must be the header row and must include the following column headers at minimum: manufacturer, mpn, sku, distributor-url
  • Each row after the header row represents a single part and its corresponding information
  • The column headers must match those listed below. Files containing unsupported or misspelled header values will be rejected
  • Each row must contain the exact same number of fields as the header
  • All URLs must start with "http://" or "https://"
  • For plain-text delimited files, field values containing double quotation mark (") characters must be properly escaped (RFC 4180, page 2)
  • Field values must not include unescaped newline or unescaped delimiter characters

Example Datafeeds

Here are some example datafeed files to help you build your own:

Supported Column Headers

Column Header Description Example(s) Required?
manufacturer The full name of the manufacturer or brand.
General Devices
 yes
mpn The manufacturer's part number.
TLC274AID
 yes
sku The distributor's SKU. It may be identical to the manufacturer's part number if a separate sku is not used.
123-456-AB
 required for distributors
distributor-url A link to the distributor's page where the part is available for purchase.
http://example.com/buy/TLC274AID.html
 required for distributors
eligible-region (ISO 3166-1 alpha-2) or (ISO 3166-2) code indicating country or country & subdivision for which this offer is eligible.

ISO 3166-1 alpha-2 codes specify the country and are two characters in length.

ISO 3166-2 codes comprise an ISO 3166-1 alpha-2 country code, followed by hyphen, followed by a 3-character country subdivision identifier:
  {ISO 3166-1 code}-{3-character subdivision code}

Search for code »
US
US-NY
 recommended for distributors
quantity The number of pieces available for immediate shipment, or one of the following negative code values:

-1 : Non-stocked
-2 : In Stock
-3 : Unknown
-4 : RFQ
4000
-1
0
-4
 recommended for distributors
multipack-quantity Custom quantity or amount of MPN(s) per SKU as configured or packaged by the distributor.

Format: {VALUE}::{UNIT}, where {VALUE} is a number and {UNIT} is the name of the unit, or just {VALUE} if the value indicates "pieces" or "items".
1000
10::yards
4::kilograms
 required if applicable
price-break-1 The first price break quantity.
2
 recommended for distributors
price-{CUR}-1 The unit price at the first price break where {CUR} is the 3-letter alphabetic currency code (http://www.iso.org/iso/home/standards/currency_codes.htm). Header examples: "price-usd-1", "price-eur-1", "price-cny-1"
Do not include currency symbols (eg. $) in the price value.
0.45
 recommended for distributors
price-break-2 The second price break quantity. Add additional price breaks by adding more numbered price-break headers.
100
 optional for distributors
price-{CUR}-2 The unit price at the second price break. Add additional prices by adding more numbered price-{CUR} headers.
0.35
 optional for distributors
price-break-reference Use this field for quoting prices at custom quantities or amounts. The value of this field will become the reference value for a price-break quantity value of "1". By default, the price-break quantity value is assumed to reference a quantity of SKUs.

Format: {VALUE}::{UNIT}, where {VALUE} is a number and {UNIT} is the name of the unit.
10::yards
4::kilograms
 optional for distributors
description A description of the part.
The TLC274AID is a precision quad operational amplifier. It is a general purpose amplifier designed for latch-up immunity.
 recommended
attributes The Attributes column is where most of the technical specifications (specs) of a part are placed. These specs are listed as Key-Value pairs in a JSON dictionary. Each type of spec has different properties that should be considered. The units for the specs MUST be placed in the "value" part of the K-V pair.

Spec type How it is processed Example(s)
Text In rare cases, "spec_text" is just passed through to the website. But usually, "spec_text" is compared against a list of valid_values. If "spec_text" does not match a valid_value, it will be ignored.

Format:
"spec_name" : "spec_text"
"rohs_compliant" : "yes"
Number (dimensionless) This spec does NOT have a unit definition. Therefore whatever number is in the value will be passed through to the website.

Format:
"spec_name" : "spec_number"
"number_of_pins" : "14"
Number with units This spec DOES have a unit definition. Therefore when the spec is processed, if a valid unit is not found, the spec will be ignored.

Format:
"spec_name" : "spec_number + spec_unit"
"supply_voltage" : "3.3 volts"
Spec with metadata Currently lifecycle_status is the only spec that we support with metadata. In the future, we will add factory_lead_days, and probably others. The requirements for formatting are very rigid. Contact Octopart with any questions.

Format:
"spec_name" : {"metadata": {"metadata_name": "metadata_value"}, "value" : "spec_value"}
"lifecycle_status": {"metadata": {"observation_date": "YYYY-MM-DD"}, "value": "PRODUCTION"}
List This is a spec that can have more than a single value for a part, displayed as a comma delimited list.

Format:
"spec_name" : "value1, value2, value3, … valueN"
"Interface" : "I2C, I2S, UART, USB"
Range This spec type is not yet supported.

Format:
"spec_name" : "spec_num1 to spec_num2 + spec_unit"
"supply_voltage" : "3.3 to 5 volts"
Unsupported Specs in the Attributes Column

Specs that are defined as a RANGE between 2 numbers are not yet implemented.
Examples: "-40C to 85C", "3.3V - 5V"

Specs that have a "test condition" specified are not yet implemented.
Examples: "200 ohms @ 100MHz", "25cfm @ 12V"

Specs that are a combination of several specs are not yet implemented.
Examples: "L x W x H", "14 x 10 x 3 mm"
{"automotive": "No", "centroid_not_specified": "No", "composition": "Thin Film", "height": "0.26mm", "ipc_land_pattern_name": "RESC6030X23", "lead_free": "Yes", "name": "RES Thin Film, 3.24k\u03a9, 0.1%, 0.05W, 25ppm/\u00b0C, 0201", "package": "0201", "power_rating": "0.05W", "prefix": "R", "resistance": "3.24k\u03a9", "rohs": "Yes", "series": "TFCR", "temperature_coefficient": "25ppm/\u00b0C", "temperature_range_high": "+125\u00b0C", "temperature_range_low": "-55\u00b0C", "tolerance": "0.1%", "lifecycle_status": {"metadata": {"observation_date": "2020-05-20"}, "value": "Active"}}
 recommended
category The category field describes the position of the part in a larger hierarchy. Each category node should be separated by '>>'.
semiconductors >> op-amps >> low noise op-amps
 recommended
manufacturer-url A link to the manufacturer's webpage describing this part.
http://example.com/products/TLC274AID.html
 recommended
evalkit-url A link to a webpage containing Evaluation Kit info.
http://example.com/evalkits/TLC274AID.html
 recommended
freesample-url A link to a webpage containing information about how to obtain free samples of this part.
http://example.com/samples/TLC274AID.html
 recommended
datasheet-url A link to download the datasheet for this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. datasheet-url-1, datasheet-url-2, etc.)
http://example.com/datasheets/TLC274AID.pdf
 recommended
image-url A link to download an image of this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. image-url-1, image-url-2, etc.)
http://example.com/images/TLC274AID.jpg
 recommended
symbol-footprint-url A link to download a CAD/EDA file for this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. symbol-footprint-url-1, symbol-footprint-url-2, etc.)
http://example.com/symbols/TLC274AID_Symbol.sym
 recommended
application-note-url A link to download an Application Note for this part. Must be JSON-encoded object string that includes 'url' and at least one of ['title', 'description'].

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. application-note-url-1, application-note-url-2, etc.)
{"url": "http://example.com/appnotes/TLC274AID_Application_Note.pdf", "title": "Use our parts"}
 recommended
technical-drawing-url A link to download a 2D Technical/Mechanical Drawing of this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. technical-drawing-url-1, technical-drawing-url-2, etc.)
http://example.com/drawings/TLC274AID_Technical_Drawing.pdf
 recommended
3d-model-url A link to download a 3D CAD model of this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. 3d-model-url-1, 3d-model-url-2, etc.)
http://example.com/cad/TLC274AID_3D_Model.prt
 recommended
instruction-sheet-url A link to download an Instruction Sheet/Manual for this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. instruction-sheet-url-1, instruction-sheet-url-2, etc.)
http://example.com/docs/TLC274AID_Instructions.pdf
 recommended
rohs-statement-url A link to download a RoHS statement for this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. rohs-statement-url-1, rohs-statement-url-2, etc.)
http://example.com/compliance/TLC274AID_RoHS_Statement.pdf
 recommended
materials-sheet-url A link to download a Materials statement or declaration for this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. materials-sheet-url-1, materials-sheet-url-2, etc.)
http://example.com/compliance/TLC274AID_Materials.pdf
 recommended
reach-statement-url A link to download a REACH compliance statement for this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. reach-statement-url-1, reach-statement-url-2, etc.)
http://example.com/compliance/TLC274AID_REACH.pdf
 recommended
conflict-mineral-statement-url A link to download a Conflict Minerals statement or declaration for this part.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. conflict-mineral-statement-url-1, conflict-mineral-statement-url-2, etc.)
http://example.com/compliance/TLC274AID_Conflict_Minerals.pdf
 recommended
simulation-model-url A link to download an Simulation Model for this part. Must be JSON-encoded object string that includes 'url' and 'description'.

Multiple instances of this header can be provided for a single part by appending an index value to the header in the format: "-#" where "#" is a unique index number (eg. simulation-model-url-1, simulation-model-url-2, etc.)
{"description" : "PSPICE", "url" : "http://example.com/simulation/TLC274AID.ckt"}
 recommended for manufacturers, optional for distributors
moq Minimum order quantity.
100
 recommended for distributors
order-multiple Minimum multiple quantity in which this part must be ordered.
1
 recommended for distributors
on-order-quantity Number of units that are currently on order from the manufacturer.
2000
 recommended for distributors
on-order-eta Expected date of arrival for quantity currently on order from the manufacturer.

Format: YYYY-MM-DD, where YYYY = 4-digit year, MM = 2-digit month, DD = 2-digit day.
2012-11-01
 recommended for distributors
packaging The type of packaging in which this part is delivered.
cut tape
 recommended
factory-lead-days Number of days required for the distributor to procure additional stock of this part from its manufacturer.
14
 recommended
factory-pack-quantity Typical package size the distributor receives from the manufacturer.
24000
 recommended
datecode Manufacture date of stock.

Format: YYYY-MM-DD, where YYYY = 4-digit year, MM = 2-digit month, DD = 2-digit day.
2012-07-04
 recommended for brokers

Integration with Google Analytics

Each month, Octopart will provide you with the part number and manufacturer of each unique click, along with the time that the click occurred. However, many distributors want to compare this to the direct traffic and organic (search engine) referrals their website is receiving. To help with this, we recommend using Google Analytics to create a custom Octopart campaign. This will allow you to track your Octopart traffic, see how Octopart compares to any AdWords or other Analytics campaigns, better understand the users that are referred from Octopart (popular parts/pages, some information about visitors, single page viewers, etc.), and best of all it’s free!

Use Google’s URL builder to create custom URLs (or add the custom parametric tag to your existing URLs), and Google Analytics will begin tracking all referrals made from Octopart. See our example below!

This will help to understand the traffic you receive from Octopart. However there are several additional factors to consider when creating your Distributor-URLs.

Google Analytics uses 'visits' to tabulate that statistic, whereby Octopart uses 'clicks.'  It is possible to receive more than one 'click' from Octopart that Google Analytics would consider a 'visit.' Google has a good article that describes the difference between clicks and visits.

Also, Octopart uses HTTPS, which is the secure version of HTTP. The ‘referrer’ data is dropped whenever a refer is made from an HTTPS page (Octopart) to a non-secure HTTP page (the product page on your site). See this description of direct traffic analysis.

Advanced Troubleshooting

Still running into issues formatting your datafeed? Here are some steps to troubleshoot why your datafeed has failed:

  • Check your headers

    Often times a slip of the hand can result in a misspelled header. Our system only processes the headers listed above so misspellings will cause the datafeed to fail. Missing or incorrectly placed hyphens are another datafeed failure culprit!

  • Check your formatting

    Common formatting problems include data values that contain improperly escaped double quotation marks (") and data values that are separated by unsupported delimiter characters (semi-colons and greater-than/less-than signs are common misused characters).

  • Check your URLs

    Make sure that your URLs begin with either http:// or https:// and that they go to part-specific images or pages on your website

  • Check your data values

    Make sure that all of your parts have valid and accurate data values that correspond to all of the required headers. Parts that do not have values for the required headers will not be shown on Octopart.com. Too many of these parts in the datafeed will cause the datafeed to fail.

  • Check of extraneous information

    Make sure that the header row is the first row in the file and that there are no random or "nonsense" characters in the datafeed. These may confuse our parser, causing it to misread your data and ultimately, the datafeed to fail.

  • Check your listings

    Look for duplicate listings and missing information. If you find duplicate lines, please delete the duplicates.

If you are still having issues submitting your datafeed, please contact your Octopart account representative or send us an email (contact@octopart.com).