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.
To get the most from the API, we recommend briefly reading the FAQ to understand the concepts behind the data, especially company groups.
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.
The default search options only search for parent companies of the company groups created and any company not in a group. 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 group the company belongs to. |
A simple example
curl -X 'GET' 'http://<api_url>/companies/?name=boeing' -H 'accept: application/json'
{
"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 company group 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 (parents and subsidiaries)
/companies/{vid}/group_suppliers/
/companies/{vid}/group_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 company group.
Notable fields in the response:
| Field | Description |
|---|---|
count | The number of suppliers or customers attached to the company group. |
confidence_score | The confidence score our AI and algorithms have assigned to this relationship. |
cluster_edge_id | The unique identifer for the group relationship. |
edge_ids | A list of the edge ids for the parent and subsidiaries in the group. |
A simple example
This example fetches suppliers for Boeing, including any suppliers found within the Boeing group of subsidiaries given:
- a confidence score of 0.8 or higher
- supported by evidence later than 1st January 2019.
curl -X 'GET' \
'http://<api_url>/companies/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/group_suppliers/?confidence_score=0.8&date=2019-01-01' \
-H 'accept: application/json'
{
"count": 369,
"next": "http://<api_url>/companies/boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e/group_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/
These endpoints return relationships directly connected to the vid. We recommend using /{vid}/group_suppliers/ and /{vid}/group_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:
| Field | Description |
|---|---|
count | The number of suppliers or customers attached to the vid. |
confidence_score | The confidence score our AI and algorithms have assigned to this relationship. |
edge_id | The unique identifer for the relationship (also known as an edge). |
evidences | A 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.
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'
{
"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.
Group Profile Lookup
/groups/{cid}/
Use this endpoint to find the record for a company group, which includes the cid and the nominated_vid for a group. The nominated_vid is the company that we have chosen to represent the company group in our database.
Group Contents
/groups/{cid}/contents/
This endpoint will return the subsidiaries assigned to this company group.
Group Relationship (aka group edges) Profile Lookup
/group_edges/{cluster_edge_id}/
Use this endpoint to get information about a specific group relationship using the cluster_edge_id. Like edges the response includes the latest date found supporting the relationships 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 group.