Nexar Playground GraphQL Query examples

Modified on Thu, 14 Sep 2023 at 03:13 PM

Welcome to the Nexar Playground example queries page. This page provides more information about the queries in the API playground.

To get started, press the PLAY button in the playground development environment in Nexar to run an example query:

You will see the response to the query on the right-hand view window.


Our Data Model

This page can tell you more about how to use Voyager, the visualisation of our data model, and how you can interact with the API. Further documentation on how the GraphQL language works can be found here.


Whilst using our GraphQL development environment, you can use CTRL+Space to explore the fields you can add to your query.


If you use Postman, you can find a collection containing many of these queries attached. Here's an article explaining how to import this into Postman.



Whilst this is a handy resource to get started, we recommend using these examples to learn how to build your queries. Feel free to adapt any of these different examples to suit your use case.


Below are more in-depth descriptions of each query and how you use them.

If you need further support, submit any questions here.


Have fun exploring!


TABLE OF CONTENTS


Total Availability

  • This search uses supSearchMPN. The query, 'q', is "acs770" and will return many parts, as supSearchMPN allows for partial matches. 
  • The country is set to "US". Without setting a country, availability for parts will default to the US.
  • The part limit is set to 5. Each part returned will count against your organisation's part limit. By design, supSearchMPN returns 10 parts.
  • Our query returns:
    • A description of the part
    • The total availability
    • The MPN
#Component availability
#Availability of a component in a specified country's market, and individual seller inventory

query marketAvailability {
  supSearchMpn(
    #The value can be a partial match
    #Change "acs770" to return your own part
    q: "acs770"
    #Total availability defaults to US
    #Set your ISO country code below
    country: "US"
    limit: 5
  ) {
    #For this query, we return:
    # Part description
    # Total availability & MPN
    # Seller name & inventory level
    #Press CTRL+space to explore more fields    
    results {
      description
      part {
        totalAvail
        mpn
        sellers {
          company {
            name
          }
          offers {
            inventoryLevel
          }
        }
      }
    }
  }
}

Pricing Breaks

  • In Octopart, you can find pricing by quantities such as 1, 10, 100, 10000. Nexar's API can also return these prices.
  • This search uses supSearchMPN. The query, 'q', is "acs770" and will return many parts, as supSearchMPN allows for partial matches.
  • The part limit is set to 5. Each part returned will count against your organisation's part limit. By design, supSearchMPN returns 10 parts.
  • Our query returns:
    • Total number of results
    • Seller names
    • The offer quantities 
    • The prices of the parts for that quantity


#Pricing by volume levels
#Returns seller pricing of components for different purchase quantities

query pricingByVolumeLevels {
  #Change "acs770" to return your own part
  supSearchMpn(
    q: "acs770", 
    #The API returns a default of 10 parts. 
    #Change limit from "5" to return the no. of parts you want
    limit: 5) {
    #Total number of results the search returns
    hits
    results {
      part {
	#For this query, we return 
        # Part MPN
        # Part sellers company name, offer quantity & prices 
        #Press CTRL+space to explore more fields
        mpn
        sellers {
          company {
            name
          }
          offers {
            prices {
              #Returns prices for different quantities sellers offer
              #Usually (but not limited to) 1, 10, 100, 1000, 10000 
              quantity
              price
            }
          }
        }      
      }
    }
  }
}

Part Attributes

  • Parts in Octopart have attributes associated with them. The total list of attributes can be found here.
  • This search uses supSearchMPN. The query, 'q', is "ADS" and will return many parts, as supSearchMPN allows for partial matches.
  • You can filter or sort your query results on the attribute short-name. In the query below, we are filtering on the case packaging, specifically for the type SSOP. Note that you cannot filter on an attribute's existence. More information on filtering and sorting can be found here
  • The part limit is set to 5. Each part returned will count against your organisation's part limit. By design, supSearchMPN returns 10 parts.
  • Our query returns:
    • Total number of results
    • Part attribute names, id and values
#Return part attributes
#Return specific component technical specifications. 


