Looking for our new API? Get started for free here.

API	App Gallery Terms of Use Support Documentation Overview BOM Quickstart Search Tutorial Data Coverage Technical Specs REST API Reference Sign In Sign Up

Search Tutorial

As of March 31, 2022 Octopart APIv3 will no longer be supported. As of June 30, 2022 this version will be completely disabled.

Octopart APIv3 and Nexar Legacy API REST provide a powerful search interface that's easy to use but will take some time to master. The following is a tutorial that will take you through the features of the search interface by using common part search examples. Although the examples are all focused on part search, the other API collections (e.g. brands, categories, and sellers) have the same search interface so the lessons can be applied to those search endpoints as well.

One thing to note is that although the "parts/search" endpoint can be used to search for parts by MPN or SKU, you can only execute one search per request. For BOM matching applications that are only interested in matching parts by part number, it is highly recommended that you use the "parts/match" endpoint which is optimized for that use-case. To learn more about BOM matching with Octopart APIv3 and Nexar Legacy API REST, a good starting point is the BOM Quickstart tutorial.

This tutorial follows a narrative style. To access the reference documentation, please visit the REST API Reference Documentation page.

Keyword Search

Octopart APIv3 and Nexar Legacy API REST search interface allows you to search across parts by keyword using the q url argument:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/keyword_search1.sh »

Python

import json
import urllib

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME" 

args = [
   ('q', 'solid state relay'),
   ('start', 0),
   ('limit', 10)
   ]

url += '&' + urllib.urlencode(args)

data = urllib.urlopen(url).read()
search_response = json.loads(data)

# print number of hits
print search_response['hits']

# print results
for result in search_response['results']:
   part = result['item']

   # print matched part
   print "%s - %s" % (part['brand']['name'], part['mpn'])

Download examples/search-tutorial/keyword_search1.py »

Ruby

require 'rubygems'
require 'json'
require 'net/http'

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME"

def to_query(hsh)
  hsh.map {|k, v| "#{k}=#{URI.encode(v.to_s)}"}.join("&")
end

params = {
  :q =>"solid state relay",
  :start => 0,
  :limit => 10
}

url += "&" + to_query(params)

resp = Net::HTTP.get_response(URI.parse(url))
search_response = JSON.parse(resp.body)

# print number of hits
puts search_response['hits']

# print results
search_response['results'].each do |result|
  part = result['item']

  # print matched part
  puts part['brand']['name'] + ' - ' + part['mpn']
end

Download examples/search-tutorial/keyword_search1.rb »

JavaScript

<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script>
    var url = "http://octopart.com/api/v3/parts/search";
    url += "?callback=?";

    // NOTE: Use your API key here (https://octopart.com/api/register)
    url += "&apikey=REPLACE_ME";

    var args = {
        q: "solid state relay",
        start: 0,
        limit: 10
    };

    $.getJSON(url, args, function(search_response) {
        // print original request
        console.log(search_response['request']);

        // iterate through results
        $.each(search_response['results'], function(i, result){
            var part = result['item'];

            // print matched part items
            console.log(part['brand']['name'] + ' - ' + part['mpn']);
        });
    });
</script>

Download examples/search-tutorial/keyword_search1.html »

C Sharp

namespace OctopartApi
{
    using Newtonsoft.Json;
    using RestSharp;
    using System;

    public static class KeywordSearch1
    {
        public static void ExecuteSearch()
        {
            // -- your search query --
            string query = "solid state relay";

            string octopartUrlBase = "http://octopart.com/api/v3";
            string octopartUrlEndpoint = "parts/search";
            string apiKey = APIKEY;

            // Create the search request
            var client = new RestClient(octopartUrlBase);
            var req = new RestRequest(octopartUrlEndpoint, Method.GET)
                        .AddParameter("apikey", apiKey)
                        .AddParameter("q", query)
                        .AddParameter("start", "0")
                        .AddParameter("limit", "10");

            // Perform the search and obtain results
            var resp = client.Execute(req);
            var search_response = JsonConvert.DeserializeObject<dynamic>(resp.Content);

            // Print the number of hits and results
            Console.WriteLine("Number of hits: " + search_response["hits"]);
            foreach (var result in search_response["results"])
            {
                var part = result["item"];
                Console.WriteLine(part["brand"]["name"] + " - " + part["mpn"]);
            }
        }

        // -- your API key -- (https://octopart.com/api/register)
        private const string APIKEY = "REPLACE_ME";
    }
}

Download examples/search-tutorial/keyword_search1.cs »

VB.NET

Imports Newtonsoft.Json
Imports RestSharp
Imports System

Public Module KeywordSearch1
    Public Sub ExecuteSearch()
        ' -- your search query --
        Dim query As String = "solid state relay"

        Dim octopartUrlBase As String = "http://octopart.com/api/v3"
        Dim octopartUrlEndpoint As String = "parts/search"
        Dim apiKey As String = KeywordSearch1.APIKEY

        ' Create the search request
        Dim client = New RestClient(octopartUrlBase)
        Dim req = New RestRequest(octopartUrlEndpoint, Method.GET) _
                        .AddParameter("apikey", apiKey) _
                        .AddParameter("q", query) _
                        .AddParameter("start", "0") _
                        .AddParameter("limit", "10")

        ' Perform the search and obtain results
        Dim resp = client.Execute(req)
        Dim search_response = JsonConvert.DeserializeObject(resp.Content)

        ' Print the number of hits and results
        Console.WriteLine("Number of hits: " & search_response("hits"))
        For Each result In search_response("results")
            Dim part = result("item")
            Console.WriteLine(part("brand")("name") & " - " & part("mpn"))
        Next
    End Sub

    ' -- your API key -- (https:'octopart.com/api/register)
    Private Const APIKEY As String = "REPLACE_ME"
End Module

Download examples/search-tutorial/keyword_search1.vb »

By default, all keywords must be present in a part object in order for it to match. However, the words can appear in any field within the part. Keyword searches are executed across the following fields:

mpn
brand.name
offers.seller.name
offers.sku
descriptions.value

This feature of the search engine allows you to search intuitively across highly structured objects. For example, if you want to narrow your query by manufacturer you can add the manufacturer brand name to the q argument:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=Omron+solid+state+relay \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/keyword_search2.sh »

Python

import json
import urllib

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME" 

args = [
   ('q', 'Omron solid state relay'),
   ('start', 0),
   ('limit', 10)
   ]

