Skip to main content
Version: Next

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.

/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:

FieldDescription
search_similarityIf a name is provided in the input, this returns the trigram similarity to the record.
count_suppliersThe number of suppliers in the database for the company.
count_customersThe number of customers in the database for the company.
cid_idThe 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:

FieldDescription
vidThe unique identifier for the company.
cid_idThe identifier of the cluster the company belongs to.
nameThe name of the company. Where possible this is the legal name.
domainsA list of domains associated with the company.
websitesA list of websites associated with the company.
company_legal_nameThe legal name of the company.
descriptionA description of the company.
count_supplier_evidenceThe number of evidences in the database for the supply relationships.
count_customer_evidenceThe number of evidences in the database for the customer relationships.
count_customersThe number of customers in the database for the company.
count_suppliersThe number of suppliers in the database for the company.
identifiersA list of identifiers associated with the company.
domiciled_countryISO3166 long form of the country the company is domiciled in.
incorporated_countryISO3166 long form of the country the company is incorporated in.
incorporation_dateDate and time of company incorporation.
ipo_dateDate and time of company incorporation.
is_activeWhether the company is active.
is_freight_forwarderWhether the company is a freight forwarder.
is_publicWhether the company is publicly listed.
hq_phone_numberPhone number of the headquarters.
addressesA list of addresses associated with the company.

Company Suppliers & Customers (parents and subsidiaries)

/companies/{vid}/cluster_suppliers/

/companies/{vid}/customer_customers/

Use these endpoints to get a list of a company's suppliers or customers, ordered by the confidence of the relationship taking into account relationships of both parent and subsidiary companies in the cluster.

Notable fields in the response:

FieldDescription
countThe number of suppliers or customers attached to the cluster.
confidence_scoreThe confidence score our AI and algorithms have assigned to this relationship.
cluster_edge_idThe unique identifer for the cluster relationship.
edge_idsA list of the edge ids for the parent and subsidiaries in the cluster.

A simple example

This example fetches suppliers for Boeing, including any suppliers found within the Boeing cluster of subsidiaries given:

  • 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 including any subsidiaries.
curl -X 'GET' \
'http://<api_url>/companies/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/cluster_suppliers/?confidence_score=0.8&date=2019-01-01' \
-H 'accept: application/json'
Response
{
"count": 369,
"next": "http://<api_url>/companies/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/cluster_suppliers/?confidence_score=0.8&date=2019-01-01&limit=10&offset=10",
"previous": null,
"results": [
{
"cluster_edge_id": "oracle-boeing-supply",
"from_parent_vid_id": "oraclecorp-27e324b2-6fb8-4161-90d3-167c8bc4c91d",
"from_cid_id": "oracle",
"to_parent_vid_id": "boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e",
"to_cid_id": "boeing",
"confidence_score": 1,
"edge_ids": [
"oraclecorp-27e324b2-6fb8-4161-90d3-167c8bc4c91d-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply"
]
},
{
"cluster_edge_id": "libertysteel-da09e5f9-30b5-4324-a831-86f0726d0fce-boeing-supply",
"from_parent_vid_id": "libertysteel-da09e5f9-30b5-4324-a831-86f0726d0fce",
"from_cid_id": null,
"to_parent_vid_id": "boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e",
"to_cid_id": "boeing",
"confidence_score": 1,
"edge_ids": [
"libertysteel-da09e5f9-30b5-4324-a831-86f0726d0fce-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply"
]
},
...
]
}

Company Suppliers & Customers

/companies/{vid}/suppliers/

/companies/{vid}/customers/

tip

These endpoints return relationships directly connected to the vid. We recommend using /{vid}/cluster_suppliers/ and /{vid}/cluster_customers/ to get a list of suppliers and customers to maximise the number of relationships returned.

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:

FieldDescription
countThe number of suppliers or customers attached to the vid.
confidence_scoreThe confidence score our AI and algorithms have assigned to this relationship.
edge_idThe unique identifer for the relationship (also known as an edge).
evidencesA list of evidence items that support the relationship.

A simple example

This example fetches suppliers for Boeing:

  • 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/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/suppliers/?confidence_score=0.8&date=2019-01-01' \
-H 'accept: application/json'
Response
{
"count": 317,
"next": "http://localhost:8000/companies/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/suppliers/?confidence_score=0.8&date=2019-01-01&limit=10&offset=10",
"previous": null,
"results": [
{
"edge_id": "flirsystems-7da1e111-2f91-45bf-8505-d68809172865-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply",
"confidence_score": 1,
"supplier": {...},
"evidences": [...]
},
{
"edge_id": "bridgestonecorp-56bf30a9-d172-4856-a86f-1b288105d662-boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e-supply",
"confidence_score": 1,
"supplier": {...},
"evidences": [...]
},
...
]
}

Relationship (aka edge) Profile Lookup

/edges/{edge_id}/

Use this endpoint to get information about a specific relationship using the edge_id. The response includes the latest date found supporting the relationship, the confidence score, and a list of evidence items that support the relationship.

Cluster Profile Lookup

/clusters/{cid}/

Use this endpoint to find the record for a cluster, which includes the cid and the nominated_vid for a cluster. The nominated_vid is the company that we have chosen to represent the cluster in our database.

Cluster Contents

/clusters/{cid}/contents/

This endpoint will return the subsidiaries assigned to this cluster.

Cluster Relationship (aka cluster edge) Profile Lookup

/cluster_edges/{cluster_edge_id}/

Use this endpoint to get information about a specific cluster relationship using the cluster_edge_id. Like edges the response includes the latest date found supporting the relationshipa and the confidence score for the relationship. The response also includes a list of the edge_ids for the relationships attached to the parent and subsidiaries in the cluster.