#Not every component will have every attribute.
#Components can be post-filtered to specific attributes
query specAttributes{
  #Change "ADS" to a search of your choice
  supSearchMpn(
    q: "ADS",
    filters: {
      case_package: 
        #Change "SSOP" to a packaging of your own (e.g. "VSSOP")
        ["SSOP"]
    },
    #The API returns a default of 10 parts. 
    #Change limit from "5" to return the no. of parts you want
    limit: 5
    ) {
    #The number of results the search returns
    hits
    results {
      part {
        mpn
        specs {
          attribute {
            #For this query, we return
            # Part MPN
            # Technical specification name, id, shortname and value
            #Press CTRL+space to explore more fields
            name
            id
            shortname
          }
          displayValue
        }      
      }
    }
  }
}

Alternative Parts

  • This query finds alternatives that are similar in specs and functionality
  • This search uses supSearchMPN. The query, 'q', is "SY55855VKG" and will return many parts, as supSearchMPN allows for partial matches.
  • The part limit is set to 5. Each part returned will count against your organisation's part limit. By design, supSearchMPN returns 10 parts.
  • Our query returns:
    • Similar part name, URL and MPN
#Alternative parts by MPN
#Search parts by MPN and return parts similar in spec & functionality
query findAlternativeParts {
  #Change "SY55855VKG" to find alternative parts of your own
  supSearchMpn(
    q: "SY55855VKG",
    #The API returns a default of 10 parts. 
    #Change limit from "5" to return the no. of parts you want
    limit: 5) {
    #The total number of results that the search returns
    hits
    results {
      part {
        mpn
        similarParts {
	  #For this query, we return
          # Similar part names, Octopart URL & MPN 
          #Press CTRL+space to explore more fields
          name
          octopartUrl
          mpn
        }
      }
    }
  }
}

Design Query Example

  • Design queries provide data from your Altium 365 account and require you to be signed up for a Nexar account and have an application with the design scope enabled. You will also need to be a member of an Altium 365 workspace.
  •  This multi-step design query requires inputting information from one query to the next.
  • This query will find a component in your workspace by its ID
  • Start by pressing the play button and selecting design1_Workspaces from the dropdown menu
  • Your workspace URL, id, name, and description will be returned. If you see the below, it means you are not a member of any workspaces in Altium 365
"desWorkspaces": []


If you have a response with values...

  • Copy the URL from the response returned.
  • Paste the URL next to workspaceUrl to replace "<WORKSPACE URL FROM PREVIOUS QUERY>" in query design2_Library
  • Press the play button and select design2_Library
  • You will see node ID, name and details, including parameter names and IDs
  • Copy the node ID from the response returned.
  • Paste the node ID next to the id to replace"<NODE ID FROM PREVIOUS QUERY>" in query design3_componentbyID
  • Press the play button and select design3_componentbyID

A component name and description from your workspace will be returned if successful.


#Find component in your workspace by ID
#Design queries often require data from multiple queries to retrieve desired data
        #Step 1: Query for the list of your Altium 365 workspaces & their fields
        query design1_Workspaces {
          desWorkspaces {
            #For this query, we return
            # Workspace url, id, name & description
            #Press CTRL+space to explore more fields
            #Copy URL returned in the response
            #This will be used in Step 2
            url
            id
            name
            description
          }
        }

        #Step 2: Take the URL from the previous query to find your library
        query design2_Library {
          desLibrary (workspaceUrl: "<WORKSPACE URL FROM PREVIOUS QUERY>") {
            components {
              nodes {
                #For this query, we return 
                # Component node ID, name, & parameter names & values
                #Press CTRL+space to explore more fields
                #Copy the node ID returned in the response
                #This will be used in Step 3
                id
                name
                details {
                  parameters {
                    name
                    value
                  }
                }
              }
            }
          }
        }

        #Step 3: Take component node ID from previous query to find component by ID
        query design3_componentbyID {
          desComponentById (id:"<NODE ID FROM PREVIOUS QUERY>"){
            #For this query, we return 
            # Component node ID, name, & component parameter names & values
            #Press CTRL+space to explore more fields
            name
            description
          }
        }

Search Parts

  • This search uses supSearch. The query, 'q', is "3 ohm resistor" and will return many parts, as supSearch allows for partial matches. 
  • The part limit is set to 5. Each part returned will count against your organisation's part limit. By design, supSearch returns 10 parts.
  • Our query returns:
    • Part ID, name and ID
    • Median price for 1000
    • Part category ID and name
    • Manufacturer name and URL