url += '&' + urllib.urlencode(args)

data = urllib.urlopen(url).read()
search_response = json.loads(data)

# print number of hits
print search_response['hits']

# print results
for result in search_response['results']:
   part = result['item']

   # print matched part
   print "%s - %s" % (part['brand']['name'], part['mpn'])

Download examples/search-tutorial/keyword_search2.py »

Ruby

require 'rubygems'
require 'json'
require 'net/http'

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME"

def to_query(hsh)
  hsh.map {|k, v| "#{k}=#{URI.encode(v.to_s)}"}.join("&")
end

params = {
  :q =>"Omron solid state relay",
  :start => 0,
  :limit => 10
}

url += "&" + to_query(params)

resp = Net::HTTP.get_response(URI.parse(url))
search_response = JSON.parse(resp.body)

# print number of hits
puts search_response['hits']

# print results
search_response['results'].each do |result|
  part = result['item']

  # print matched part
  puts part['brand']['name'] + ' - ' + part['mpn']
end

Download examples/search-tutorial/keyword_search2.rb »

JavaScript

<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script>
    var url = "http://octopart.com/api/v3/parts/search";
    url += "?callback=?";

    // NOTE: Use your API key here (https://octopart.com/api/register)
    url += "&apikey=REPLACE_ME";

    var args = {
        q: "Omron solid state relay",
        start: 0,
        limit: 10
    };

    $.getJSON(url, args, function(search_response) {
        // print original request
        console.log(search_response['request']);

        // iterate through results
        $.each(search_response['results'], function(i, result){
            var part = result['item'];

            // print matched part items
            console.log(part['brand']['name'] + ' - ' + part['mpn']);
        });
    });
</script>

Download examples/search-tutorial/keyword_search2.html »

C Sharp

namespace OctopartApi
{
    using Newtonsoft.Json;
    using RestSharp;
    using System;

    public static class KeywordSearch2
    {
        public static void ExecuteSearch()
        {
            // -- your search query --
            string query = "Omron solid state relay";

            string octopartUrlBase = "http://octopart.com/api/v3";
            string octopartUrlEndpoint = "parts/search";
            string apiKey = APIKEY;

            // Create the search request
            var client = new RestClient(octopartUrlBase);
            var req = new RestRequest(octopartUrlEndpoint, Method.GET)
                        .AddParameter("apikey", apiKey)
                        .AddParameter("q", query)
                        .AddParameter("start", "0")
                        .AddParameter("limit", "10");

            // Perform the search and obtain results
            var resp = client.Execute(req);
            var search_response = JsonConvert.DeserializeObject<dynamic>(resp.Content);

            // Print the number of hits and results
            Console.WriteLine("Number of hits: " + search_response["hits"]);
            foreach (var result in search_response["results"])
            {
                var part = result["item"];
                Console.WriteLine(part["brand"]["name"] + " - " + part["mpn"]);
            }
	    }

        // -- your API key -- (https://octopart.com/api/register)
        private const string APIKEY = "REPLACE_ME";
    }
}

Download examples/search-tutorial/keyword_search2.cs »

VB.NET

Imports Newtonsoft.Json
Imports RestSharp
Imports System

Public Module KeywordSearch2
    Public Sub ExecuteSearch()
        ' -- your search query --
        Dim query As String = "Omron solid state relay"

        Dim octopartUrlBase As String = "http://octopart.com/api/v3"
        Dim octopartUrlEndpoint As String = "parts/search"
        Dim apiKey As String = KeywordSearch2.APIKEY

        ' Create the search request
        Dim client = New RestClient(octopartUrlBase)
        Dim req = New RestRequest(octopartUrlEndpoint, Method.GET) _
                        .AddParameter("apikey", apiKey) _
                        .AddParameter("q", query) _
                        .AddParameter("start", "0") _
                        .AddParameter("limit", "10")

        ' Perform the search and obtain results
        Dim resp = client.Execute(req)
        Dim search_response = JsonConvert.DeserializeObject(resp.Content)

        ' Print the number of hits and results
        Console.WriteLine("Number of hits: " & search_response("hits"))
        For Each result In search_response("results")
            Dim part = result("item")
            Console.WriteLine(part("brand")("name") & " - " & part("mpn"))
        Next
    End Sub

    ' -- your API key -- (https:'octopart.com/api/register)
    Private Const APIKEY As String = "REPLACE_ME"
End Module

Download examples/search-tutorial/keyword_search2.vb »

Boolean Operators

The q url argument also allows you to filter out keywords by using the "NOT" operator. For example, if you want your search to exclude parts made by a particular manufacturer, you can add a "NOT" to the manufacturer brand name in the q argument:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=NOT+Omron+solid+state+relay \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/boolean_operators.sh »

Python

import json
import urllib

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME" 

args = [
   ('q', 'NOT Omron solid state relay'),
   ('start', 0),
   ('limit', 10)
   ]

url += '&' + urllib.urlencode(args)

data = urllib.urlopen(url).read()
search_response = json.loads(data)

# print number of hits
print search_response['hits']

# print results
for result in search_response['results']:
   part = result['item']

   # print matched part
   print "%s - %s" % (part['brand']['name'], part['mpn'])

Download examples/search-tutorial/boolean_operators.py »

Ruby

require 'rubygems'
require 'json'
require 'net/http'

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME"

def to_query(hsh)
  hsh.map {|k, v| "#{k}=#{URI.encode(v.to_s)}"}.join("&")
end

params = {
  :q =>"NOT Omron solid state relay",
  :start => 0,
  :limit => 10
}

url += "&" + to_query(params)

resp = Net::HTTP.get_response(URI.parse(url))
search_response = JSON.parse(resp.body)

# print number of hits
puts search_response['hits']

# print results
search_response['results'].each do |result|
  part = result['item']

  # print matched part
  puts part['brand']['name'] + ' - ' + part['mpn']
end

Download examples/search-tutorial/boolean_operators.rb »

JavaScript

<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script>
    var url = "http://octopart.com/api/v3/parts/search";
    url += "?callback=?";

    // NOTE: Use your API key here (https://octopart.com/api/register)
    url += "&apikey=REPLACE_ME";

    var args = {
        q: "NOT Omron solid state relay",
        start: 0,
        limit: 10
    };

    $.getJSON(url, args, function(search_response) {
        // print original request
        console.log(search_response['request']);

        // iterate through results
        $.each(search_response['results'], function(i, result){
            var part = result['item'];

            // print matched part items
            console.log(part['brand']['name'] + ' - ' + part['mpn']);
        });
    });
