An Example

In this example we will generate a sub tier map for a single company, Boeing Co. using the Bulk Data API. Broadly, there are 3 steps:

1. Find the Versed Identifier for "Boeing Co." by searching the Versed database.
2. Start a tier view job with the identifier from (1) and store the run identifier.
3. Check the status of the job and when it's complete download the data.

Step 1 - Match to a Versed Identifier

The Request

Using the /v1/companies/ endpoint we find the match for Boeing Co.

curl --request GET \
     --url '<YOUR BASE URL HERE>/v1/companies/?name=Boeing%20Co.' \
     --header 'X-BLOBR-KEY: <YOUR KEY HERE>'

or via the API user interface:

The Response

The top result from the database has a high similarity to our query and relationships, so we will use this Versed Identifier (vid) boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e.

"search_similarity": 1,
      "vid": "boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e",
      "cid_id": "boeing",
      "name": "Boeing Co",
      "domains": [
        "boeing.com"
      ],
      "websites": [
        "https://www.boeing.com/",
        "http://www.boeing.com/"
      ],
      "company_legal_name": "Boeing Co",
      "description": "aerospace and defense manufacturer in the United States",
      "count_supplier_evidence": 2058,
      "count_customer_evidence": 3642,
      "count_customers": 374,
      "count_suppliers": 530,
      ...

Step 2 - Start the Tier View Process

We start the process of extracting the sub tier relationships using the /tierviewjob/ endpoint. This is a POST endpoint so we need to send a body like the following:

The Request

curl --request POST \
     --url '<YOU BASE URL HERE>/v1/tierviewjob/' \
     --header 'Content-Type: application/json' \
     --header 'X-BLOBR-KEY: <YOUR KEY HERE>' \
     --data '{
      "root_nodes": "boeingco-63be9d9f-baba-4a40-9124-ea494dadc48e",
      "num_tiers": "3",
      "direction": "supplier",
      "min_evid_date": "2019-01-01",
      "output_multiple_tables": "no"
    }'

or via the API user interface:

Field	Description
root_nodes	The Versed Identifier to create the map for.
num_tiers	The number of tiers to create. 1 tier is 1 level of suppliers, 2 tiers is another level and so on.
direction	"customer" or "supplier", where this defines if we want to find customers or suppliers of the root node
min_evid_date	The earliest date of evidence used to create the map. Earlier dates will use older pieces of evidence for relationships.
output_multiple_tables	"yes" or "no". If yes, 3 CSV files will be created, separating relationship, tier location and company information. If not, a single CSV will be returned with all of the data.

The Response

The API will return a run id, which can be used to find the status of the job and the result once finished.

{
  "run_id": 367899
}

Step 3 - Fetch the Data

The Request

To find the status of the process we poll the /v1/jobs/{run_id} with the run id returned from the step earlier.

The Response

Waiting State

Initially our platform will allocate resources to complete the workflow, returning a PENDING, waiting for cluster state. This could take 1 to 5 minutes.

{
  "run_id": "367899",
  "state": {
    "life_cycle_state": "PENDING",
    "state_message": "Waiting for cluster",
    "user_cancelled_or_timedout": false
  },
  "output": null
}

Running State

Once the cluster has started, the system will return a RUNNING state. This could take 5 to 10 minutes.

{
  "run_id": "367899",
  "state": {
    "life_cycle_state": "RUNNING",
    "state_message": "In run",
    "user_cancelled_or_timedout": false
  },
  "output": {}
}

Finished State

Once the job has finished, the system will return a SUCCESS state and in the output field, a signed url to download the dataset. This URL can be pasted into a browser to download the CSV or programmatically using curl. See here for field descriptions of the data set.

{
  "run_id": "367899",
  "state": {
    "life_cycle_state": "TERMINATED",
    "result_state": "SUCCESS",
    "state_message": "",
    "user_cancelled_or_timedout": false
  },
  "output": {
    "result": "{'tierview_file': 'https://storage.googleapis.com/staging-databricks-outputs-versed-ai/tierview/psm/tierview-20230721-102856.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=databricks-staging%40databricks-387607.iam.gserviceaccount.com%2F20230721%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20230721T103233Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&X-Goog-Signature=980376374b9ed491e14fb4070c9a71e4301077c10911a2b6ace741373ee25808b35f65fde0adcf43a822ed0a75c41cdb8fec2aa5f6a10ba56b96818914c45587d03b3b8edcbf0b858b0b01b4c3fd55aa4f709f8d794871dbcbd0b20f25d97f71f6aafa395daf36d4b61dba314e09fd53e65764d9217754e5c4beee63a03e8691d221cca6cd0c41bb62868c5b7c4202d37fd027afe5e13d572c65543f9661e0460834379735708e16460db08cef8ae3081d576d756c8b5005ec258a46f01826591dc5d3da731816ee6a71c25073b21d94d896a0cdb7948bdb36742d05613c1c8d6873b9051487f6feca493c96900c717ad0203519c0843f356cd2208844435198'}",
    "truncated": false
  }
}