#Search parts
#Return parts based off a descriptive search, e.g. 3 ohm resistor
query partSearch {
  supSearch (
    #Try changing "3 ohm resistor" to a search value of your own
    # This can also be an MPN
    q:"3 ohm resistor", 
    #The API returns a default of 10 parts. 
    #Change limit from "5" to return the no. of parts you want
    limit: 5
    ){
    #The total number of results that the search returns
    hits
    results {
      part {
	    #For this query, we return
        # Part ID, name, MPN, median price
        # Part category & manufacturer 
        #Delete ID & press CTRL+space to explore other queries
        id
        name
        mpn        
        medianPrice1000 {
          quantity
          currency
        }
        category {
          id
          name          
        }
        manufacturer {
          name
          homepageUrl
        }
      }
    }
  }
}

Multi-Part Search

  • This search uses multiSearch and takes multiple exact MPNs.
  • By design, supMultiMatch will return 3 parts. Each part returned will count against your organisation's part limit. 
  • Our query returns:
    • Part ID, name and MPN
#Multiple parts by manufacturer part number
query multiSearch {
    #The API returns a maximum of 3 parts. 
    #supMultiMatch requires an exact MPN match
    supMultiMatch (
        queries: [
            #Try changing "SY55855VKG" to your own part number
            {mpn: "SY55855VKG"},
            {mpn: "SY89832UMG"},
        ]
    ){
        #The total number of results the search returns
        hits
        parts {
            #For this query, we return
            # Part ID, name, & MPN 
            #Press CTRL+space to explore more fields
            id
            name
            mpn
        }
    }
}

Exact Parts by ID

  • This search uses supParts and takes exact part IDs. 
  • Currency has been set as "USD" in this example. By default, prices are returned in the sellers' currency. Using ISO codes, you can set your currency.
  • Our query returns:
    • Part ID, name and MPN
    • Seller company names
    • Offer lead days, packaging time and minimum order quantity
    • Part category ID and name
#Exact parts by part ID
#Return a part by ID, and its price in specified currency

query partsById {
  supParts (
    ##Change the ids "300" & "100" to return your own part
    ids: ["300", "100"],
    #Change "USD" to your currency using ISO currency codes
    #Prices are returned in the sellers set currency
    currency: "USD"
    ){
    #For this query, we return
    # Part info, seller info & part category.    
    #Press CTRL+space to explore more fields
	id
    name
    mpn
    sellers {
      company {
        name
      }
      offers {
        factoryLeadDays
        packaging
        moq
      }
    }
    category {
      id
      name
    }
  }
}

Median Price for 1000 Components

  • This search uses supSearchMPN. The query, 'q', is "acs770" and will return many parts, as supSearchMPN allows for partial matches.
  • Currency has been set as "EUR" in this example. By default, prices are returned in the sellers' currency. Using ISO codes, you can set your currency. 
  • The part limit is set to 5. Each part returned will count against your organisation's part limit. By design, supSearchMPN returns 10 parts.
  • Our query returns:
    • Total number of returned parts
    • Part ID, name and MPN
    • Median price for 1000 (in the default currency)
    • Currency (this is the default currency set by seller)
    • Converted price and currency (set by user in the query)
#Median price for 1000 components in EUR
#Returns the median price at quantity 1000 in a set currency, discarding outliers to provide an estimated average price

query setCurrency {
  supSearchMpn (
    #The query value can be a partial match
    #Change the mpn from "acs770" to your own search
    q: "acs770", 
    #Change currency from "EUR" using ISO currency codes
    currency: "EUR"
    #The API returns a default of 10 parts. 
    #Change limit from "5" to return the no. of parts you want
    limit: 5
    ){
    #Total number of results the search returns
    hits
    results {
      part {
	    #For this query, we return 
        #Part id, name, MPN, median price in set currency
        #Press CTRL+space to explore more fields
        id
        name
        mpn
        medianPrice1000 {
          quantity
          price
          #Default currency is specific to the seller
          currency
          convertedPrice
          #Default value for convertedCurrency is USD
          convertedCurrency
        }
      }
    }
  }
}