</script>

Download examples/search-tutorial/boolean_operators.html »

C Sharp

namespace OctopartApi
{
    using Newtonsoft.Json;
    using RestSharp;
    using System;

    public static class BooleanOperators
    {
        public static void ExecuteSearch()
        {
            // -- your search query --
            string query = "NOT Omron solid state relay";

            string octopartUrlBase = "http://octopart.com/api/v3";
            string octopartUrlEndpoint = "parts/search";
            string apiKey = APIKEY;

            // Create the search request
            var client = new RestClient(octopartUrlBase);
            var req = new RestRequest(octopartUrlEndpoint, Method.GET)
                        .AddParameter("apikey", apiKey)
                        .AddParameter("q", query)
                        .AddParameter("start", "0")
                        .AddParameter("limit", "10");

            // Perform the search and obtain results
            var resp = client.Execute(req);
            var search_response = JsonConvert.DeserializeObject<dynamic>(resp.Content);

            // Print the number of hits and results
            Console.WriteLine("Number of hits: " + search_response["hits"]);
            foreach (var result in search_response["results"])
            {
                var part = result["item"];
                Console.WriteLine(part["brand"]["name"] + " - " + part["mpn"]);
            }
	    }

        // -- your API key -- (https://octopart.com/api/register)
    	private const string APIKEY = "REPLACE_ME";
    }
}

Download examples/search-tutorial/boolean_operators.cs »

VB.NET

Imports Newtonsoft.Json
Imports RestSharp
Imports System

Public Module BooleanOperators
    Public Sub ExecuteSearch()
        ' -- your search query --
        Dim query As String = "NOT Omron solid state relay"

        Dim octopartUrlBase As String = "http://octopart.com/api/v3"
        Dim octopartUrlEndpoint As String = "parts/search"
        Dim apiKey As String = BooleanOperators.APIKEY

        ' Create the search request
        Dim client = New RestClient(octopartUrlBase)
        Dim req = New RestRequest(octopartUrlEndpoint, Method.GET) _
                        .AddParameter("apikey", apiKey) _
                        .AddParameter("q", query) _
                        .AddParameter("start", "0") _
                        .AddParameter("limit", "10")

        ' Perform the search and obtain results
        Dim resp = client.Execute(req)
        Dim search_response = JsonConvert.DeserializeObject(resp.Content)

        ' Print the number of hits and results
        Console.WriteLine("Number of hits: " & search_response("hits"))
        For Each result In search_response("results")
            Dim part = result("item")
            Console.WriteLine(part("brand")("name") & " - " & part("mpn"))
        Next
    End Sub

    ' -- your API key -- (https:'octopart.com/api/register)
    Private Const APIKEY As String = "REPLACE_ME"
End Module

Download examples/search-tutorial/boolean_operators.vb »

Phrase Matching

If you only want to match on parts that contain a particular phrase you can wrap the phrase in quotation (") marks:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=Omron+%22solid+state+relay%22 \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/phrase_matching.sh »

Python

import json
import urllib

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME" 

args = [
   ('q', 'Omron "solid state relay"'),
   ('start', 0),
   ('limit', 10)
   ]

url += '&' + urllib.urlencode(args)

data = urllib.urlopen(url).read()
search_response = json.loads(data)

# print number of hits
print search_response['hits']

# print results
for result in search_response['results']:
   part = result['item']

   # print matched part
   print "%s - %s" % (part['brand']['name'], part['mpn'])

Download examples/search-tutorial/phrase_matching.py »

Ruby

require 'rubygems'
require 'json'
require 'net/http'

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME"

def to_query(hsh)
  hsh.map {|k, v| "#{k}=#{URI.encode(v.to_s)}"}.join("&")
end

params = {
  :q =>"Omron \"solid state relay\"",
  :start => 0,
  :limit => 10
}

url += "&" + to_query(params)

resp = Net::HTTP.get_response(URI.parse(url))
search_response = JSON.parse(resp.body)

# print number of hits
puts search_response['hits']

# print results
search_response['results'].each do |result|
  part = result['item']

  # print matched part
  puts part['brand']['name'] + ' - ' + part['mpn']
end

Download examples/search-tutorial/phrase_matching.rb »

JavaScript

<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script>
    var url = "http://octopart.com/api/v3/parts/search";
    url += "?callback=?";

    // NOTE: Use your API key here (https://octopart.com/api/register)
    url += "&apikey=REPLACE_ME";

    var args = {
        q: 'Omron "solid state relay"',
        start: 0,
        limit: 10
    };

    $.getJSON(url, args, function(search_response) {
        // print original request
        console.log(search_response['request']);

        // iterate through results
        $.each(search_response['results'], function(i, result){
            var part = result['item'];

            // print matched part items
            console.log(part['brand']['name'] + ' - ' + part['mpn']);
        });
    });
</script>

Download examples/search-tutorial/phrase_matching.html »

C Sharp

namespace OctopartApi
{
    using Newtonsoft.Json;
    using RestSharp;
    using System;

    public static class PhraseMatching
    {
        public static void ExecuteSearch()
        {
            // -- your search query --
            string query = "Omron \"solid state relay\"";

            string octopartUrlBase = "http://octopart.com/api/v3";
            string octopartUrlEndpoint = "parts/search";
            string apiKey = APIKEY;

            // Create the search request
            var client = new RestClient(octopartUrlBase);
            var req = new RestRequest(octopartUrlEndpoint, Method.GET)
                        .AddParameter("apikey", apiKey)
                        .AddParameter("q", query)
                        .AddParameter("start", "0")
                        .AddParameter("limit", "10");

            // Perform the search and obtain results
            var resp = client.Execute(req);
            var search_response = JsonConvert.DeserializeObject<dynamic>(resp.Content);

            // Print the number of hits and results
            Console.WriteLine("Number of hits: " + search_response["hits"]);
            foreach (var result in search_response["results"])
            {
                var part = result["item"];
                Console.WriteLine(part["brand"]["name"] + " - " + part["mpn"]);
            }
        }

        // -- your API key -- (https://octopart.com/api/register)
        private const string APIKEY = "REPLACE_ME";
    }
}

Download examples/search-tutorial/phrase_matching.cs »

VB.NET

Imports Newtonsoft.Json
Imports RestSharp
Imports System

Public Module PhraseMatching
    Public Sub ExecuteSearch()
        ' -- your search query --
        Dim query As String = "Omron ""solid state relay"""

        Dim octopartUrlBase As String = "http://octopart.com/api/v3"
        Dim octopartUrlEndpoint As String = "parts/search"
        Dim apiKey As String = PhraseMatching.APIKEY

        ' Create the search request
        Dim client = New RestClient(octopartUrlBase)
        Dim req = New RestRequest(octopartUrlEndpoint, Method.GET) _
                        .AddParameter("apikey", apiKey) _
                        .AddParameter("q", query) _
                        .AddParameter("start", "0") _
                        .AddParameter("limit", "10")

        ' Perform the search and obtain results
        Dim resp = client.Execute(req)
        Dim search_response = JsonConvert.DeserializeObject(resp.Content)

        ' Print the number of hits and results
        Console.WriteLine("Number of hits: " & search_response("hits"))
        For Each result In search_response("results")
            Dim part = result("item")
            Console.WriteLine(part("brand")("name") & " - " & part("mpn"))
        Next
    End Sub

    ' -- your API key -- (https:'octopart.com/api/register)
    Private Const APIKEY As String = "REPLACE_ME"
