Getting Started

Examples in Python of how to effectively use the Particl API

The Particl API provides programmatic access to Particl's data set, allowing customers to streamline data into their own systems. It's a REST api that allows apps to query company and product level data.

For quick start examples of how to effectively use Particl's API see below.

Visit API Reference to see all available endpoints.

Authentication

The Particl API uses API keys to authenticate requests. API keys are managed in the My Account page in the Particl App. Authorization is done through an Authorization header.

headers = {
    'authorization': '<your-api-token>',
}

Find a Company's ID with Company Search

Particl uses IDs internally to connect all data. Many companies hoping to use the Particl API begin with a list of domains. In order to connect a domain to an ID, you can hit the Company Search endpoint.

import requests
import json

# constants
domain_to_search = "kith.com"
headers = {
    'authorization': '<your-api-token>',
}
params = (
    ('domain', domain_to_search),
)

# make a response
response = requests.get('https://api.particl.com/companies/list', headers=headers, params=params)

# print response
print(json.loads(response.text))

This response will have a list of companies matching the domain.

📘

API Development in progress

We're currently working on the ability to query endpoints by passing in a domain as a parameter, for now we require users to first hit our company search endpoint to collect IDs.

The reason being domains are not cemented in stone (ie can change over time) and there are issues with uniqueness when you introduce subdomains and localized domains.

Get Company Sales over a period of time

With a company ID, you can query an endpoint for sales at a given point in time, or for a range of dates. The API will return totaled numbers for the period, as well as a list of time series data for each day in the range.

import requests
import json

# constants
company_id = "1000835"
headers = {
    'authorization': '<your-api-token>',
}
params = (
  ('start_date', "2022-02-14"),
  ('end_date', "2022-02-14")
)

# make a response
response = requests.get(f"https://api.particl.com/companies/{company_id}/sales", headers=headers, params=params)

# print response
print(json.loads(response.text))

This example is for a single company. This code can be extended to include multiple domains, from a CSV, or a database.

Getting Company Sales for multiple Companies over a period of time

The following example pulls company level sales over a date range.

As input the code takes a CSV file with one column of company domains. It would look something like this:

domain
bombas.com
kith.com
allbirds.com

Using the Company Search endpoint, you get back a list of Particl company id's that data is available for.

import requests
import json
import pandas as pd
import concurrent.futures

headers = {
    'authorization': '<your-api-token>',
}

# create a pandas dataframe from the input CSV file
companies_df = pd.read_csv('/file/path/company_domains.csv')
domains = list(companies_df.domain)

def get_company_id(domain):
    search_params = (
        ('domain', domain),
    )
    response = requests.get('https://api.particl.com/companies/list', headers=headers, params=search_params)

    response = json.loads(response.text)
    
    if len(response['companies']) != 0:
        company = response['companies'][0]
        print(domain)
        return company['id']
    else:
        return -1


futures = []
with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
    for domain in domains:
        futures.append(executor.submit(get_company_id, domain))
        
companies = []
for future in futures:
    company = future.result()
    companies.append(company)

Then, using those company IDs, using the Company Sales endpoint you can retrieve sales data for an assigned date range.

import requests
import json
import pandas as pd
import concurrent.futures

headers = {
    'authorization': 'INSERT API KEY',
}

# create a pandas dataframe from the input CSV file
companies = ['1000012', '1764706', ....., '1471648' ]

# define the date range to fetch
params = (
    ('start_date', '2022-01-01'),
    ('end_date', '2022-01-31')
)


def get_company_sales_concurrent(company_id):    
    response = response = requests.get(f'https://api.particl.com/companies/{company_id}', headers=headers)
    c = json.loads(response.text)
    if 'No Company Found with company_id' not in c:
        print(company_id)
        name = c['name']
        domain = c['domain']
        
        response = requests.get(f'https://api.particl.com/companies/{company_id}/sales', headers=headers, params=params)
        data = json.loads(response.text)
        df = pd.DataFrame()
        for day in data['timeseries']:
            row = {
                'company_id': str(int(company_id)),
                'date': day['date'],
                'name': name,
                'domain': domain,
                'sales_revenue': day['revenue'],
                'sales_volume': day['units_moved']
                }
            df = df.append(row, ignore_index=True)
    return df
                       
# gather results in a new dataframe        
df_results = pd.DataFrame()

futures = []
with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
    for company_id in companies:
        if company_id != -1:
            futures.append(executor.submit(get_company_sales_concurrent, company_id))

for future in futures:
    company = future.result()
    df_results = df_results.append(company, ignore_index=True)
    
# save results to an output CSV file
df_results.to_csv('/file/path/report.csv')

📘

Note:

This code also utilizes python's concurrent futures package which allows the code to make concurrent requests to the Particl API which speeds up the code due to network latency.