Changing Currency & Country

  • This search uses supSearchMPN. The query, 'q', is "SY55855VKG" and will return many parts, as supSearchMPN allows for partial matches.
  • Currency has been set as "GBP" in this example. By default, prices are returned in the sellers' currency. Using ISO codes, you can set your currency.
  • The country has been set as "GB" in this example. By default, the country is set as "US", and affects fields such as inventory level. Using ISO codes, you can set your Country. 
  • The part limit is set to 5. Each part returned will count against your organisation's part limit. By design, supSearchMPN returns 10 parts.
  • Our query returns:
    • Total number of returned parts
    • Part ID, name
    • Seller company name
    • Part offer prices in the currency (set by the seller)
    • Part offer prices in the converted currency (set by the user)
    • Inventory level (Country dependent)
#Price & inventory levels for a set country & currency
#The default currency & country availability will be specified by the seller, unless set in the query

query setCurrencyCountry {
  supSearchMpn (
    #Change "SY55855VKG" to your own search
    q: "SY55855VKG", 
    #Change "GBP" to your currency using ISO currency codes
    currency: "GBP",
    #Change "GB" to see availability in your country using ISO country codes
    country: "GB",
    #The API returns a default of 10 parts. 
    #Change limit from "5" to return the no. of parts you want
    limit: 5
    ){
    #The total number of results the search returns
    hits
    results {
      part {
	    #For this query, we return 
        # Part id, name & seller info, offer prices & inventory level
        #Press CTRL+space to explore more fields
        id
        name
        sellers {
          company {
            name
          }
          offers {  
            prices {
              price
              #Default currency is specific to the seller
              currency
              #Default value for convertedCurrency is USD
              convertedPrice
              convertedCurrency
            }
            #Default availability is in the US
            inventoryLevel
          }
        }
      }
    }
  }
}

Parts by MPN

  • This search uses supSearchMPN. The query, 'q', is "acs770" and will return many parts, as supSearchMPN allows for partial matches.
  • The part limit is set to 5. Each part returned will count against your organisation's part limit. By design, supSearchMPN returns 10 parts.
  • Our query returns:
    • Total number of returned parts
    • Part ID, name, and MPN
    • Median price for 1000
    • Category id and name


#Parts by MPN
#Uses manufacturer part number (MPN) "acs770" to finds the median price for 1000 parts, and the category it belongs to

query partsByMpn {
  #Try changing the value "acs770" to return a part of your own
  supSearchMpn (
    q: "acs770",
    #By design, when searching queries the API will return a default of 10 parts. Remove or change the limit parameter from "5" to return the number of parts you want
    limit: 5){
    #The total number of results that the search returns
    hits
    results {
      part {
      #For this query, we have chosen to return the part id, name, MPN, medianPrice1000 & category
        #Press CTRL+space to find out what else you can return
        id
        name
        mpn
        medianPrice1000 {
          quantity
          price
        }
        category {
          id
          name
        }
      }
    }
  }
}

Specific Suppliers Match

  • This search uses supMultiMatch to find whether a specific supplier exists for a part. The queries require exact MPNs and will return a default maximum of 3 parts
  • You can filter or sort your query results on the manufacturer name or ID, found here. Note that other distributors will also be listed if they sell this part.
  • Our query returns:
    • Total number of results
    • Part name and MPN
    • Seller company name
    • Offer prices and currency
#Specific suppliers match
#Filter parts for selected suppliers 

#The list of distributors can be found here & can be queried by ID or name: https:#octopart.com/api/v4/values
#If other distributors also sell this part, they will also be listed & can be filtered out later.
query MultiMatch {
  supMultiMatch(
    queries: [{
      #supMultiMatch requires an exact MPN match
      #Try changing "FH12-5S-1SH(55)" to a MPN of your choice
      mpn: "FH12-5S-1SH(55)",
      #By design, the API will return a maximum default of 3 parts
      #Try changing "2" to a value of your choice to return that number of parts
      limit: 2
    }]
    #These are specific distibutor ids. Try changing them to a distributor of your choice (e.g. "12947" or "Worldway Electronics")
    #Seller IDs can be found here: https://octopart.com/api/v4/values#sellers
    options: {filters: {distributor_id: ["459", "Newark", "1106", "3261"]}}
  ) {
    #The total number of results that the search returns
    hits
    parts {
      #For this query, we have chosen to return the MPN, part name, along with seller names, offer prices & currency
      #Press CTRL+space to find out what else you can return
      mpn
      name
      sellers {
        company {
          name
        }
        offers {
          prices {
            price
            currency
          }
        }
      }
    }
  }
}