End Module

Download examples/search-tutorial/phrase_matching.vb »

Part Number Wildcards

The "parts/search" endpoint allows users to search for part numbers using wildcards. Wildcards can be used at the beginning, at the end, and anywhere within a part number. Multiple wildcards can be used but at least three alphanumeric characters must be present in the query term, otherwise it will be ignored. The asterisk wildcard ("*") can be used to match on zero or more characters and the question mark wildcard ("?") can be used to match on exactly one character:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=SN74S7* \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/part_number_wildcards.sh »

Python

import json
import urllib

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME" 

args = [
   ('q', 'SN74S7*'),
   ('start', 0),
   ('limit', 10)
   ]

url += '&' + urllib.urlencode(args)

data = urllib.urlopen(url).read()
search_response = json.loads(data)

# print number of hits
print search_response['hits']

# print results
for result in search_response['results']:
   part = result['item']

   # print matched part
   print "%s - %s" % (part['brand']['name'], part['mpn'])

Download examples/search-tutorial/part_number_wildcards.py »

Ruby

require 'rubygems'
require 'json'
require 'net/http'

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME"

def to_query(hsh)
  hsh.map {|k, v| "#{k}=#{URI.encode(v.to_s)}"}.join("&")
end

params = {
  :q =>"SN74S7*",
  :start => 0,
  :limit => 10
}

url += "&" + to_query(params)

resp = Net::HTTP.get_response(URI.parse(url))
search_response = JSON.parse(resp.body)

# print number of hits
puts search_response['hits']

# print results
search_response['results'].each do |result|
  part = result['item']

  # print matched part
  puts part['brand']['name'] + ' - ' + part['mpn']
end

Download examples/search-tutorial/part_number_wildcards.rb »

JavaScript

<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script>
    var url = "http://octopart.com/api/v3/parts/search";
    url += "?callback=?";

    // NOTE: Use your API key here (https://octopart.com/api/register)
    url += "&apikey=REPLACE_ME";

    var args = {
        q: "SN74S7*",
        start: 0,
        limit: 10
    };

    $.getJSON(url, args, function(search_response) {
        // print original request
        console.log(search_response['request']);

        // iterate through results
        $.each(search_response['results'], function(i, result){
            var part = result['item'];

            // print matched part items
            console.log(part['brand']['name'] + ' - ' + part['mpn']);
        });
    });
</script>

Download examples/search-tutorial/part_number_wildcards.html »

C Sharp

namespace OctopartApi
{
    using Newtonsoft.Json;
    using RestSharp;
    using System;

    public static class PartNumberWildcards
    {
        public static void ExecuteSearch()
        {
            // -- your search query --
            string query = "SN74S7*";

            string octopartUrlBase = "http://octopart.com/api/v3";
            string octopartUrlEndpoint = "parts/search";
            string apiKey = APIKEY;

            // Create the search request
            var client = new RestClient(octopartUrlBase);
            var req = new RestRequest(octopartUrlEndpoint, Method.GET)
                        .AddParameter("apikey", apiKey)
                        .AddParameter("q", query)
                        .AddParameter("start", "0")
                        .AddParameter("limit", "10");

            // Perform the search and obtain results
            var resp = client.Execute(req);
            var search_response = JsonConvert.DeserializeObject<dynamic>(resp.Content);

            // Print the number of hits and results
            Console.WriteLine("Number of hits: " + search_response["hits"]);
            foreach (var result in search_response["results"])
            {
                var part = result["item"];
                Console.WriteLine(part["brand"]["name"] + " - " + part["mpn"]);
            }
	    }

        // -- your API key -- (https://octopart.com/api/register)
        private const string APIKEY = "REPLACE_ME";
    }
}

Download examples/search-tutorial/part_number_wildcards.cs »

VB.NET

Imports Newtonsoft.Json
Imports RestSharp
Imports System

Public Module PartNumberWildcards
    Public Sub ExecuteSearch()
        ' -- your search query --
        Dim query As String = "SN74S7*"

        Dim octopartUrlBase As String = "http://octopart.com/api/v3"
        Dim octopartUrlEndpoint As String = "parts/search"
        Dim apiKey As String = PartNumberWildcards.APIKEY

        ' Create the search request
        Dim client = New RestClient(octopartUrlBase)
        Dim req = New RestRequest(octopartUrlEndpoint, Method.GET) _
                        .AddParameter("apikey", apiKey) _
                        .AddParameter("q", query) _
                        .AddParameter("start", "0") _
                        .AddParameter("limit", "10")

        ' Perform the search and obtain results
        Dim resp = client.Execute(req)
        Dim search_response = JsonConvert.DeserializeObject(resp.Content)

        ' Print the number of hits and results
        Console.WriteLine("Number of hits: " & search_response("hits"))
        For Each result In search_response("results")
            Dim part = result("item")
            Console.WriteLine(part("brand")("name") & " - " & part("mpn"))
        Next
    End Sub

    ' -- your API key -- (https:'octopart.com/api/register)
    Private Const APIKEY As String = "REPLACE_ME"
End Module

Download examples/search-tutorial/part_number_wildcards.vb »

