Set Up Your Environment

Before we begin, make sure you have Python installed on your system. You can download it from the official website: https://www.python.org/downloads/

We'll also be using the requests library to make API requests. If you don't have it installed, you can do so using pip:

pip install requests

Obtain API Key

To access the Sourcengine API, you need an API key. If you don't have one, please reach out to your account manager.

Usage

In the context of the Sourcengine API, there are two primary types of searches: searching for parts and getting analytical information. Let's break down the difference between these two types of searches:

Searching for Parts

When you search for parts using the Sourcengine API, you are querying the database for electronic components based on various parameters such as Manufacturer Part Number (MPN), Manufacturer, category, full text search, and more. This type of search helps you find detailed information about specific electronic components, including their specifications, datasheets, availability, and potentially multiple offers from different suppliers.

For example, if you're looking for a specific type of microcontroller, you can use the API to search for it by providing its MPN or other relevant details. The API will return information about the microcontroller itself, such as its technical specifications, package type, pin configuration, and more. This type of search is useful when you want to gather detailed information about electronic components to make informed purchasing decisions.

Time Series and Analytics

When using the Sourcengine API, you might also be looking for marketing intelligence data for a particular electronic component, typically identified by its SKU. For instance, if you have a specific SKU in mind and you want to know what was the price of that component 1 year ago, if it is good or not for new designs, how much stock was available and how much stock we believe there might be in the future, you would perform an analytical query.

The forecasting model in the Sourcengine Analytics API allows you to include forecast data along with the historical time series. The forecast is available for the specified period, and you can choose the granularity of the forecast. When you include the forecast parameter in your API request and specify either "quarter" or "year," the API will return not only historical time series data but also forecasted values for the chosen period.

The API endpoint for getting time series data for a specific SKU is:

/api/parts/{sku}/analytics/time-series/{datapoint}

You need to replace {sku} with the actual SKU and {datapoint} with the specific data point you want (e.g., "inventory," "market-availability," "lead-time," or "price").

The endpoint requires the following parameters:

sku: The SKU for which you want to get data.
datapoint: The specific data point you are interested in.
start and end: Optional parameters to specify the date range in the format YYYY-MM-DD.
period: Optional parameter to aggregate results on (e.g., "weekly").
forecast: Optional parameter to include forecast data, with options "quarter" or "year."

The response follows the structure defined in the PartTimeSeries schema. It includes data for the specified datapoint, such as inventory, price, market availability, or lead time, depending on your request. The forecasted values will be included in the response if you've opted to include forecasts.

The forecast data will typically extend beyond the latest date in the historical time series, providing insights into the expected future values based on the forecasting model employed by Sourcengine.

Ensure that you handle the response appropriately in your application code to extract and utilize both historical and forecast data as needed for your analytics or planning purposes.

You can find more detailed information about the endpoint here: https://dev.sourcengine.com/reference/get_app_api_analytics_gettimeseries

Make API Requests

Now let's write a Python script to search for offers based on an MPN and Manufacturer using the Sourcengine API:

import requests

API_TOKEN = 'YOUR_TOKEN'

def match_parts(searches):
    headers = {
        'accept': 'application/json',
        'content-type': 'application/json',
        'authorization': 'Bearer ' + API_TOKEN
    }

    response = requests.post('https://catalog.sourcengine.com/api/parts/search-multiple', headers=headers, json={'searches': searches}).json()

    return response['results']

def get_inventory(sku):
    headers = {
        'content-type': 'application/json',
        'authorization': 'Bearer ' + API_TOKEN
    }
    
    params = {
        'start': '2024-02-01',
        'period': 'weekly',
        'forecast': 'year',
    }
    print('Fetching inventory for: ' + sku)

    return requests.get('/api/parts/'+ sku +'/analytics/time-series/inventory', headers=headers, params=params).json()


results = match_parts([{'mpn': 'MAX232IN', 'manufacturer': 'Texas Instruments'}])
for result in results:
    for part in result['parts']:
        print('Matched: ' + part['sku'])
        print('MPN Match type: ' + part['match']['mpn'])
        print('Manufacturer match: ' + str(part['match']['manufacturerMatched']))

        # Now that we have a match, get inventory time series
        time_series = get_inventory(part['sku'])
        
        # Process and analyze the time series data as needed
        print(time_series)

Replace YOUR_TOKEN, with your actual API key.

Step 4: Run the Script

Save the script to a .py file and run it using your terminal:

python get_inventory.py