Distributors With Inventory

  • This search uses supMultiMatch to find whether a specific supplier exists for a part. The queries require exact MPNs and will return a default maximum of 3 parts
  • You can filter or sort your query results on the manufacturer name or ID, found here, that have the part in stock.  Note that other distributors will also be listed if they sell this part.
  • Our query returns:
    • Total number of results
    • Part name and MPN
    • Seller company name
    • Offer prices and currency


#Find exact distributors with parts in stock
#If other distributors also sell this part, they will also be listed
#If the distributors selected have no parts in stock, there will be no results
query MultiMatch {
  supMultiMatch(
    queries: [{
    #supMultiMatch requres an exact MPN match
    #Try changing "FH12-5S-1SH(55)" to a MPN of your choice
    mpn: "FH12-5S-1SH(55)",
    #The API will return a maximum default of 3 parts
    #Change "2" to return that number of parts
    limit: 2
    }]
    #Change distributor ID to one of your choice 
    #(e.g. "2454" or "Future Electronics")
    options: {requireStockAvailable: true, filters: {distributor_id: ["Newark", "459"]}}
  ) {
    #Total number of results that the search returns
    hits
    parts {
      #For this query, wereturn 
      # Part MPN, name, seller names, ID, & offer inventory level
      #Press CTRL+space to explore more fields
      mpn
      name
      sellers {
        company {
          name
          id
        }
        offers {
          inventoryLevel
        }
      }
    }
  }
}

Categories by IDs

  • This search uses supCategories to query all categories by path and ID. Category paths and IDs can be found here.
  • This query does not affect your part limit, as no parts are turned.
  • Our query returns:
    • Category ID, name, path and the number of parts associated with that category
#Categories by IDs
#Query categories by path or ID. Omit these values to fetch all categories

query categories {
  supCategories(
    #Change "/electronic-parts" to "/electronics-parts/cables-and-wire
    paths: "/electronic-parts"
    ids: "4311"
  ){
    #For this query, we return
    # Part ID, name, path and no. parts in that category
    #Press CTRL+space to explore more fields
    id
    name
    path
    numParts
  }
}

Manufacturers by ID

  • This search uses supManufacturers to query all manufacturers by name and ID. Manufacturer names and IDs can be found here.
  • This query does not affect your part limit, as no parts are turned.
  • Our query returns:
    • Manufacturer ID, name, aliases and homepage URL


#Manufacturers by ID
#Query manufacturers by name or ID. Omit these values to fetch all categories

query Manufacturers {
  #Remove < (ids:["5081", "5276"]) > to see all manufacturers available
  supManufacturers(ids: ["AEG", "5276"]) {
    #For this query, we return
    # Category id, name, aliases & URL
    #Press CTRL+space to explore more fields
    id
    name
    aliases
    homepageUrl
  }
}

Sellers by ID

  • This search uses supManufacturers to query all manufacturers by name and ID. Seller names and IDs can be found here.
  • This query does not affect your part limit, as no parts are turned.
  • Our query returns:
    • Seller ID, name, aliases and homepage URL
#Sellers by ID
#Query sellers by name or ID. Omit these values to fetch all categories

query Sellers {
  #Remove < (ids:["4025", "15313"]) > to see all sellers available
  supSellers(ids: ["DigiKey", "15313"]) {
    #For this query, we return 
    # Seller id, name, aliases & URL
    #Press CTRL+space to explore more fields
    id
    name
    aliases
    homepageUrl
  }
}



Query by Variables

  • Querying by variables allows the variables to be changed without changing the bulk of the code in the IDE
  • Variables are taken from the Query Variable box
  • The Voyager provides more information on variable and type names that you can try out for yourself.


#Query by Variables
#Use variables to query from

query queryByVariables($queries: [SupPartMatchQuery!]!) {
  supMultiMatch (
    currency: "EUR",
    #Queries are taken from the Query Variable box below
    #Change the MPN value in Query Variables box below to search your own MPN
    queries: $queries
  ){
    parts {
      #For this query, we return 
      # Part MPN, manufacturer name, price and converted price
      #Press CTRL+space to explore more fields
      mpn
      manufacturer{
        name
        price
        convertedPrice
      }
    }
  }
}

#To go in the Query Variables box
{"queries":[{"start": 0, "limit": 1, "mpn": "ACS770ECB-200U-PFF-T"}]}

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article