One important thing to note is that when a wildcard is present in a query term, that term will be treated as a part number and will not match on any other field.

Search Response Overview

Each API search endpoint returns a JSON object containing a list of search results along with some data about the search such as how long it took and the original request object. Here's an example of a parts search response:

For a more detailed explanation of the response object please see the SearchResponse object schema section of the REST API Reference Documentation.

Paging Through Results

By default, the parts/search endpoint returns up to 10 results per request. To change the number of results to return you can use the limit url argument:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d start=0 \
   -d limit=20 \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/limit_argument.sh »

Python

import json
import urllib

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME" 

args = [
   ('q', 'solid state relay'),
   ('start', 0),
   ('limit', 20)
   ]

url += '&' + urllib.urlencode(args)

data = urllib.urlopen(url).read()
search_response = json.loads(data)

# print number of hits
print search_response['hits']

# print results
for result in search_response['results']:
   part = result['item']

   # print matched part
   print "%s - %s" % (part['brand']['name'], part['mpn'])

Download examples/search-tutorial/limit_argument.py »

Ruby

require 'rubygems'
require 'json'
require 'net/http'

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME"

def to_query(hsh)
  hsh.map {|k, v| "#{k}=#{URI.encode(v.to_s)}"}.join("&")
end

params = {
  :q =>"solid state relay",
  :start => 0,
  :limit => 20
}

url += "&" + to_query(params)

resp = Net::HTTP.get_response(URI.parse(url))
search_response = JSON.parse(resp.body)

# print number of hits
puts search_response['hits']

# print results
search_response['results'].each do |result|
  part = result['item']

  # print matched part
  puts part['brand']['name'] + ' - ' + part['mpn']
end

Download examples/search-tutorial/limit_argument.rb »

JavaScript

<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script>
    var url = "http://octopart.com/api/v3/parts/search";
    url += "?callback=?";

    // NOTE: Use your API key here (https://octopart.com/api/register)
    url += "&apikey=REPLACE_ME";

    var args = {
        q: "solid state relay",
        start: 0,
        limit: 20
    };

    $.getJSON(url, args, function(search_response) {
        // print original request
        console.log(search_response['request']);

        // iterate through results
        $.each(search_response['results'], function(i, result){
            var part = result['item'];

            // print matched part items
            console.log(part['brand']['name'] + ' - ' + part['mpn']);
        });
    });
</script>

Download examples/search-tutorial/limit_argument.html »

C Sharp

namespace OctopartApi
{
    using Newtonsoft.Json;
    using RestSharp;
    using System;

    public static class LimitArgument
    {
        public static void ExecuteSearch()
        {
            // -- your search query --
            string query = "solid state relay";

            string octopartUrlBase = "http://octopart.com/api/v3";
            string octopartUrlEndpoint = "parts/search";
            string apiKey = APIKEY;

            // Create the search request
            var client = new RestClient(octopartUrlBase);
            var req = new RestRequest(octopartUrlEndpoint, Method.GET)
                        .AddParameter("apikey", apiKey)
                        .AddParameter("q", query)
                        .AddParameter("start", "0")
                        .AddParameter("limit", "20");

            // Perform the search and obtain results
            var resp = client.Execute(req);
            var search_response = JsonConvert.DeserializeObject<dynamic>(resp.Content);

            // Print the number of hits and results
            Console.WriteLine("Number of hits: " + search_response["hits"]);
            foreach (var result in search_response["results"])
            {
                var part = result["item"];
                Console.WriteLine(part["brand"]["name"] + " - " + part["mpn"]);
            }
        }

        // -- your API key -- (https://octopart.com/api/register)
        private const string APIKEY = "REPLACE_ME";
    }
}

Download examples/search-tutorial/limit_argument.cs »

VB.NET

Imports Newtonsoft.Json
Imports RestSharp
Imports System

Public Module LimitArgument
    Public Sub ExecuteSearch()
        ' -- your search query --
        Dim query As String = "solid state relay"

        Dim octopartUrlBase As String = "http://octopart.com/api/v3"
        Dim octopartUrlEndpoint As String = "parts/search"
        Dim apiKey As String = LimitArgument.APIKEY

        ' Create the search request
        Dim client = New RestClient(octopartUrlBase)
        Dim req = New RestRequest(octopartUrlEndpoint, Method.GET) _
                        .AddParameter("apikey", apiKey) _
                        .AddParameter("q", query) _
                        .AddParameter("start", "0") _
                        .AddParameter("limit", "20")

        ' Perform the search and obtain results
        Dim resp = client.Execute(req)
        Dim search_response = JsonConvert.DeserializeObject(resp.Content)

        ' Print the number of hits and results
        Console.WriteLine("Number of hits: " & search_response("hits"))
        For Each result In search_response("results")
            Dim part = result("item")
            Console.WriteLine(part("brand")("name") & " - " & part("mpn"))
        Next
    End Sub

    ' -- your API key -- (https:'octopart.com/api/register)
    Private Const APIKEY As String = "REPLACE_ME"
End Module

Download examples/search-tutorial/limit_argument.vb »

To change the ordinal position of the first result you can use the start argument. For example, to return the second page of results (20-40):

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d start=20 \
   -d limit=20 \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/start_argument.sh »

Python

import json
import urllib

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME" 

args = [
   ('q', 'solid state relay'),
   ('start', 20),
   ('limit', 20)
   ]

url += '&' + urllib.urlencode(args)

data = urllib.urlopen(url).read()
search_response = json.loads(data)

# print number of hits
print search_response['hits']

# print results
for result in search_response['results']:
   part = result['item']

   # print matched part
   print "%s - %s" % (part['brand']['name'], part['mpn'])

Download examples/search-tutorial/start_argument.py »

Ruby

require 'rubygems'
require 'json'
require 'net/http'

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME"

def to_query(hsh)
  hsh.map {|k, v| "#{k}=#{URI.encode(v.to_s)}"}.join("&")
end

params = {
  :q =>"solid state relay",
  :start => 20,
  :limit => 20
}

url += "&" + to_query(params)

resp = Net::HTTP.get_response(URI.parse(url))
search_response = JSON.parse(resp.body)

# print number of hits
puts search_response['hits']

# print results
search_response['results'].each do |result|
  part = result['item']

  # print matched part
  puts part['brand']['name'] + ' - ' + part['mpn']
end

