Quickstart Examples

This is a quickstart guide to our API. It will show you how to get started and how to use it to find information about companies and their supply chains.

info

To get the most from the API, we recommend briefly reading the FAQ to understand the concepts behind the data, especially clustering.

Company Search

/companies/

You can use this endpoint to search for companies by name, city, country, website or identifier. Use the limit (defaults to 10) and offset parameters to paginate through the results.

tip

The default search options only search for parent companies of the clusters created and any company not in a cluster. To search for all companies in the database, use the include_subsidiaries=true parameter.

The response includes a number of important fields to help with matching:

Field	Description
search_similarity	If a name is provided in the input, this returns the trigram similarity to the record.
count_suppliers	The number of suppliers in the database for the company.
count_customers	The number of customers in the database for the company.
cid_id	The identifier of the cluster the company belongs to.

A simple example

Request to search for companies by name.

curl -X 'GET' 'http://<api_url>/companies/?name=boeing' -H 'accept: application/json'

Response

{
  "next": "http://<api_url>/companies/?limit=10&name=boeing&offset=10",
  "previous": null,
  "results": [
    {
      "search_similarity": 0.7,
      "vid": "boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e",
      "cid_id": "boeing",
      "name": "Boeing Co",
      "domains": [
        "boeing.com"
      ],
      "websites": [
        "https://www.boeing.com/"
      ],
      "company_legal_name": "Boeing Co",
      "description": "aerospace and defense manufacturer in the United States",
      "count_supplier_evidence": 3094,
      "count_customer_evidence": 5957,
      "count_customers": 558,
      "count_suppliers": 561,
      ...
    }
    ...
  ]
}  

Company Profile Lookup

/companies/{vid}/

Use this endpoint to get information about a specific company. The company is identified by its vid - a unique identifier we assign to each company in our database. Use the company search endpoint to find the vid for a company.

Here is a list of the fields on the company profile and their descriptions:

Field	Description
vid	The unique identifier for the company.
cid_id	The identifier of the cluster the company belongs to.
name	The name of the company. Where possible this is the legal name.
domains	A list of domains associated with the company.
websites	A list of websites associated with the company.
company_legal_name	The legal name of the company.
description	A description of the company.
count_supplier_evidence	The number of evidences in the database for the supply relationships.
count_customer_evidence	The number of evidences in the database for the customer relationships.
count_customers	The number of customers in the database for the company.
count_suppliers	The number of suppliers in the database for the company.
identifiers	A list of identifiers associated with the company.
domiciled_country	ISO3166 long form of the country the company is domiciled in.
incorporated_country	ISO3166 long form of the country the company is incorporated in.
incorporation_date	Date and time of company incorporation.
ipo_date	Date and time of company incorporation.
is_active	Whether the company is active.
is_freight_forwarder	Whether the company is a freight forwarder.
is_public	Whether the company is publicly listed.
hq_phone_number	Phone number of the headquarters.
addresses	A list of addresses associated with the company.

Company Suppliers & Customers

/companies/{vid}/suppliers/

/companies/{vid}/customers/

Use these endpoints to get a list of a company's suppliers or customers, ordered by the confidence of the relationship. Each item in the response list is a relationship terminating or originating at the vid company.

Notable fields in the response:

Field	Description
supplier	Subsection of the response with supplier fields.
relationship	Subsection of the response with fields regard the relationship confidence and date.
evidences	A list of evidence items that support the relationship.

A simple example

This example fetches suppliers for Amazon:

• with a confidence score of 0.8 or higher
• supported by evidence later than 1st January 2019.

Request to get a list of suppliers for a company.

curl -X 'GET' \
  'http://<api_url>/companies/amazoncominc-db72624a-c1a5-4936-9459-eaf3fe7c7565/suppliers/?confidence_score=0.8&date=2019-01-01' \
  -H 'accept: application/json'

Response

{
  "next": "http://localhost:8000/companies/amazoncominc-db72624a-c1a5-4936-9459-eaf3fe7c7565/suppliers/?confidence_score=0.8&date=2019-01-01&limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "supplier": {
        "vid": "ultimateearsinc-c3de8a43-2424-4b11-8e0f-8d0b358984ea",
        "name": "Ultimate Ears Inc",
        "company_legal_name": "Ultimate Ears Inc",
        "description": null,
        "domains": [
          "ultimateears.com"
        ],
        "country": "United States",
        "count_supplier_evidence": 5,
        "count_customer_evidence": 6,
        "count_customers": 3,
        "count_suppliers": 4
      },
      "relationship": {
        "confidence_score": 1,
        "latest_relationship_date": "2022-10-27T00:00:00Z",
        "relationship_type": "cluster_edge",
        "relationship_id": "ultimateears-amazon-supply",
        "edge_ids": [
          "ultimateearsinc-c3de8a43-2424-4b11-8e0f-8d0b358984ea-amazoncominc-db72624a-c1a5-4936-9459-eaf3fe7c7565-supply"
        ]
      },
      "evidences": {
        "evidence_types": [
          "text"
        ]
      }
    },
    ...
  ]
}