Link

Assuming that you have read Authentication Quickstart, you may start linking your company data with S&P Global's Market Intelligence or CapitalIQ data.

Link REST APIs

The Link API supports the following endpoint for matching your company data:

• /api/ondemand/v0/companies/<knowledge_base>/<model_name>

This on-demand endpoint asks the user to provide a knowledge base and model name in the URI.

• knowledge_base is either "mi" or "capiq".
  • "mi" allows the user to link against the Market Intelligence dataset
  • "capiq" allows the user to link against the CapitalIQ dataset.
• model_name (at this time) must be "generic".

A JSON request body should be provided with the following format:

{
    "include_response_fields": Optional[List[str]] = [],
    "num_top_records": Optional[int] = 1,
    "records": [{
        "uid": str,
        "name": str,
        "aliases": Optional[List[str]] = [],
        "country_iso3": Optional[str] = None,
        "address": Optional[str] = None,
        "state": Optional[str] = None,
        "city": Optional[str] = None,
        "zipcode": Optional[str] = None,
        "year_founded": Optional[int] = None,
        "url": Optional[str] = None,
        "phone_number": Optional[str] = None,
    }] 
}

Sample usage

Request

The following example links companies to the CapitalIQ dataset with the "generic" model.

The URI indicates the knowledge base (capiq) and model name (generic):

https://link-streaming.kensho.com/api/ondemand/v0/companies/capiq/generic

The JSON body requests links for two companies, "S&P Global Inc." and "kensho". num_top_records indicates how many records to return for each company. include_response_fields indicates any knowledge base fields to return along with each linked record. Currently, only "knowledge_base_name" is supported which will return the name of the matched company as found in the knowledge base. For "S&P Global Inc.", all possible fields are provided, whereas for "kensho" only the required fields (name and uid) are provided.

{
    "records": [
        {
            "uid": "1",
            "name": "S&P Global Inc.",
            "aliases": ["S&P", "SPGI"],
            "country_iso3": "USA",
            "address": "55 Water Street",
            "state": "New York",
            "city": "New York",
            "zipcode": "10041",
            "year_founded": 1917,
            "url": "https://www.spglobal.com/",
            "phone_number": "718-123-4567"
        },
        {
            "uid": "2",
            "name": "kensho"
        }
    ],
    "num_top_records": 2,
    "include_response_fields": ["knowledge_base_name"],
}

Response

The output of the endpoint contains metadata that describes the entity type, knowledge base, model name and model version used for the request. The output for each linked record contains the knowledge base name, knowledge base uid and the associated link score. The results for each record are returned in descending order of the link_score field.

{
    "entity_type": "companies",
    "knowledge_base": "capiq",
    "model_name": "generic",
    "model_version": 10,
    "records": [
        {
            "links": [
                {
                    "knowledge_base_name": "S&P Global Inc.",
                    "knowledge_base_uid": "21719",
                    "link_score": 0.9975524835880594
                },
                {
                    "knowledge_base_name": "S&P Global Ratings Inc",
                    "knowledge_base_uid": "142188790",
                    "link_score": 0.7593954434416339
                }
            ],
            "num_links": 2,
            "uid": "1"
        },
        {
            "links": [
                {
                    "knowledge_base_name": "Kensho Technologies, Inc.",
                    "knowledge_base_uid": "251994106",
                    "link_score": 0.9933911614820168
                },
                {
                    "knowledge_base_name": "kensho",
                    "knowledge_base_uid": "605329218",
                    "link_score": 0.832991328482396
                }
            ],
            "num_links": 2,
            "uid": "2"
        }
    ]
}

The following is an example of how to interact with the API using Python:

import json
import requests
LINK_API_URL = 'https://link-streaming.kensho.com/api/ondemand/v0/companies/capiq/generic'
data = {
        "records": [
            {
                "uid": "1",
                "name": "S&P Global Inc.",
                "aliases": ["S&P", "SPGI"],
                "country_iso3": "USA",
                "address": "55 Water Street",
                "state": "New York",
                "city": "New York",
                "zipcode": "10041",
                "year_founded": 1917,
                "url": "https://www.spglobal.com/",
                "phone_number": "718-123-4567"
            },
            {
                "uid": "2",
                "name": "kensho"
            }
        ],
        "num_top_records": 2,
        "include_response_fields": ["knowledge_base_name"],
    }
response = requests.post(
    LINK_API_URL,
    data=json.dumps(data),
    headers={'Content-Type': 'application/json',
             'Authorization': 'Bearer <token obtained from login>'}
)
linked_results = response.json()