Download examples/search-tutorial/start_argument.rb »

JavaScript

<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script>
    var url = "http://octopart.com/api/v3/parts/search";
    url += "?callback=?";

    // NOTE: Use your API key here (https://octopart.com/api/register)
    url += "&apikey=REPLACE_ME";

    var args = {
        q: "solid state relay",
        start: 20,
        limit: 20
    };

    $.getJSON(url, args, function(search_response) {
        // print original request
        console.log(search_response['request']);

        // iterate through results
        $.each(search_response['results'], function(i, result){
            var part = result['item'];

            // print matched part items
            console.log(part['brand']['name'] + ' - ' + part['mpn']);
        });
    });
</script>

Download examples/search-tutorial/start_argument.html »

C Sharp

namespace OctopartApi
{
    using Newtonsoft.Json;
    using RestSharp;
    using System;

    public static class StartArgument
    {
        public static void ExecuteSearch()
        {
            // -- your search query --
            string query = "solid state relay";

            string octopartUrlBase = "http://octopart.com/api/v3";
            string octopartUrlEndpoint = "parts/search";
            string apiKey = APIKEY;

            // Create the search request
            var client = new RestClient(octopartUrlBase);
            var req = new RestRequest(octopartUrlEndpoint, Method.GET)
                        .AddParameter("apikey", apiKey)
                        .AddParameter("q", query)
                        .AddParameter("start", "20")
                        .AddParameter("limit", "20");

            // Perform the search and obtain results
            var resp = client.Execute(req);
            var search_response = JsonConvert.DeserializeObject<dynamic>(resp.Content);

            // Print the number of hits and results
            Console.WriteLine("Number of hits: " + search_response["hits"]);
            foreach (var result in search_response["results"])
            {
                var part = result["item"];
                Console.WriteLine(part["brand"]["name"] + " - " + part["mpn"]);
            }
	    }

        // -- your API key -- (https://octopart.com/api/register)
        private const string APIKEY = "REPLACE_ME";
    }
}

Download examples/search-tutorial/start_argument.cs »

VB.NET

Imports Newtonsoft.Json
Imports RestSharp
Imports System

Public Module StartArgument
    Public Sub ExecuteSearch()
        ' -- your search query --
        Dim query As String = "solid state relay"

        Dim octopartUrlBase As String = "http://octopart.com/api/v3"
        Dim octopartUrlEndpoint As String = "parts/search"
        Dim apiKey As String = StartArgument.APIKEY

        ' Create the search request
        Dim client = New RestClient(octopartUrlBase)
        Dim req = New RestRequest(octopartUrlEndpoint, Method.GET) _
                        .AddParameter("apikey", apiKey) _
                        .AddParameter("q", query) _
                        .AddParameter("start", "20") _
                        .AddParameter("limit", "20")

        ' Perform the search and obtain results
        Dim resp = client.Execute(req)
        Dim search_response = JsonConvert.DeserializeObject(resp.Content)

        ' Print the number of hits and results
        Console.WriteLine("Number of hits: " & search_response("hits"))
        For Each result In search_response("results")
            Dim part = result("item")
            Console.WriteLine(part("brand")("name") & " - " & part("mpn"))
        Next
    End Sub

    ' -- your API key -- (https:'octopart.com/api/register)
    Private Const APIKEY As String = "REPLACE_ME"
End Module

Download examples/search-tutorial/start_argument.vb »

Sorting

To change the sort order of the result set you can use the sortby url argument. The syntax for the sortby argument is "<fieldname> <sortorder>" where fieldname is the field to sort on (e.g. "brand.name", "specs.capacitance.value") and sortorder is either "asc" or "desc".

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d sortby=specs.current_rating.value%20desc \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/sortby_argument1.sh »

Python

import json
import urllib

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME" 

args = [
   ('q', 'solid state relay'),
   ('sortby', 'specs.current_rating.value desc')
   ]

url += '&' + urllib.urlencode(args)

data = urllib.urlopen(url).read()
search_response = json.loads(data)

# print number of hits
print search_response['hits']

# print results
for result in search_response['results']:
   part = result['item']

   # print matched part
   print "%s - %s" % (part['brand']['name'], part['mpn'])

Download examples/search-tutorial/sortby_argument1.py »

Ruby

require 'rubygems'
require 'json'
require 'net/http'

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME"

def to_query(hsh)
  hsh.map {|k, v| "#{k}=#{URI.encode(v.to_s)}"}.join("&")
end

params = {
  :q =>"solid state relay",
  :sortby => "specs.current_rating.value desc"
}

url += "&" + to_query(params)

resp = Net::HTTP.get_response(URI.parse(url))
search_response = JSON.parse(resp.body)

# print number of hits
puts search_response['hits']

# print results
search_response['results'].each do |result|
  part = result['item']

  # print matched part
  puts part['brand']['name'] + ' - ' + part['mpn']
end

Download examples/search-tutorial/sortby_argument1.rb »

JavaScript

<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script>
    var url = "http://octopart.com/api/v3/parts/search";
    url += "?callback=?";

    // NOTE: Use your API key here (https://octopart.com/api/register)
    url += "&apikey=REPLACE_ME";

    var args = {
        q: "solid state relay",
        sortby: "specs.current_rating.value desc"
    };

    $.getJSON(url, args, function(search_response) {
        // print original request
        console.log(search_response['request']);

        // iterate through results
        $.each(search_response['results'], function(i, result){
            var part = result['item'];

            // print matched part items
            console.log(part['brand']['name'] + ' - ' + part['mpn']);
        });
    });
</script>

Download examples/search-tutorial/sortby_argument1.html »

C Sharp

namespace OctopartApi
{
    using Newtonsoft.Json;
    using RestSharp;
    using System;

    public static class SortByArgument1
    {
        public static void ExecuteSearch()
        {
            // -- your search query --
            string query = "solid state relay";

            string octopartUrlBase = "http://octopart.com/api/v3";
            string octopartUrlEndpoint = "parts/search";
            string apiKey = APIKEY;

            // Create the search request
            var client = new RestClient(octopartUrlBase);
            var req = new RestRequest(octopartUrlEndpoint, Method.GET)
                        .AddParameter("apikey", apiKey)
                        .AddParameter("q", query)
                        .AddParameter("sortby", "specs.current_rating.value desc");

            // Perform the search and obtain results
            var resp = client.Execute(req);
            var search_response = JsonConvert.DeserializeObject<dynamic>(resp.Content);

            // Print the number of hits and results
            Console.WriteLine("Number of hits: " + search_response["hits"]);
            foreach (var result in search_response["results"])
            {
                var part = result["item"];
                Console.WriteLine(part["brand"]["name"] + " - " + part["mpn"]);
            }
	    }

