brokerbin

BrokerBin API wrapper for Node.js

☁️ Installation

# Using npm
npm install --save brokerbin

# Using yarn
yarn add brokerbin

📋 Example

const BrokerBinREST = require("brokerbin");

// REST Example
(async () => {
    const bbClient = new BrokerBinREST({
        username: process.env.BROKERBIN_USERNAME || "your username",
        token: process.env.BROKERBIN_TOKEN || process.env.BROKERBIN_SOAP_KEY || "your token",
    })

    const result = await bbClient.partSearch({
        query: "F238F",
    });

    console.log(result)
})().catch(console.error)

📝 Documentation

BrokerBinREST(data)

Initializes a new BrokerBinREST instance.

Example:

const BrokerBinREST = require("brokerbin").REST

const bbClient = new BrokerBinREST({
  username: "webdevops",
  token: "..."
})

Params

• Object data: The BrokerBinREST data:
  • username (String): The BrokerBin username (default: process.env.BROKERBIN_USERNAME).
  • token (String): The BrokerBin token (default: process.env.BROKERBIN_TOKEN).
  • api_root (String): The BrokerBin API root (default: https://search.brokerbin.com/api/v2).
  • cache_dir (String): The directory to store the cache (default: ~/.brokerbin-cache/).
  • cache_ttl (Number): The time to live for the cache in seconds (default: 7200). You can also set this using the BROKERBIN_CACHE_TTL environment variable.

Return

• BrokerBinREST The BrokerBinREST instance.

getCacheKey(query)

Get the cache key for a given query.

Params

• Object query: The axios query.

Return

• String The cache key.

getCachePath(key)

Get the cache path for a given key.

Params

• String key: The cache key.

Return

• String The cache path.

cacheValid(key)

Check if the cache is valid for a given key.

Params

• String key: The cache key.

Return

• Boolean true if the cache is valid, false otherwise.

getCachedResponse(query)

Get the cached response for a given query.

Params

• Object query: The axios query.

Return

• Object The cached response.

setCachedResponse(query, data)

Set the cached response for a given query.

Params

• Object query: The axios query.
• Object data: The data to cache.

Return

• Promise A promise that resolves when the cache is set.

updateGlobalMetadata(data)

Update the global metadata file with the current rate limit.

Params

• Object data: The data to cache.

Return

• Promise A promise that resolves when the cache is set.

request(endpoint, query, returnData)

Make a request to the BrokerBin API.

Params

• String endpoint: The endpoint to request.
• Object query: The query object.
• Boolean returnData: If true, the function will return the data. If false, it will return the response object.

Return

• Promise The response data or the response object.

partSearch(data)

Search for parts by part number.

Example

// Initialize the BrokerBin instance
const bbClient = new BrokerBinREST({
   username: "webdevops",
   token: "..."
})

// Run a search
bbClient.partSearch({
  query: "188122-B22",
})

Params

• Object data: The search data:
  • query (required) the search string, part number
  • fields db fields to search against, possible values: partsno,manufacturer,description,condition (default: partsno)
  • mfg[] filter by manufacturer
  • cond[] filter by condition
  • country[] filter by country
  • region[] filter by region
  • state[] filter by state
  • size number of results to return (default: 10)
  • offset number of results to skip (default: 0, max: 900)
  • fuzziness percentage of search terms that require matches (default: 100%)
  • first myVen show first (boost 200%)
  • last myVen show last (de-boost 90%)
  • never myVen show never (filter out)
  • priced filter priced parts only
  • age only match parts this many days old, or less
  • sort[index][field]=direction the index, field and direction (default: sort[0][_score]=desc&sort[1][age]=desc&sort[2][company.original]=asc)
    • where index is an integer with which the lowest number takes the highest precedence and no numbers repeat -- ex: 0, 1, 2
    • and where the valid sorting fields are: age, clei.original, company.original, condition, country, manufacturer, partsno.original, price, qty, region, state
    • and where the valid sorting directions are: asc, desc

Return

• Promise The response data looks like this:

{
    "meta": {
        "total": 18,
        "manufacturers": [
            {
                "key": "HP",
                "doc_count": 18
            }
        ],
        "conditions": [
            {
                "key": "REF",
                "doc_count": 17
            },
            {
                "key": "NEW",
                "doc_count": 1
            }
        ],
        "states": [
            {
                "key": "FL",
                "doc_count": 6
            },
            {
                "key": "WY",
                "doc_count": 6
            },
            {
                "key": "TX",
                "doc_count": 2
            },
            {
                "key": "KY",
                "doc_count": 1
            },
            {
                "key": "MN",
                "doc_count": 1
            },
            {
                "key": "NY",
                "doc_count": 1
            },
            {
                "key": "WA",
                "doc_count": 1
            }
        ],
        "countries": [
            {
                "key": "USA",
                "doc_count": 18
            }
        ],
        "regions": [
            {
                "key": "North America",
                "doc_count": 18
            }
        ],
        "request": {
            "count": 33,
            "limit": 100
        }
    },
    "data": [
        {
            "company": "Techlogix USA",
            "country": "USA",
            "part": "188122-B22",
            "clei": "",
            "mfg": "HP",
            "cond": "REF",
            "description": "HP 18.2GB 15000RPM Ultra-160 SCSI 80-Pin LVD Hot-Pluggable 3.5-inch Hard Drive",
            "price": 0,
            "qty": 1,
            "age_in_days": 6
        },
        {
            "company": "Techlogix USA",
            "country": "USA",
            "part": "188122-B22",
            "clei": "",
            "mfg": "HP",
            "cond": "REF",
            "description": "HP 18.2GB 15000RPM Ultra-160 SCSI 80-Pin LVD Hot-Pluggable 3.5-inch Hard Drive",
            "price": 0,
            "qty": 1,
            "age_in_days": 7
        },
        "truncated..."
    ]
}

partPrefix(data)

Search for parts by the beginning (or complete) of a part number.

Params

• Object data: An object containing the following data:
  • query (required) the search string, part number, or beginning of part number
  • mfg[] filter by manufacturer
  • cond[] filter by condition
  • country[] filter by country
  • region[] filter by region
  • state[] filter by state
  • size number of results to return (default: 10)
  • offset number of results to skip (default: 0, max: 900)
  • first myVen show first (boost 200%)
  • last myVen show last (de-boost 90%)
  • never myVen show never (filter out)
  • priced filter priced parts only
  • age only match parts this many days old, or less
  • sort[index][field]=direction the index, field and direction (default: sort[0][_score]=desc&sort[1][age]=desc&sort[2][company.original]=asc)
    • where index is an integer with which the lowest number takes the highest precedence and no numbers repeat -- ex: 0, 1, 2
    • and where valid sorting fields are: age, clei.original, company.original, condition, country, manufacturer, partsno.original, price, qty, region, state
    • and where valid sorting directions are: asc, desc

Return

• Promise The response data looks like this:

{
   "meta": {
       "total": 18,
       "request": {
           "count": 16,
           "limit": 50
       },
       "manufacturers": [
           {
               "key": "HP",
               "doc_count": 18
           }
       ],
       "conditions": [
           {
               "key": "REF",
               "doc_count": 16
           },
           {
               "key": "NEW",
               "doc_count": 2
           }
       ],
       "states": [
           {
               "key": "FL",
               "doc_count": 8
           },
           {
               "key": "NY",
               "doc_count": 3
           },
           {
               "key": "KY",
               "doc_count": 2
           },
           {
               "key": "TX",
               "doc_count": 2
           },
           {
               "key": "WA",
               "doc_count": 2
           },
           {
               "key": "MN",
               "doc_count": 1
           }
       ],
       "countries": [
           {
               "key": "USA",
               "doc_count": 18
           }
       ],
       "regions": [
           {
               "key": "North America",
               "doc_count": 18
           }
       ],
       "price": {
           "count": 18,
           "min": 0,
           "max": 65,
           "avg": 6.833333333333333,
           "sum": 123
       },
       "qty": {
           "count": 18,
           "min": 1,
           "max": 69,
           "avg": 7.277777777777778,
           "sum": 131
       }
   },
   "data": [
       {
           "company": "Serverworlds.com",
           "country": "USA",
           "part": "188122-B22",
           "clei": "",
           "mfg": "HP",
           "cond": "REF",
           "description": "18.2GB U3 15K SCSI 1 hotplug",
           "price": 65,
           "qty": 69,
           "age_in_days": 0
       },
       {
           "company": "Blitz Network Solutions Inc.",
           "country": "USA",
           "part": "188122-B21",
           "clei": "",
           "mfg": "HP",
           "cond": "REF",
           "description": "HP 18.2GB 15000RPM Ultra-160 SCSI Hot-Pluggable LVD 80-Pin 3.5-inch Hard Drive 5-7 Business Days Lead Time",
           "price": 0,
           "qty": 7,
           "age_in_days": 0
       }
       ,{"truncated":"truncated..."}
   ]
}

partStatsHistogram(data)

Produce 90 day histogram for a single part with extended stats on price and qty.

Params

• Object data: An object containing the following data:
  • query (required) the search string, part number
  • mfg[] filter by manufacturer
  • cond[] filter by condition
  • country[] filter by country
  • region[] filter by region
  • state[] filter by state
  • never myVen show never (filter out)
  • priced filter priced parts only
  • interval the timeframe for the historgram (day,week,month, or year)
  • from include dates greater than or equal to this date
  • to include dates less than or equal to this date

Return

• Promise The response data looks like this:

{
   "meta": {
       "request": {
           "count": 19,
           "limit": 25
       },
       "manufacturers": [
           {
               "key": "HP",
               "doc_count": 182
           }
       ],
       "conditions": [
           {
               "key": "REF",
               "doc_count": 154
           },
           {
               "key": "NEW",
               "doc_count": 28
           }
       ],
       "states": [],
       "countries": [
           {
               "key": "USA",
               "doc_count": 182
           }
       ],
       "regions": [
           {
               "key": "North America",
               "doc_count": 182
           }
       ]
   },
   "data": [
       {
           "date": "2023-02-01 00:00:00",
           "price_weighted_by_qty": 32.206832871652814,
           "price_stats": {
               "count": 182,
               "min": 0,
               "max": 45,
               "avg": 8.131868131868131,
               "sum": 1480,
               "sum_of_squares": 57320,
               "variance": 248.81777563096244,
               "variance_population": 248.81777563096244,
               "variance_sampling": 250.19245947422743,
               "std_deviation": 15.773958781198917,
               "std_deviation_population": 15.773958781198917,
               "std_deviation_sampling": 15.817473232922742,
               "std_deviation_bounds": {
                   "upper": 39.679785694265966,
                   "lower": -23.416049430529704,
                   "upper_population": 39.679785694265966,
                   "lower_population": -23.416049430529704,
                   "upper_sampling": 39.76681459771362,
                   "lower_sampling": -23.503078333977353
               }
           },
           "qty_stats": {
               "count": 182,
               "min": 1,
               "max": 73,
               "avg": 11.901098901098901,
               "sum": 2166,
               "sum_of_squares": 113284,
               "variance": 480.80340538582294,
               "variance_population": 480.80340538582294,
               "variance_sampling": 483.45977779126946,
               "std_deviation": 21.927229769987427,
               "std_deviation_population": 21.927229769987427,
               "std_deviation_sampling": 21.98771879461963,
               "std_deviation_bounds": {
                   "upper": 55.75555844107376,
                   "lower": -31.953360638875953,
                   "upper_population": 55.75555844107376,
                   "lower_population": -31.953360638875953,
                   "upper_sampling": 55.87653649033817,
                   "lower_sampling": -32.07433868814036
               }
           }
       }
   ]
}

rfqHistogram(data)

Aggregated RFQ counts for a single part.

Params

• Object data: An object containing the following data:
  • query (required) the search string, part number
  • mfg[] filter by manufacturer
  • cond[] filter by condition
  • from include dates greater than or equal to this date
  • to include dates less than or equal to this date
  • size number of results to return (default: 10)
  • offset number of results to skip (default: 0, max: 900)
  • fuzziness percentage of search terms that require matches (default: 100%)

Return

• Promise The response data looks like this:

{
   "meta": {
       "request": {
           "count": 19,
           "limit": 25
       },
       "manufacturers": [
           {
               "key": "HP",
               "doc_count": 50
           }
       ],
       "conditions": [
           {
               "key": "NEW",
               "doc_count": 50
           }
       ]
   },
   "data": [
       {
           "date": "2023-01-30 00:00:00",
           "rfqs": 5
       },
       {
           "date": "2023-02-06 00:00:00",
           "rfqs": 17
       },
       {
           "date": "2023-02-13 00:00:00",
           "rfqs": 6
       },
       {
           "date": "2023-02-20 00:00:00",
           "rfqs": 6
       },
       {
           "date": "2023-02-27 00:00:00",
           "rfqs": 7
       },
       {
           "date": "2023-03-06 00:00:00",
           "rfqs": 9
       }
   ]
}

supplyAndDemandHistogram(data)

Aggregated Search and Result counts for a single part.

Params

• Object data: An object containing the following data:
  • query (required) the search string, part number
  • mfg[] filter by manufacturer
  • age only include parts this many days old, or less
  • fuzziness percentage of search terms that require matches (default: 100%)
  • interval the timeframe for the historgram (day,week,month, or year)
  • from include dates greater than or equal to this date
  • to include dates less than or equal to this date

Return

• Promise The response data looks like this:

{
    "meta": {
        "request": {
            "count": 12,
            "limit": 25
        },
        "manufacturers": [
            {
                "key": "HP",
                "doc_count": 18
            },
            {
                "key": "HPE",
                "doc_count": 17
            },
            {
                "key": "ARUBA NETWORKS",
                "doc_count": 13
            },
            {
                "key": "HPE - ARUBA SWITCHING",
                "doc_count": 3
            }
        ]
    },
    "data": [
        {
            "date": "2023-02-01 00:00:00",
            "searches": 2113,
            "avg_result_count": 688
        }
    ]
}

topParts(data)

Aggregated search counts by part for a given mfg sorted by number of searches in descending order

Params

• Object data: An object containing the following data:
  • query (required) the search string, manufacturer
  • fuzziness percentage of search terms that require matches (default: 100%)
  • from include dates greater than or equal to this date
  • to include dates less than or equal to this date
  • size the number of parts to return

Return

• Promise The response data looks like this:

{
   "meta": {
       "request": {
           "count": 19,
           "limit": 25
       }
   },
   "data": [
       {
           "part": "WS-C2960X-24PS-L",
           "searches": 5475
       },
       {
           "part": "WS-C2960X-48FPS-L",
           "searches": 4154
       },
       {
           "part": "WS-C2960X-48FPD-L",
           "searches": 3661
       },
       {
           "part": "GLC-LH-SMD",
           "searches": 3244
       },
       {
           "part": "C9300-NM-8X",
           "searches": 2783
       },
       {
           "part": "N9K-C93180YC-EX",
           "searches": 2442
       },
       {
           "part": "STACK-T1-50CM",
           "searches": 2410
       },
       {
           "part": "ASR1001-X",
           "searches": 2394
       },
       {
           "part": "C9200L-48P-4X-E",
           "searches": 1955
       },
       {
           "part": "WS-C2960X-48LPS-L",
           "searches": 1886
       }
   ]
}

matches(data)

Find users and company who searched for an exact part number.

Params

• Object data: An object containing the following data:
  • query (required) the search string, part number
  • from include matches on dates greater than or equal to this date
  • never myVen show never (filter out)
  • in_stock only include searchers who had the item in-stock when the search occurred

Return

• Promise The response data looks like this:

{
   "meta": {
       "request": {
           "count": 44,
           "limit": 100
       }
   },
   "data": {
       "query": "c9300-nm-8x",
       "from": "2024-06-20",
       "results": {
           "count": 17,
           "matches": [
               {
                   "company_name": "Network Craze Technologies",
                   "company_contact": "James Froio",
                   "search_query": "C9300-NM-8X",
                   "qty": 26,
                   "age": "51 minutes ago"
               },
               {
                   "company_name": "NW Remarketing",
                   "company_contact": "Louis Zahler",
                   "search_query": "C9300-NM-8X",
                   "qty": 5,
                   "age": "3 hours ago"
               },
               {
                   "company_name": "Refub Tech",
                   "company_contact": "Saless Team",
                   "search_query": "C9300-NM-8X",
                   "qty": 4,
                   "age": "4 hours ago"
               },
               {
                   "company_name": "Neon Devices LLC",
                   "company_contact": "Nohail K",
                   "search_query": "C9300-NM-8X",
                   "qty": 52,
                   "age": "4 hours ago"
               },
               {
                   "company_name": "Network Integrators LTD.",
                   "company_contact": "Purchasing Team",
                   "search_query": "C9300-NM-8X",
                   "qty": 1,
                   "age": "5 hours ago"
               },
               {
                   "company_name": "Link-US LLC",
                   "company_contact": "Basem Toma",
                   "search_query": "C9300-NM-8X",
                   "qty": 1,
                   "age": "6 hours ago"
               },
               {
                   "company_name": "Crisp Technologies LLC",
                   "company_contact": "Steve Murphy",
                   "search_query": "C9300-NM-8X",
                   "qty": 10,
                   "age": "6 hours ago"
               },
               {
                   "company_name": "Nordic Computer",
                   "company_contact": "Ozren Nezic",
                   "search_query": "C9300-NM-8X",
                   "qty": 1,
                   "age": "11 hours ago"
               },
               {
                   "company_name": "Euro IT Solution LTD",
                   "company_contact": "Javed A.",
                   "search_query": "C9300-NM-8X",
                   "qty": 2,
                   "age": "12 hours ago"
               },
               {
                   "company_name": "Knowledge Computers PTE",
                   "company_contact": "N/A",
                   "search_query": "C9300-NM-8X",
                   "qty": 2,
                   "age": "12 hours ago"
               },
               {
                   "company_name": "Euro IT Solution LTD",
                   "company_contact": "Javed A.",
                   "search_query": "C9300-NM-8X",
                   "qty": 2,
                   "age": "12 hours ago"
               },
               {
                   "company_name": "Units Enterprise",
                   "company_contact": "Andy Bryant",
                   "search_query": "C9300-NM-8X",
                   "qty": 2,
                   "age": "1 day ago"
               },
               {
                   "company_name": "Units Enterprise",
                   "company_contact": "Jim Henderson",
                   "search_query": "C9300-NM-8X",
                   "qty": 2,
                   "age": "1 day ago"
               },
               {
                   "company_name": "Units Enterprise",
                   "company_contact": "Jim Henderson",
                   "search_query": "C9300-NM-8X",
                   "qty": 2,
                   "age": "1 day ago"
               },
               {
                   "company_name": "Knowledge Computers USA",
                   "company_contact": "Travis Oestreich",
                   "search_query": "c9300-nm-8x",
                   "qty": 4,
                   "age": "1 day ago"
               },
               {
                   "company_name": "Colorado Peak Technologies,Inc",
                   "company_contact": "Alex Myers",
                   "search_query": "C9300-NM-8X",
                   "qty": 3,
                   "age": "1 day ago"
               },
               {
                   "company_name": "eGoods Supply, Inc.",
                   "company_contact": "Norman",
                   "search_query": "C9300-NM-8X",
                   "qty": 4,
                   "age": "1 day ago"
               }
           ]
       }
   }
}

---

❓ Get Help

There are few ways to get help:

1. Please post questions on Stack Overflow. You can open issues with questions, as long you add a link to your Stack Overflow question.
2. For bug reports and feature requests, open issues. 🐛

😋 How to contribute

Have an idea? Found a bug? See how to contribute.

📜 License

MIT © Bloggify