        // -- your API key -- (https://octopart.com/api/register)
        private const string APIKEY = "REPLACE_ME";
    }
}

Download examples/search-tutorial/sortby_argument1.cs »

VB.NET

Imports Newtonsoft.Json
Imports RestSharp
Imports System

Public Module SortByArgument1
    Public Sub ExecuteSearch()
        ' -- your search query --
        Dim query As String = "solid state relay"

        Dim octopartUrlBase As String = "http://octopart.com/api/v3"
        Dim octopartUrlEndpoint As String = "parts/search"
        Dim apiKey As String = SortByArgument1.APIKEY

        ' Create the search request
        Dim client = New RestClient(octopartUrlBase)
        Dim req = New RestRequest(octopartUrlEndpoint, Method.GET) _
                        .AddParameter("apikey", apiKey) _
                        .AddParameter("q", query) _
                        .AddParameter("sortby", "specs.current_rating.value desc")

        ' Perform the search and obtain results
        Dim resp = client.Execute(req)
        Dim search_response = JsonConvert.DeserializeObject(resp.Content)

        ' Print the number of hits and results
        Console.WriteLine("Number of hits: " & search_response("hits"))
        For Each result In search_response("results")
            Dim part = result("item")
            Console.WriteLine(part("brand")("name") & " - " & part("mpn"))
        Next
    End Sub

    ' -- your API key -- (https:'octopart.com/api/register)
    Private Const APIKEY As String = "REPLACE_ME"
End Module

Download examples/search-tutorial/sortby_argument1.vb »

By default, the value of sortby is "score desc" where "score" is a special field to indicate full-text matching score. To add a secondary sort value, you can comma separate sortby strings:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d sortby=specs.current_rating.value%20desc%2C%20specs.isolation_voltage.value%20desc \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/sortby_argument2.sh »

Python

import json
import urllib

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME" 

args = [
   ('q', 'solid state relay'),
   ('sortby', 'specs.current_rating.value desc, specs.isolation_voltage.value desc')
   ]

url += '&' + urllib.urlencode(args)

data = urllib.urlopen(url).read()
search_response = json.loads(data)

# print number of hits
print search_response['hits']

# print results
for result in search_response['results']:
   part = result['item']

   # print matched part
   print "%s - %s" % (part['brand']['name'], part['mpn'])

Download examples/search-tutorial/sortby_argument2.py »

Ruby

require 'rubygems'
require 'json'
require 'net/http'

url = "http://octopart.com/api/v3/parts/search"

# NOTE: Use your API key here (https://octopart.com/api/register)
url += "?apikey=REPLACE_ME"

def to_query(hsh)
  hsh.map {|k, v| "#{k}=#{URI.encode(v.to_s)}"}.join("&")
end

params = {
  :q =>"solid state relay",
  :sortby => "specs.current_rating.value desc, specs.isolation_voltage.value desc"
}

url += "&" + to_query(params)

resp = Net::HTTP.get_response(URI.parse(url))
search_response = JSON.parse(resp.body)

# print number of hits
puts search_response['hits']

# print results
search_response['results'].each do |result|
  part = result['item']

  # print matched part
  puts part['brand']['name'] + ' - ' + part['mpn']
end

Download examples/search-tutorial/sortby_argument2.rb »

JavaScript

<script src="http://code.jquery.com/jquery-1.11.0.js"></script>
<script>
    var url = "http://octopart.com/api/v3/parts/search";
    url += "?callback=?";

    // NOTE: Use your API key here (https://octopart.com/api/register)
    url += "&apikey=REPLACE_ME";

    var args = {
        q: "solid state relay",
        sortby: "specs.current_rating.value desc, specs.isolation_voltage.value desc"
    };

    $.getJSON(url, args, function(search_response) {
        // print original request
        console.log(search_response['request']);

        // iterate through results
        $.each(search_response['results'], function(i, result){
            var part = result['item'];

            // print matched part items
            console.log(part['brand']['name'] + ' - ' + part['mpn']);
        });
    });
</script>

Download examples/search-tutorial/sortby_argument2.html »

C Sharp

namespace OctopartApi
{
    using Newtonsoft.Json;
    using RestSharp;
    using System;

    public static class SortByArgument2
    {
        public static void ExecuteSearch()
        {
            // -- your search query --
            string query = "solid state relay";

            string octopartUrlBase = "http://octopart.com/api/v3";
            string octopartUrlEndpoint = "parts/search";
            string apiKey = APIKEY;

            // Create the search request
            var client = new RestClient(octopartUrlBase);
            var req = new RestRequest(octopartUrlEndpoint, Method.GET)
                        .AddParameter("apikey", apiKey)
                        .AddParameter("q", query)
                        .AddParameter("sortby", "specs.current_rating.value desc, specs.isolation_voltage.value desc");

            // Perform the search and obtain results
            var resp = client.Execute(req);
            var search_response = JsonConvert.DeserializeObject<dynamic>(resp.Content);

            // Print the number of hits and results
            Console.WriteLine("Number of hits: " + search_response["hits"]);
            foreach (var result in search_response["results"])
            {
                var part = result["item"];
                Console.WriteLine(part["brand"]["name"] + " - " + part["mpn"]);
            }
	    }

        // -- your API key -- (https://octopart.com/api/register)
        private const string APIKEY = "REPLACE_ME";
    }
}

Download examples/search-tutorial/sortby_argument2.cs »

VB.NET

Imports Newtonsoft.Json
Imports RestSharp
Imports System

Public Module SortByArgument2
    Public Sub ExecuteSearch()
        ' -- your search query --
        Dim query As String = "solid state relay"

        Dim octopartUrlBase As String = "http://octopart.com/api/v3"
        Dim octopartUrlEndpoint As String = "parts/search"
        Dim apiKey As String = SortByArgument2.APIKEY

        ' Create the search request
        Dim client = New RestClient(octopartUrlBase)
        Dim req = New RestRequest(octopartUrlEndpoint, Method.GET) _
                        .AddParameter("apikey", apiKey) _
                        .AddParameter("q", query) _
                        .AddParameter("sortby", "specs.current_rating.value desc, specs.isolation_voltage.value desc")

        ' Perform the search and obtain results
        Dim resp = client.Execute(req)
        Dim search_response = JsonConvert.DeserializeObject(resp.Content)

        ' Print the number of hits and results
        Console.WriteLine("Number of hits: " & search_response("hits"))
        For Each result In search_response("results")
            Dim part = result("item")
            Console.WriteLine(part("brand")("name") & " - " & part("mpn"))
        Next
    End Sub

    ' -- your API key -- (https:'octopart.com/api/register)
    Private Const APIKEY As String = "REPLACE_ME"
End Module

Download examples/search-tutorial/sortby_argument2.vb »

Fieldnames

Several of the search endpoint url arguments use a variable referred to as <fieldname>. Fieldnames are dot-separated property names which can be used to reference nested property values. For example, to sort results alphabetically by manufacturer brand names you can use the brand.name fieldname in place of the specs.current_rating.value fieldname found above.

Note that not every field is searchable. Fields that are searchable can be used in filters, faceting, calculating stats and sorting. These are the searchable part fields:

Fieldname	Description
`mpn`	Manufacturer part number
`brand.name`	Manufacturer brand name
`offers.sku`	Distributor SKU
`offers.seller.name`	Distributor name
`descriptions.value`	Description text value
`specs.*.value`	Technical specs `value` property
`specs.*.min_value`	Technical specs `min_value` property
`specs.*.max_value`	Technical specs `max_value` property
`category_uids`	Category uid's

Filtering

Octopart APIv3 and Nexar Legacy API REST search interface allows you to filter results by the value of a given field using filter fields or to add more complex filters such as ranged filters and filters with wildcards using filter queries.

Filter Fields

The filter[fields][<fieldname>][] url argument allows you to add simple filters to a search result. To filter on a field just replace the <fieldname> value with the field you want to filter on and use the filter value as the url argument. Here's an example of how to display all Texas Instruments parts:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d filter[fields][brand.name][]=Texas+Instruments \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/filter_fields1.sh »

Also note that multiple arguments get AND'd together:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d filter[fields][brand.name][]=Texas+Instruments \
   -d filter[fields][offers.seller.name][]=Digi-Key \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/filter_fields2.sh »

For more information about the filter[fields][<fieldname>][] url argument please see the Search Documentation section of the REST API reference.

Filter Queries

The filter[queries][] url argument allows you to add more complex filters to the query using "filter query" syntax:

Description	Filter query syntax
Single Terms	fieldname:val
Multiple Terms	fieldname:(val1 val2)
Phrase Match	fieldname:"val1 val2"
Multiple-letter Wildcards	fieldname:val*
Single-letter Wildcards	fieldname:va?
Ranged Search (inclusive)	fieldname:[min_val TO max_val]
Ranged Search (exclusive)	fieldname:{min_val to max_val}
Ranged Search (unbounded)	fieldname:[min_val TO *]
Boolean Operators	query1 OR query2
Nested Queries	(query1 AND query2) OR (query3 AND query4)

To add a filter query to the search request, simply add it as a url argument:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d filter[queries][]=brand.name:Crydom \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/filter_queries1.sh »

And multiple arguments get AND'd together:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d filter[queries][]=brand.name:Crydom \
   -d filter[queries][]=offers.seller.name:Digi-Key \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/filter_queries2.sh »

For more information about the filter[queries][] url argument please see the Search Documentation section of the REST API reference.

Faceting

Search facets allow you to implement guided search interfaces like those found on Amazon or eBay where users are presented with a list of filters and the number of items which apply to each filter. For example, search facets can be used to indicate to a user who has searched for "LEDs" how many Red, Green, or Yellow LEDs are in the result set.

Facet Fields

By adding url arguments of the form facet[fields][<fieldname>][include]=true the API will return the filters available for a given field. To facet on a particular field just replace the <fieldname> value with the field you want to facet on. Here's an example of how to see which manufacturers make solid state relays:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d facet[fields][brand.name][include]=true \
   -d limit=0 \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/facet_fields.sh »

For more information about the facet[fields][<fieldname>] url argument please see the Search Documentation section of the REST API reference.

Facet Queries

The facet[queries][] url argument allows you to facet on more complex filter values using the "filter query" syntax (see Filter Queries Section above). Here's an example of how to calculate the number of solid state relays with a load current of 5A and 10A:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d facet[queries][]=specs.load_current.value:5 \
   -d facet[queries][]=specs.load_current.value:10 \
   -d limit=0 \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/facet_queries.sh »

For more information about the facet[queries][] url argument please see the Search Documentation section of the REST API reference.

Calculating Statistics

By adding url arguments of the form stats[<fieldname>][include]=true the API will return statistics for the property values in the result set (e.g. min, max, mean, standard deviation). Here's an example of how to calculate statistics on current load values for solid state relays:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d stats[specs.load_current.value][include]=true \
   -d limit=0 \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/stats.sh »

For more information about the stats[<fieldname>] url argument please see the Search Documentation section of the REST API reference.

Spec Drilldown

One problem with calculating facets and stats for part objects is that the technical specs which are relevant to each result set vary from query to query. For example, the technical specs that are relevant to a search for "capacitors" are different than those for "solid state relays". In many cases the ideal question to ask the search engine is, "for a given query X, what are the relevant technical specs I can filter on?"

To address this problem, Octopart APIv3 and Nexar Legacy API REST have a useful feature called "spec drilldown" which can be enabled by adding the url argument spec_drilldown[include]=true to the API request:

Bash

$ curl -G http://octopart.com/api/v3/parts/search \
   -d q=solid+state+relay \
   -d spec_drilldown[include]=true \
   -d limit=0 \
   -d apikey=REPLACE_ME \
   -d pretty_print=true

Download examples/search-tutorial/spec_drilldown.sh »

When you perform a spec drilldown the API will automatically facet on all technical spec string values and calculate stats for technical spec numeric values.

For more information about the spec_drilldown url argument please see the parts/search section of the REST API reference.

Search Tutorial

Keyword Search

Boolean Operators

Phrase Matching

Part Number Wildcards

Search Response Overview

Paging Through Results

Sorting

Fieldnames

Filtering

Filter Fields

Filter Queries

Faceting

Facet Fields

Facet Queries

Calculating Statistics

Spec Drilldown

Company

Product

Community

Business