Yewno Concept Exposures API Documentation

Version 2.3


Change Log

API Reference

Yewno's Concept Exposure API is base on REST, returns JSON-encoded responses, and returns standard HTTP response codes.
  • The base url for the API is: https://ceapi.yewno.com/api/
  • All requests require an Authorization header set to the owner token supplied to you by sales.
  • All requests are processed in the background. Once complete the request's status will transition to complete and a zip file or csv is added to the request record.
  • Requested data will be retrievable for 5 days after the request was completed. After 5 days the data will have to be re-requested.
  • A user can only have 5 concurrent requests processing. All other requests will sit in Awaiting status.

Concept Search

Concept Search by Keyword
top

API to search for concepts by keyword. Returned is matching concepts and their corresponding metadata.

Operation HTTP Request Description
GET /api/concept?q=apple,google Searches Concepts by Keywords (comma delimited & Max 100)
GET /api/concept?q=apple,canada&categories=company,place Searches Concepts by Keyword & Category
Requirements:
  • Authorization Header set to your token
  • q [REQUIRED] Comma delimited list of keywords to search concepts
  • categories [OPTIONAL] Comma delimited list of categories to limit results by. Possible categories are company, person, place, other
Example Requests:

curl --location --request GET 'https://ceapi.yewno.com/api/concept?q=apple,canada&categories=company,place'
                --header 'Authorization: ___YOUR_AUTH_CODE___'

import requests
url = "https://ceapi.yewno.com/api/concept?q=apple,canada&categories=company,place"
headers = {'Authorization': '___YOUR_AUTH_CODE___'}
response = requests.request("GET", url, headers=headers)
print(response.json())
Response Details:
  • cId: Concept's ID
  • title: Concept's plain title
  • definition: Concept's definition
  • category: Concept's category [company, person, place, or other]
  • topics: Concept's topic titles, & subtopics (list of dictionaries)
Example Response:
{
    "status": 200,
    "message": "OK",
    "data": [
        {
            "cId": "930ccb849232d29423fd7e4c44d4a89d",
            "title": "Apple Inc.",
            "category": "company",
            "definition": "Apple Inc. is an American multinational technology company headquartered in Cupertino, California that designs, develops, and sells consumer electronics, computer software, and online services. The company's hardware products include the iPhone smartphone, the iPad tablet computer, the Mac personal computers, the iPod portable media player, the Apple Watch smartwatch, Apple",
            "topics": [
                {
                    "title": "Technology & Engineering",
                    "subtopics": [
                        {
                            "title": "Mobile & Wireless Communication"
                        },
                        {
                            "title": "Agricultural Engineering"
                        }
                    ]
                },
                {
                    "title": "Business & Economics",
                    "subtopics": [
                        {
                            "title": "Industries"
                        },
                        {
                            "title": "Economics"
                        },
                        {
                            "title": "Computer & Information Technology"
                        }
                    ]
                },
                {
                    "title": "Computers & Computer Science",
                    "subtopics": [
                        {
                            "title": "Information Systems"
                        },
                        {
                            "title": "Computer Science"
                        },
                        {
                            "title": "Desktop Applications"
                        }
                    ]
                }
            ]
        },
        {
            "cId": "c406fac5adce4abf7cd534369aa1ae3b",
            "title": "Apple Store",
            "category": "company",
            "definition": "Apple Store is a chain of retail stores owned and operated by Apple Inc. The stores sell Mac personal computers, iPhone smartphones, iPad tablet computers, iPod portable media players, Apple Watch smartwatches, Apple TV digital media players, software, and select third-party accessories. The first Apple Stores were originally opened as",
            "topics": [
                {
                    "title": "Business & Economics",
                    "subtopics": [
                        {
                            "title": "Sales & Selling"
                        },
                        {
                            "title": "Economics"
                        }
                    ]
                },
                {
                    "title": "Technology & Engineering",
                    "subtopics": [
                        {
                            "title": "Mobile & Wireless Communication"
                        },
                        {
                            "title": "Agricultural Engineering"
                        }
                    ]
                },
                {
                    "title": "Social Science",
                    "subtopics": [
                        {
                            "title": "Anthropology"
                        },
                        {
                            "title": "Fashion"
                        }
                    ]
                }
            ]
        },
        {
            "cId": "cd6a7b8768528485a0dbcd459185091e",
            "title": "Canada",
            "category": "place",
            "definition": "The instrumental version of the Canadian national anthem, “O Canada.” 

Canada, second largest country in the world in area (after Russia ), occupying roughly the northern two-fifths of the continent of North America . 

Despite Canada’s great size, it is one of the world’s most sparsely populated countries. This fact,",
            "topics": [
                {
                    "title": "Geography",
                    "subtopics": [
                        {
                            "title": "Canada"
                        }
                    ]
                },
                {
                    "title": "History",
                    "subtopics": [
                        {
                            "title": "Politics"
                        },
                        {
                            "title": "Cold War"
                        }
                    ]
                },
                {
                    "title": "Business & Economics",
                    "subtopics": [
                        {
                            "title": "International Economics"
                        },
                        {
                            "title": "Statistics"
                        }
                    ]
                },
                {
                    "title": "Social Science",
                    "subtopics": [
                        {
                            "title": "Indigenous Studies"
                        },
                        {
                            "title": "Emigration & Immigration"
                        }
                    ]
                }
            ]
        },
        {
            "cId": "57d3c3bc1ce69845c1a5d045ec989d1f",
            "title": "Canadian Pacific Railway",
            "category": "company",
            "definition": "The Canadian Pacific Railway (CPR), also known formerly as CP Rail (reporting mark CP) between 1968 and 1996, is a historic Canadian Class I railroad incorporated in 1881. The railroad is owned by Canadian Pacific Railway Limited, which began operations as legal owner in a corporate restructuring in 2001. Headquartered",
            "topics": [
                {
                    "title": "Transportation",
                    "subtopics": [
                        {
                            "title": "Railroads"
                        }
                    ]
                },
                {
                    "title": "Geography",
                    "subtopics": [
                        {
                            "title": "Canada"
                        }
                    ]
                },
                {
                    "title": "Business & Economics",
                    "subtopics": [
                        {
                            "title": "Accounting"
                        },
                        {
                            "title": "Service Industry"
                        },
                        {
                            "title": "Industries"
                        },
                        {
                            "title": "Food Industry"
                        }
                    ]
                }
            ]
        }
    ]
}
Concept Search by Concept IDs
top

API to search for concepts by ID. Returned is matching concepts and their corresponding metadata

Operation HTTP Request Description
GET /api/concept?cIds=476432a3e85a0aa21c23f5abd2975a89,8a85fe387e2c50917fb2e7b7087aebd0 Searches Concepts by Concept IDs
Requirements:
  • Authorization Header set to your token
  • cIds [REQUIRED] Comma delimited list of conceptIds to search across Limit 100
Example Requests:

curl --location --request GET 'https://ceapi.yewno.com/api/concept?cIds=476432a3e85a0aa21c23f5abd2975a89,8a85fe387e2c50917fb2e7b7087aebd0'
                --header 'Authorization: ___YOUR_AUTH_CODE___'

import requests
url = "https://ceapi.yewno.com/api/concept?cIds=930ccb849232d29423fd7e4c44d4a89d,8a85fe387e2c50917fb2e7b7087aebd0"
headers = {'Authorization': '___YOUR_AUTH_CODE___'}
response = requests.request("GET", url, headers=headers)
print(response.json())
Response Details:
  • cId: Concept's ID
  • title: Concept's plain title
  • definition: Concept's definition
  • category: Concept's category [company, person, place, or other]
  • topics: Concept's topic titles, & subtopics (list of dictionaries)
Example Response:
{
    "status": 200,
    "message": "OK",
    "data": [
        {
            "cId": "476432a3e85a0aa21c23f5abd2975a89",
            "title": "Apple",
            "category": "other",
            "definition": "Because of the apple’s fine qualities, it is sometimes called the king of fruits. The hardy apple flourishes over more parts of the Earth than any other fruit tree. Because the fruit keeps for months in cool storage, it was a dependable winter fruit supply before cold storage was developed. 

The glossy red or greenish-yellow fruit is juicy and crisp, with a spicy aroma. It is delicious to eat raw or cooked. Apple juice and cider are popular drinks. Apples also are commercially canned, prepared as jelly or apple butter, and frozen as juice. The apple contains minerals and a fair amount of vitamins; the carbohydrates are readily digested fruit sugars. About one sixth is solid material and the rest water. 

Although there are thousands of varieties of apples, relatively few are raised commercially.",
            "topics": [
                {
                    "title": "Technology & Engineering",
                    "subtopics": [
                        {
                            "title": "Agriculture"
                        },
                        {
                            "title": "Food Science"
                        }
                    ]
                },
                {
                    "title": "Earth Sciences",
                    "subtopics": [
                        {
                            "title": "Environmental Science"
                        },
                        {
                            "title": "Meteorology & Climatology"
                        }
                    ]
                }
            ]
        },
        {
            "cId": "8a85fe387e2c50917fb2e7b7087aebd0",
            "title": "5G",
            "category": "other",
            "definition": "5th generation mobile networks or 5th generation wireless systems, abbreviated 5G, are the proposed next telecommunications standards beyond the current 4G/IMT-Advanced standards. 5G planning aims at higher capacity than current 4G, allowing a higher density of mobile broadband users, and supporting device-to-device, ultra reliable, and massive machine communications. 5G research and development also aims at lower latency than 4G equipment and lower battery consumption, for better implementation of the Internet of things. There is currently no standard for 5G deployments. The Next Generation Mobile Networks Alliance defines the following requirements that a 5G standard should fulfill: Data rates of tens of megabits per second for tens of thousands of users Data rates of 100 megabits per second for metropolitan areas 1 Gb per second simultaneously to many workers on the same office floor Several hundreds of thousands of simultaneous connections for wireless sensors Spectral efficiency significantly enhanced compared to 4G Coverage improved Signalling efficiency enhanced Latency reduced significantly compared to LTE.",
            "topics": [
                {
                    "title": "Computers",
                    "subtopics": [
                        {
                            "title": "Networking"
                        },
                        {
                            "title": "Information Systems"
                        }
                    ]
                },
                {
                    "title": "Technology & Engineering",
                    "subtopics": [
                        {
                            "title": "Telecommunication"
                        },
                        {
                            "title": "Power Resources"
                        }
                    ]
                }
            ]
        }
    ]
}


Trending Concepts Request

New Trending Concept Request
top

Request for new Trending Concepts data to be processed. Returned will be a request ID to be tracked until the request is completed and then the file and corresponding trending concepts can be downloaded. This is currently only on the news data.

Operation HTTP Request Description
POST /api/request/trending New Trending Concept Request
Requirements:
  • Authorization Header set to your token
  • windows [REQUIRED] list: Rolling look back windows to search. Options any of the following 1d, 2d, 7d, 15d, 1m, 3m, 180d, 365d
  • dateStart [REQUIRED] string: Beginning of Search Window. Format (YYYY-MM-DD)
  • dateEnd [REQUIRED] string: End of Search Window. Format (YYYY-MM-DD)
  • source [OPTIONAL] Source items to query data from. Map of one or both of the following items (Max 100 Total Items):
    • isins: list of Company ISINs to filter by
    • concepts: list of Concept IDs to filter by
  • filters [OPTIONAL] Map with the following details to help filter your results:
    • threshold: [OPTIONAL] Filter Results by Threshold. Map with the following data: { "factor": options are change1d,change2d,change7d,change15d,change1m,change3m,change180d,change365d,count1d,count2d,count7d,count15d,count1m,count3m,count180d,count365d "op": operation options are gt (greater than), gte (greater than equal to), lt (less than), lte (less than equal to), "value": float value to use as your threshold }
    • categories: [OPTIONAL] List of concept categories to include in file. Options [company, person, place, other]
  • sort [OPTIONAL] map with the following data points:
    • sortBy: Factor to sort by. Options are change1d, change2d, change7d, change15d, change1m, change3m, change180d, change365d, count1d, count2d, count7d, count15d, count1m, count3m, count180d, count365d
    • sortAsc: Boolean. True to sort ascending, False to sort descending.
  • limit [OPTIONAL] integer: total number of records returned per request per day
Example Requests:

curl --location --request POST 'https://ceapi.yewno.com/api/request/trending'
--header 'Authorization: ___YOUR_AUTH_CODE___'
--header 'Content-Type: application/json'
--data-raw '{
    "dateStart": "2021-05-01",
    "dateEnd": "2021-06-01",
    "windows": ["2d","15d","1m"],
    "filters": {
        "categories": ["company", "other"],
        "threshold": {
            "factor": "change15d",
            "op": "gt",
            "value": 0.001
        }
    },
    "sort": {
        "sortAsc": false,
        "sortBy": "change1m"
    },
    "limit": 100
}'

import requests
import json
url = "https://ceapi.yewno.com/api/request/trending"
payload = {'dateEnd': '2021-06-01', 'dateStart': '2021-05-01', 'windows': ['2d', '15d', '1m'], 'filters':
    {'categories': ['company', 'other'], 'threshold': {'factor': 'change15d', 'op': 'gt', 'value': 0.001}},
    'sort': {'sortAsc': False, 'sortBy': 'change1m'}, 'limit': 100}


headers = {
  'Authorization': '___YOUR_AUTH_CODE___',
  'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())
Response Details:
  • requestID: New Request ID
  • msg: Success Message
Example Response:
{
        "status": 200,
        "message": "trending request received and processing",
        "data": {
            "requestId": "cf2f58fe-d8cd-4de6-be43-a30a270b7c27"
        }
    }
Resulting Output File:

Once your request starts processing file names will begin to be populated into the filenames list in your response. Those files will either be in CSV or ZIP (containing CSVs) format, depending on how large the data is. The CSVs will have the following headers which can be specified in the "Fields" attribute specified above.

  • ReferenceDate: Reference date of trending concepts
  • ConceptID: ID of the exposed concept
  • Concept: Title of the exposed concept
  • ConceptCategory: Category of the exposed concept
  • ConceptIsin: ISIN of the exposed concept
  • Count1d: [If 1d window requested]: Total count of mentions for concept within window
  • Count2d: [If 2d window requested]: Total count of mentions for concept within window
  • Count7d: [If 7d window requested]: Total count of mentions for concept within window
  • Count15d: [If 15d window requested]: Total count of mentions for concept within window
  • Count1m: [If 1m window requested]: Total count of mentions for concept within window
  • Count3m: [If 3m window requested]: Total count of mentions for concept within window
  • Count180d: [If 180d window requested]: Total count of mentions for concept within window
  • Count365d: [If 365d window requested]: Total count of mentions for concept within window
  • Change1d: [If 1d window requested]: Total change percent of mentions for concept within window compared to window from previous day
  • Change2d: [If 2d window requested]: Total change percent of mentions for concept within window compared to window from previous day
  • Change7d: [If 7d window requested]: Total change percent of mentions for concept within window compared to window from previous day
  • Change15d: [If 15d window requested]: Total change percent of mentions for concept within window compared to window from previous day
  • Change1m: [If 1m window requested]: Total change percent of mentions for concept within window compared to window from previous day
  • Change3m: [If 3m window requested]: Total change percent of mentions for concept within window compared to window from previous day
  • Change180d: [If 180d window requested]: Total change percent of mentions for concept within window compared to window from previous day
  • Change365d: [If 365d window requested]: Total change percent of mentions for concept within window compared to window from previous day
Retrieve Trending Concept Requests
top

API to Retrieve all trending concept requests or a specific request by ID

Operation HTTP Request Description
GET /api/request/trending All Trending Concept Requests (with limited payload returned)
GET /api/request/trending/<request_id> Trending Concept Request by ID
Requirements:
  • Authorization Header set to your token
  • id Required for the request by ID query
Example Requests:

curl --location --request GET 'https://ceapi.yewno.com/api/request/trending/cf2f58fe-d8cd-4de6-be43-a30a270b7c27'
--header 'Authorization: ___YOUR_AUTH_CODE___

import requests
url = "https://ceapi.yewno.com/api/request/trending/cf2f58fe-d8cd-4de6-be43-a30a270b7c27"
headers = {'Authorization': '___YOUR_AUTH_CODE___'}
response = requests.get(url, headers=headers)
print(response.json())
Response Details:
  • id: Request ID
  • status: Status of request. Options are awaiting, processing, complete
  • fileNames: List of file names by url which can be downloaded
  • fulfilledAt: Time at which the request was fulfilled
  • createdAt: Time at Which the request was created
  • Above are returned with request without ID. Below are returned with query by ID.
  • dateStart: Start date requested
  • dateEnd: End date requested
  • windows: Windows requested
  • source: Sources requested ISINs and/or concepts
  • filters: Filters requested
  • limit: Any limit requested
  • sort: Sort settings requested
  • notes: Any notes regarding the trending request retrieval
  • errors: Any errors that occurred during the trending request retrieval
  • percentComplete: Percentage of completion
Example Response:
{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "cf2f58fe-d8cd-4de6-be43-a30a270b7c27",
        "status": "complete",
        "dateStart": "2021-05-01",
        "dateEnd": "2021-06-01",
        "windows": [
            "2d",
            "15d",
            "1m"
        ],
        "filters": {
            "categories": [
                "company",
                "other"
            ],
            "threshold": {
                "factor": "change15d",
                "op": "gt",
                "value": 0.001
            }
        },
        "sort": {
            "sortBy": "change1m",
            "sortAsc": false
        },
        "limit": 100,
        "fields": null,
        "notes": [],
        "errors": [],
        "percentComplete": 100.0,
        "fileNames": [
            "https://ceapi.yewno.io/dev/CEHistory/trending/6e9bfa5d-0c6f-4543-a7f6-bf3bb2ed7737.cf2f58fe-d8cd-4de6-be43-a30a270b7c27_part_0.csv"
        ],
        "fulfilledAt": "2021-06-03T18:07:01.819844",
        "createdAt": "2021-06-03T18:05:30.248639"
    }
}


Score Request

New Score Request
top

Request for new Score data to be processed. Returned will be a request ID to be tracked until the request is completed and then the file and corresponding scores can be downloaded. Expected Result/Computation Times:
1 year of News Data for one asset
365d Window: 4 minutes
180d Window: 6 minutes
15d Window: 9 minutes
2d Window 6 minutes

Operation HTTP Request Description
POST /api/request/scores New Score Request
Requirements:
  • Authorization Header set to your token
  • sourceType [REQUIRED] string: Source Type. Options are news, patents, officialFilings, transcripts, clinicalTrials
  • window [REQUIRED] string: Lookback Window to Search. Options are 2d, 15d, 180d, 365d
  • dateStart [REQUIRED] string: Beginning of Search Window. Format (YYYY-MM-DD)
  • dateEnd [REQUIRED] string: End of Search Window. Format (YYYY-MM-DD)
  • source [REQUIRED] Source items to query data from. Map of one or both of the following items (Max 100 Total Items):
    • isins: list of Company ISINs to filter by
    • concepts: list of Concept IDs to filter by
  • destination [OPTIONAL] Destination items to query data to. This will limit results to specifically the items in your source to your destination. Map of one or both of the following items:
    • isins: list of Company ISINs to filter by
    • concepts: list of Concept IDs to filter by
  • expandIsins [OPTIONAL] Boolean to expand every available ISIN for a company. Lines for a specific company will be duplicated for each ISIN that company has (default: False)
  • expandParents [OPTIONAL] Boolean to expand to parent ISIN for a company, whenever it’s different from the subsidiary. Lines for a specific parent companies will be duplicated for each ISIN that company has (default: False)
  • filters [OPTIONAL] Map with the following details to help filter your results:
    • threshold: [OPTIONAL] Filter Results by Threshold. Map with the following data: { "factor": options are aggregate, similarity, centrality, contribution, pureplay, "op": operation options are gt (greater than), gte (greater than equal to), lt (less than), lte (less than equal to), "value": float value to use as your threshold }
    • categories: [OPTIONAL] List of concept categories to include in file. Options [company, person, place, other]
    • entitiesOnly: [OPTIONAL] Boolean. Results file will be composed of only exposed publicly traded companies (default: False)
    • conceptsOnly: [OPTIONAL] Boolean. Results file will be composed of only exposed non-publicly traded company concepts (default: False)
  • sort [OPTIONAL] map with the following data points:
    • sortBy: Factor to sort by. Options are aggregate, similarity, centrality, contribution, pureplay.
    • sortAsc: Boolean. True to sort ascending, False to sort descending.
  • limit [OPTIONAL] integer: total number of records returned per request type (ISIN/concept) per day
  • fields [OPTIONAL] list of fields to be returned in csv. See below for options here
Example Requests:

curl --location --request POST 'https://ceapi.yewno.com/api/request/scores'
--header 'Authorization: ___YOUR_AUTH_CODE___'
--header 'Content-Type: application/json'
--data-raw '{
    "sourceType": "news",
    "window": "15d",
    "dateStart": "2020-01-01",
    "dateEnd": "2020-06-30",
    "source": {
        "isins": [
            "US0378331005",
            "US0231351067",
            "US88160R1014"
        ],
        "concepts": [
            "d018b082e8a372d9b860417e823c6451",
            "0e85749a6f40d4614b87411e141fe810",
            "af55336221b72bee24d6c136a4a459ed"
        ]
    },
    "destination": {
        "isins": [
            "US0378331005",
            "US5949181045"
        ],
        "concepts": []
    },
    "expandIsins": true,
    "expandParents": true,
    "sort": {
        "sortAsc": false,
        "sortBy": "aggregate"
    },
    "filters": {
        "entitiesOnly": true,
        "conceptsOnly": false,
        "categories": [
            "company",
            "other"
        ],
        "threshold": {
            "factor": "aggregate",
            "op": "gt",
            "value": 0.001
        }
    },
    "limit": 100,
    "fields": [
        "ReferenceDate",
        "RequestedConceptID",
        "RequestedConcept",
        "RequestedIsin",
        "ConceptID",
        "Concept",
        "ConceptIsin",
        "Aggregate",
        "Similarity",
        "Centrality",
        "Contribution",
        "Pureplay"
    ]
}'

import requests
import json
url = "https://ceapi.yewno.com/api/request/scores"
payload = {'sourceType': 'news', 'window': '15d', 'dateStart': '2020-01-01', 'dateEnd': '2020-06-30', 'source':
    {'isins': ['US0378331005', 'US0231351067', 'US88160R1014'], 'concepts': ['d018b082e8a372d9b860417e823c6451',
    '0e85749a6f40d4614b87411e141fe810', 'af55336221b72bee24d6c136a4a459ed']}, 'destination': {'isins':
    ['US0378331005', 'US5949181045'], 'concepts': []}, 'expandIsins': True, 'expandParents': True, 'sort':
    {'sortAsc': False, 'sortBy': 'aggregate'}, 'filters': {'entitiesOnly': True, 'conceptsOnly': False, 'categories':
    ['company', 'other'], 'threshold': {'factor': 'aggregate', 'op': 'gt', 'value': 0.001}}, 'limit': 100, 'fields':
    ['ReferenceDate', 'RequestedConceptID', 'RequestedConcept', 'RequestedIsin', 'ConceptID', 'Concept', 'ConceptIsin',
    'Aggregate', 'Similarity', 'Centrality', 'Contribution', 'Pureplay']}

headers = {
  'Authorization': '___YOUR_AUTH_CODE___',
  'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=json.dumps(payload))
print(response.json())
Response Details:
  • requestID: New Request ID
  • msg: Success Message
Example Response:
{
      "status": 200,
      "message": "score request received and processing",
      "data": {
        "requestId": "2d9dbc79-2f54-4e0f-9384-1d1bef3b1da8"
      }
    }
Resulting Output File:

Once your request starts processing file names will begin to be populated into the filenames list in your response. Those files will either be in CSV or ZIP (containing CSVs) format, depending on how large the data is. The CSVs will have the following headers which can be specified in the "Fields" attribute specified above.

  • SourceType: Source type requested
  • ReferenceDate: Reference date of score
  • Window: Window requested
  • RequestedConceptID: ID of the concept requested
  • RequestedConcept: Title of the concept requested
  • RequestedIsin: ISIN of the concept requested
  • ConceptID: ID of the exposed concept
  • Concept: Title of the exposed concept
  • ConceptCategory: Category of the exposed concept
  • ConceptIsin: ISIN of the exposed concept
  • ConceptParentEntityName: Parent entity name of the exposed concept
  • ConceptParentEntityCID: Parent's concept name of the exposed concept
  • ConceptParentEntityIsin: Parent's ISIN of the exposed concept
  • Aggregate: Aggregated is a weighted linear combination of the previous scores (Contribution, Pureplay, Similarity and Centrality).
  • Similarity: Similarity is based on how close the Source and Destination concepts are to each other in the graph embeddings space, taking into account the network connecting all concepts.
  • Centrality: Centrality measures how central a concept is in the network of all concepts related to the Source concept, it takes into account indirect connections as well.
  • Contribution: Contribution is a measure of how much the destination concept was co-mentioned with the source concept in the news, or published documents relative to all the mentions of the concept source. The Contribution ratio aims to measure the contribution of the destination concept to the source concept.
  • Pureplay: Pureplay is a measure of the percentage of co-mentions between the destination concept and the source concept relative to all mentions of the destination concept. The Pureplay ratio aims to measure the concentration of the destination concept in the source concept.
Retrieve Score Requests
top

API to Retrieve all score requests or a specific request by ID

Operation HTTP Request Description
GET /api/request/scores All Score Requests (with limited payload returned)
GET /api/request/score/<request_id> Score Request by ID
Requirements:
  • Authorization Header set to your token
  • id Required for the request by ID query
Example Requests:

curl --location --request GET 'https://ceapi.yewno.com/api/request/score/d78d59ec-acd1-4fc1-bf8b-bdd0e0e962f8'
--header 'Authorization: ___YOUR_AUTH_CODE___

import requests
url = "https://ceapi.yewno.com/api/request/score/d78d59ec-acd1-4fc1-bf8b-bdd0e0e962f8"
headers = {'Authorization': '___YOUR_AUTH_CODE___'}
response = requests.request("GET", url, headers=headers)
print(response.json())
Response Details:
  • id: Request ID
  • status: Status of request. Options are awaiting, processing, complete
  • fileNames: List of filenames by url which can be downloaded
  • fulfilledAt: Time at which the request was fulfilled
  • createdAt: Time at Which the request was created
  • Above are returned with request without ID. Below are returned with query by ID.
  • sourceType: Source type requested
  • dateStart: Start date requested
  • dateEnd: End date requested
  • window: Window requested
  • source: Sources requested ISINs and/or concepts
  • destination: Destinations requested ISINs and/or concepts
  • expandIsins: Boolean flag requested
  • expandParents: Boolean flag requested
  • filters: Filters requested
  • limit: Any limit requested
  • sort: Sort settings requested
  • notes: Any notes regarding the score retrieval
  • errors: Any errors that occurred during the score retrieval
Example Response:
{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "0ec7c0c0-a5a2-469f-a3d8-b46cc9141ffb",
        "status": "awaiting",
        "sourceType": "news",
        "window": "15d",
        "dateStart": "2020-01-01",
        "dateEnd": "2020-06-30",
        "source": {
            "isins": ["US0231351067", "US0378331005", "US88160R1014"],
            "concepts": ["0e85749a6f40d4614b87411e141fe810", "af55336221b72bee24d6c136a4a459ed", "d018b082e8a372d9b860417e823c6451"]
        },
        "destination": {
            "isins": ["US0378331005", "US5949181045"],
            "concepts": []
        },
        "expandIsins": true,
        "expandParents": true,
        "filters": {
            "entitiesOnly": true,
            "conceptsOnly": false,
            "categories": ["company", "other"],
            "threshold": {
                "factor": "aggregate",
                "op": "gt",
                "value": 0.001
            }
        },
        "sort": {
            "sortBy": "aggregate",
            "sortAsc": false
        }
        "limit": 100,
        "fields": ["ReferenceDate", "RequestedConceptID", "RequestedConcept", "RequestedIsin", "ConceptID", "Concept", "ConceptIsin", "Aggregate", "Similarity", "Centrality", "Contribution", "Pureplay"],
        "notes": [],
        "errors": [],
        "percentComplete": 100.0,
        "fileNames": ["https://ceapi.yewno.io/stage/CEHistory/scores/e5c3bf12-537e-4d12-8707-bf780e77f6c5.2690faff-e29f-408x-b98c-513be07643b5_0.zip"],
        "fulfilledAt": "2021-01-21T18:22:37.593852",
        "createdAt": "2021-01-21T17:21:37.322503"
    }
}


Sentiment Request

New Sentiment Request
top

Request for new Sentiment data to be processed. Returned will be a request ID to be tracked until the request is completed and then the file and corresponding sentiment data can be downloaded. Sentiment is currently only available for 2 day window and on the news data.

Operation HTTP Request Description
POST /api/request/sentiment New Sentiment Request
Requirements:
  • Authorization Header set to your token
  • dateStart [REQUIRED] string: Beginning of Search Window. Format (YYYY-MM-DD)
  • dateEnd [REQUIRED] string: End of Search Window. Format (YYYY-MM-DD)
  • source [REQUIRED] Source items to query data from. Map of one or both of the following items (Max 100 Total Items):
    • isins: list of Company ISINs to filter by
    • concepts: list of Concept IDs to filter by
  • destination [OPTIONAL] Destination items to query data to. This will limit results to specifically the items in your source to your destination. Map of one or both of the following items:
    • isins: list of Company ISINs to filter by
    • concepts: list of Concept IDs to filter by
  • expandIsins [OPTIONAL] Boolean to expand every available ISIN for a company. Lines for a specific company will be duplicated for each ISIN that company has (default: False)
  • expandParents [OPTIONAL] Boolean to expand to parent ISIN for a company, whenever it’s different from the subsidiary. Lines for a specific parent companies will be duplicated for each ISIN that company has (default: False)
  • filters [OPTIONAL] Map with the following details to help filter your results:
    • threshold: [OPTIONAL] Filter Results by Threshold. Map with the following data: { "factor": option is sentiment, "op": operation options are gt (greater than), gte (greater than equal to), lt (less than), lte (less than equal to) "value": float value to use as your threshold }
    • categories: [OPTIONAL] List of concept categories to include in file. Options [company, person, place, other]
    • entitiesOnly: [OPTIONAL] Boolean. Results file will be composed of only exposed publicly traded companies (default: False)
    • conceptsOnly: [OPTIONAL] Boolean. Results file will be composed of only exposed non-publicly traded company concepts (default: False)
  • sort [OPTIONAL] map with the following data points:
    • sortBy: Factor to sort by Option is sentiment
    • sortAsc: Boolean. True to sort ascending, False to sort descending.
  • limit [OPTIONAL] integer: total number of records returned per request type (ISIN/concept) per day
  • fields [OPTIONAL] list of fields to be returned in csv. See below for options here
Example Requests:

curl --location --request POST 'https://ceapi.yewno.com/api/request/sentiment'
--header 'Authorization: ___YOUR_AUTH_CODE___'
--header 'Content-Type: application/json'
--data-raw '{
    "dateStart": "2020-06-01",
    "dateEnd": "2020-12-30",
    "source": {
        "isins": [],
        "concepts": [
            "0a2e23a3050e7dd612332c60dee7948a",
            "71d7ed755bdd77ff52e7f8e92d2a1264",
            "31bc1b17f9808c0c47226bf731833f8f"
        ]
    },
    "destination": {
        "isins": [
            "US88160R1014",
            "US62914V1061"
        ],
        "concepts": []
    },
    "expandIsins": true,
    "expandParents": true,
    "sort": {
        "sortAsc": false,
        "sortBy": "sentiment"
    },
    "filters": {
        "entitiesOnly": true,
        "conceptsOnly": false,
        "categories": [],
        "threshold": {
            "factor": "sentiment",
            "op": "gte",
            "value": 0.075
        }
    },
    "limit": 100,
    "fields": [
        "ReferenceDate",
        "RequestedConceptID",
        "RequestedConcept",
        "RequestedIsin",
        "ConceptID",
        "Concept",
        "ConceptIsin",
        "Sentiment"
    ]
}'

import requests
import json
url = "https://ceapi.yewno.com/api/request/sentiment"
payload = {'dateStart': '2020-06-01', 'dateEnd': '2020-12-30', 'source': {'isins': [], 'concepts':
    ['0a2e23a3050e7dd612332c60dee7948a', '71d7ed755bdd77ff52e7f8e92d2a1264', '31bc1b17f9808c0c47226bf731833f8f']},
    'destination': {'isins': ['US88160R1014', 'US62914V1061'], 'concepts': []}, 'expandIsins': True,
    'expandParents': True, 'sort': {'sortAsc': False, 'sortBy': 'sentiment'}, 'filters': {'entitiesOnly': True,
    'conceptsOnly': False, 'categories': [], 'threshold': {'factor': 'sentiment', 'op': 'gte', 'value': 0.075}},
    'limit': 100, 'fields': ['ReferenceDate', 'RequestedConceptID', 'RequestedConcept', 'RequestedIsin', 'ConceptID',
    'Concept', 'ConceptIsin', 'Sentiment']}

headers = {
  'Authorization': '___YOUR_AUTH_CODE___',
  'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=json.dumps(payload))
print(response.json())
Response Details:
  • requestID: New Request ID
  • msg: Success Message
Example Response:
{
    "status": 200,
    "message": "sentiment request received and processing",
    "data": {
        "requestId": "6ebeeb73-86d0-47be-b7cb-489de307c89d"
    }
}
Resulting Output File:

Once your request starts processing file names will begin to be populated into the filenames list in your response. Those files will either be in CSV or ZIP (containing CSVs) format, depending on how large the data is. The CSVs will have the following headers which can be specified in the "Fields" attribute specified above.

  • ReferenceDate: Reference date of sentiment
  • RequestedConceptID: ID of the concept requested
  • RequestedConcept: Title of the concept requested
  • RequestedIsin: ISIN of the concept requested
  • ConceptID: ID of the exposed concept
  • Concept: Title of the exposed concept
  • ConceptCategory: Category of the exposed concept
  • ConceptIsin: ISIN of the exposed concept
  • ConceptParentEntityName: Parent entity name of the exposed concept
  • ConceptParentEntityCID: Parent's concept name of the exposed concept
  • ConceptParentEntityIsin: Parent's ISIN of the exposed concept
  • Sentiment: Concept-to-concept sentiment score measuring the polarity of how directly and indirectly connected concepts impact each other
Retrieve Sentiment Requests
top

API to Retrieve all sentiment requests or a specific request by ID

Operation HTTP Request Description
GET /api/request/sentiment All Sentiment Requests (with limited payload returned)
GET /api/request/sentiment/<request_id> Sentiment Request by ID
Requirements:
  • Authorization Header set to your token
  • id Required for the request by ID query
Example Requests:

curl --location --request GET 'https://ceapi.yewno.com/api/request/sentiment/6ebeeb73-86d0-47be-b7cb-489de307c89d'
--header 'Authorization: ___YOUR_AUTH_CODE___

import requests
url = "https://ceapi.yewno.com/api/request/sentiment/6ebeeb73-86d0-47be-b7cb-489de307c89d"
headers = {'Authorization': '___YOUR_AUTH_CODE___'}
response = requests.request("GET", url, headers=headers)
print(response.json())
Response Details:
  • id: Request ID
  • status: Status of request. Options are awaiting, processing, complete
  • fileNames: List of filenames by url which can be downloaded
  • fulfilledAt: Time at which the request was fulfilled
  • createdAt: Time at which the request was created
  • Above are returned with request without ID. Below are returned with query by ID.
  • dateStart: Start date requested
  • dateEnd: End date requested
  • source: Sources requested ISINs and/or concepts
  • destination: Destinations requested ISINs and/or concepts
  • expandIsins: Boolean flag requested
  • expandParents: Boolean flag requested
  • filters: Filters requested
  • limit: Any limit requested
  • sort: Sort settings requested
  • notes: Any notes regarding the sentiment retrieval
  • errors: Any errors that occurred during the sentiment retrieval
Example Response:
{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "485db928-2c80-4f0a-a326-6bfa7239669f",
        "status": "complete",
        "dateStart": "2020-01-01",
        "dateEnd": "2020-06-30",
        "source": {
            "isins": [],
            "concepts": ["0a2e23a3050e7dd612332c60dee7948a", "31bc1b17f9808c0c47226bf731833f8f", "71d7ed755bdd77ff52e7f8e92d2a1264"]
        },
        "destination": {
            "isins": ["US62914V1061", "US88160R1014"],
            "concepts": []
        },
        "expandIsins": true,
        "expandParents": true,
        "filters": {
            "entitiesOnly": true,
            "conceptsOnly": false,
            "categories": [],
            "threshold": {
                "factor": "sentiment",
                "op": "gte",
                "value": 0.75
            }
        },
        "sort": {
            "sortBy": "sentiment",
            "sortAsc": false
        },
        "limit": 100,
        "fields": ["ReferenceDate", "RequestedConceptID", "RequestedConcept", "RequestedIsin", "ConceptID", "Concept", "ConceptCategory", "ConceptIsin", "Sentiment"],
        "notes": [],
        "errors": [],
        "percentComplete": 100.0,
        "fileNames": ["https://ceapi.yewno.io/stage/CEHistory/scores/e5c3bf12-537e-4d12-8707-bf780e77f6c5.2690faff-e29f-408a-b98c-513be07943b5_0.zip"],
        "fulfilledAt": "2021-01-21T19:18:04.193849",
        "createdAt": "2021-01-21T17:28:07.957451"
    }
}


Metadata Request

New Metadata Request
top

Request for new Metadata to be processed. Returned will be a request ID to be tracked until the request is completed and then the file and corresponding metadata data can be downloaded.

Operation HTTP Request Description
POST /api/request/metadata New Metadata Request
Requirements:
  • Authorization Header set to your token
  • sourceType [REQUIRED] string: Source Type. Options are news, patents, officialFilings, transcripts, clinicalTrials
  • dateStart [REQUIRED] string: Beginning of Search Window. Format (YYYY-MM-DD)
  • dateEnd [REQUIRED] string: End of Search Window. Format (YYYY-MM-DD)
  • source [REQUIRED] Source items to query data from. Map of one or both of the following items (Max 100 Total Items):
    • isins: list of Company ISINs to filter by
    • concepts: list of Concept IDs to filter by
  • destination [OPTIONAL] Destination items to query data to. This will limit results to specifically the items in your source to your destination. Map of one or both of the following items:
    • isins: list of Company ISINs to filter by
    • concepts: list of Concept IDs to filter by
  • expandIsins [OPTIONAL] Boolean to expand every available ISIN for a company. Lines for a specific company will be duplicated for each ISIN that company has (default: False)
  • expandParents [OPTIONAL] Boolean to expand to parent ISIN for a company, whenever it’s different from the subsidiary. Lines for a specific parent companies will be duplicated for each ISIN that company has (default: False)
  • expandSnippetScore [OPTIONAL] Boolean to expand every snippet and it's correlating score within the article(default: False)
  • filters [OPTIONAL] Map with the following details to help filter your results:
    • threshold: [OPTIONAL] Filter Results by Threshold. Map with the following data: { "factor": option is score, "op": operation options are gt (greater than), gte (greater than equal to), lt (less than), lte (less than equal to) "value": float value to use as your threshold }
    • categories: [OPTIONAL] List of concept categories to include in file. Options [company, person, place, other]
    • entitiesOnly: [OPTIONAL] Boolean. Results file will be composed of only exposed publicly traded companies (default: False)
    • conceptsOnly: [OPTIONAL] Boolean. Results file will be composed of only exposed non-publicly traded company concepts (default: False)
  • sort [OPTIONAL] map with the following data points:
    • sortBy: Factor to sort by. Option is score.
    • sortAsc: Boolean. True to sort ascending, False to sort descending.
  • limit [OPTIONAL] integer: total number of records returned per request type (ISIN/concept) per day
  • fields [OPTIONAL] list of fields to be returned in csv. See below for options here
Example Requests:

curl --location --request POST 'https://ceapi.yewno.com/api/request/metadata'
--header 'Authorization: ___YOUR_AUTH_CODE___'
--header 'Content-Type: application/json'
--data-raw '{
    "sourceType": "news",
    "dateStart": "2020-01-01",
    "dateEnd": "2020-12-31",
    "source": {
        "isins": [
            "US0378331005",
            "US0231351067",
            "US88160R1014"
        ],
        "concepts": [
            "d018b082e8a372d9b860417e823c6451",
            "0e85749a6f40d4614b87411e141fe810",
            "af55336221b72bee24d6c136a4a459ed"
        ]
    },
    "destination": {
        "isins": [
            "US0378331005",
            "US5949181045"
        ],
        "concepts": []
    },
    "expandIsins": true,
    "expandParents": true,
    "expandSnippetScore": false,
    "sort": {
        "sortAsc": false,
        "sortBy": "score"
    },
    "filters": {
        "entitiesOnly": true,
        "conceptsOnly": false,
        "categories": [],
        "threshold": {
            "factor": "score",
            "op": "gte",
            "value": 0.00
        }
    },
    "limit": 100,
    "fields": []
}'

import requests
import json
url = "https://ceapi.yewno.com/api/request/metadata"
payload = {'sourceType': 'news', 'dateStart': '2020-01-01', 'dateEnd': '2020-12-31', 'source': {
    'isins': ['US0378331005', 'US0231351067', 'US88160R1014'], 'concepts': ['d018b082e8a372d9b860417e823c6451',
    '0e85749a6f40d4614b87411e141fe810', 'af55336221b72bee24d6c136a4a459ed']}, 'destination': {'isins':
    ['US0378331005', 'US5949181045'], 'concepts': []}, 'expandIsins': True, 'expandParents': True,
    'expandSnippetScore': False, 'sort': {'sortAsc': False, 'sortBy': 'score'}, 'filters': {'entitiesOnly': True,
    'conceptsOnly': False, 'categories': [], 'threshold': {'factor': 'score', 'op': 'gte', 'value': 0.0}},
    'limit': 100, 'fields': []}

headers = {
  'Authorization': '___YOUR_AUTH_CODE___',
  'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=json.dumps(payload))
print(response.json())
Response Details:
  • requestID: New Request ID
  • msg: Success Message
Example Response:
{
    "status": 200,
    "message": "metadata request received and processing",
    "data": {
        "requestId": "971a4817-0149-43e1-bf52-04cc5a36a6c0"
    }
}
Resulting Output File:

Once your request starts processing file names will begin to be populated into the filenames list in your response. Those files will either be in CSV or ZIP (containing CSVs) format, depending on how large the data is. The CSVs will have the following headers which can be specified in the "Fields" attribute specified above.

  • ArticleID: ID of the article or document
  • Title: Title of the article or document
  • PublishedAt: Date of the publication
  • URL: URL of the document or article if applicable
  • RequestedConceptID: ID of the concept requested
  • RequestedConcept: Title of the concept requested
  • RequestedIsin: ISIN of the concept requested
  • ConceptID: ID of the exposed concept
  • Concept: Title of the exposed concept
  • ConceptCategory: Category of the exposed concept
  • ConceptIsin: ISIN of the exposed concept
  • ConceptParentEntityName: Parent entity name of the exposed concept
  • ConceptParentEntityCID: Parent's concept name of the exposed concept
  • ConceptParentEntityIsin: Parent's ISIN of the exposed concept
  • Score: Score of the snippet
  • Snippet: Actual text of the extracted snippet
  • SnippetID: ID of the snippet
Retrieve Metadata Requests
top

API to Retrieve all metadata requests or a specific request by ID

Operation HTTP Request Description
GET /api/request/metadata All Metadata Requests (with limited payload returned)
GET /api/request/metadata/<request_id> Metadata Request by ID
Requirements:
  • Authorization Header set to your token
  • id Required for the request by ID query
Example Requests:

curl --location --request GET 'https://ceapi.yewno.com/api/request/metadata/971a4817-0149-43e1-bf52-04cc5a36a6c0'
--header 'Authorization: ___YOUR_AUTH_CODE___

import requests
url = "https://ceapi.yewno.com/api/request/metadata/971a4817-0149-43e1-bf52-04cc5a36a6c0"
headers = {'Authorization': '___YOUR_AUTH_CODE___'}
response = requests.request("GET", url, headers=headers)
print(response.json())
Response Details:
  • id: Request ID
  • status: Status of request. Options are awaiting, processing, complete
  • fileNames: List of filenames by url which can be downloaded
  • fulfilledAt: Time at which the request was fulfilled
  • createdAt: Time at which the request was created
  • Above are returned with request without ID. Below are returned with query by ID.
  • sourceType: Source type requested
  • dateStart: Start date requested
  • dateEnd: End date requested
  • source: Sources requested ISINs and/or concepts
  • destination: Destinations requested ISINs and/or concepts
  • expandIsins: Boolean flag requested
  • expandParents: Boolean flag requested
  • expandSnippetSource: Boolean flag requested
  • filters: Filters requested
  • limit: Any limit requested
  • sort: Sort settings requested
  • notes: Any notes regarding the metadata retrieval
  • errors: Any errors that occurred during the metadata retrieval
Example Response:
{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "6fdc4ee9-e968-4980-b19f-637b857cec32",
        "status": "complete",
        "sourceType": "news",
        "dateStart": "2020-01-01",
        "dateEnd": "2020-12-31",
        "source": {
            "isins": ["US0231351067", "US0378331005", "US88160R1014"],
            "concepts": ["af55336221b72bee24d6c136a4a459ed", "d018b082e8a372d9b860417e823c6451", "0e85749a6f40d4614b87411e141fe810"]
        },
        "destination": {
            "isins": ["US5949181045", "US0378331005"],
            "concepts": []
        },
        "expandIsins": true,
        "expandParents": true,
        "expandSnippetScore": true,
        "filters": {
            "entitiesOnly": true,
            "conceptsOnly": false,
            "categories": [],
            "threshold": {
                "factor": "score",
                "op": "gte",
                "value": 0.0
            }
        },
        "sort": {
            "sortBy": "score",
            "sortAsc": false
        },
        "limit": 100,
        "fields": [],
        "notes": [],
        "errors": [],
        "percentComplete": 100.0,
        "fileNames": ["https://ceapi.yewno.io/stage/CEHistory/metadata/e5c3bf12-537e-4d12-8707-bf780e77f6c5.13d3a547-d978-440d-95f5-546d7b245a47.csv"],
        "fulfilledAt": "2021-01-26T20:03:40.505482",
        "createdAt": "2021-01-26T19:53:33.432638"
    }
}


Snippet Request

New Snippet Request
top

Request for new Snippet data to be processed which will return a request ID to be tracked until the request is completed and then the file and corresponding snippet data can be downloaded.
NOTE: Snippets for news considers concepts on a sentence level whereas all other sources consider concepts on a document level.

Operation HTTP Request Description
POST /api/request/snippets New Snippet Request
Requirements:
  • Authorization Header set to your token
  • articleIds [REQUIRED] a list of article ids retrieved from the output file from the Metadata search
  • filters [OPTIONAL] Map with the following details to help filter your results:
    • threshold: [OPTIONAL] Filter Results by Threshold. Map with the following data: { "factor": option is score, "op": operation options are gt (greater than), gte (greater than equal to), lt (less than), lte (less than equal to) "value": float value to use as your threshold }
    • categories: [OPTIONAL] List of concept categories to include in file. Options [company, person, place, other]
    • entitiesOnly: [OPTIONAL] Boolean. Results file will be composed of only exposed publicly traded companies (default: False)
    • conceptsOnly: [OPTIONAL] Boolean. Results file will be composed of only exposed non-publicly traded company concepts (default: False)
  • sort [OPTIONAL] map with the following data points:
    • sortBy: Factor to sort by. Option is score.
    • sortAsc: Boolean. True to sort ascending, False to sort descending.
  • limit [OPTIONAL] integer: total number of records returned per request type (isin/concept) per day
  • fields [OPTIONAL] list of fields to be returned in csv. See below for options here
Example Requests:

curl --location --request POST 'https://ceapi.yewno.com/api/request/snippets'
--header 'Authorization: ___YOUR_AUTH_CODE___'
--header 'Content-Type: application/json'
--data-raw '{
    "articleIds": [
        "5516f96e9392789dc793ca0601eafc54",
        "ac59cea3c4ba42476c66350fff22e181",
        "2ab6d90782f6cacc04bfa92f3d8238ac",
        "44be857d434425f5f8ed83e902b58867",
        "74765a64e6594590a3308c2d9780486f",
        "44be857d434425f5f8ed83e902b58867"
    ],
    "sort": {
        "sortAsc": false,
        "sortBy": "score"
    },
    "filters": {
        "threshold": {
            "factor": "score",
            "op": "gte",
            "value": 0.5
        }
    },
    "limit": 100,
    "fields": [
        "ArticleID",
        "SnippetID",
        "Snippet",
        "Score",
        "ConceptOne",
        "ConceptTwo"
    ]
}'

import requests
import json
url = "https://ceapi.yewno.com/api/request/snippets"
payload = {'articleIds': ['5516f96e9392789dc793ca0601eafc54', 'ac59cea3c4ba42476c66350fff22e181',
    '2ab6d90782f6cacc04bfa92f3d8238ac', '44be857d434425f5f8ed83e902b58867', '74765a64e6594590a3308c2d9780486f',
    '44be857d434425f5f8ed83e902b58867'], 'sort': {'sortAsc': False, 'sortBy': 'score'}, 'filters': {
    'threshold': {'factor': 'score', 'op': 'gte', 'value': 0.5}}, 'limit': 100, 'fields': ['ArticleID', 'SnippetID',
    'Snippet', 'Score', 'ConceptOne', 'ConceptTwo']}

headers = {
  'Authorization': '___YOUR_AUTH_CODE___',
  'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=json.dumps(payload))
print(response.json())
Response Details:
  • requestID: New Request ID
  • msg: Success Message
Example Response:
{
    "status": 200,
    "message": "snippets request received and processing",
    "data": {
        "requestId": "2152900a-33b4-40e5-a700-050b428d40a2"
    }
}
Resulting Output File:

Once your request starts processing file names will begin to be populated into the filenames list in your response. Those files will either be in CSV or ZIP (containing CSVs) format, depending on how large the data is. The CSVs will have the following headers which can be specified in the "Fields" attribute specified above.

  • ArticleID: ID of the article or document
  • SnippetID: ID of the snippet
  • Snippet: Actual text of the extracted snippet
  • Score: Score of the snippet
  • ConceptOneID: ID of the first concept
  • ConceptOne: Title of the first concept
  • ConceptOneCategory: Category of the first concept
  • ConceptOneIsin: ISIN of the first concept
  • ConceptTwoID: ID of the second concept
  • ConceptTwo: Title of the second concept
  • ConceptTwoCategory: Category of the second concept
  • ConceptTwoIsin: ISIN of the second concept
Retrieve Snippet Requests
top

API to Retrieve all snippet requests or a specific request by ID

Operation HTTP Request Description
GET /api/request/snippets All Snippet Requests (with limited payload returned)
GET /api/request/snippet/<request_id> Snippet Request by ID
Requirements:
  • Authorization Header set to your token
  • id Required for the request by ID query
Example Requests:

curl --location --request GET 'https://ceapi.yewno.com/api/request/snippet/2152900a-33b4-40e5-a700-050b428d40a2'
                --header 'Authorization: ___YOUR_AUTH_CODE___

import requests
url = "https://ceapi.yewno.com/api/request/snippet/971a4817-0149-43e1-bf52-04cc5a36a6c0"
headers = {'Authorization': '___YOUR_AUTH_CODE___'}
response = requests.request("GET", url, headers=headers)
print(response.json())
Response Details:
  • id: Request ID
  • status: Status of request. Options are awaiting, processing, complete
  • fileNames: List of filenames by url which can be downloaded
  • fulfilledAt: Time at which the request was fulfilled
  • createdAt: Time at which the request was created
  • Above are returned with request without ID. Below are returned with query by ID.
  • articleIds: Article Ids requested
  • filters: Filters requested
  • limit: Any limit requested
  • sort: Sort settings requested
  • notes: Any notes regarding the snippet retrieval
  • errors: Any errors that occurred during the snippet retrieval
Example Response:
{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "3f3184f4-4605-46e0-9313-e0e296768d85",
        "status": "complete",
        "articleIds": ["5516f96e9392789dc793ca0601eafc54", "ac59cea3c4ba42476c66350fff22e181", "2ab6d90782f6cacc04bfa92f3d8238ac", "44be857d434425f5f8ed83e902b58867", "74765a64e6594590a3308c2d9780486f", "44be857d434425f5f8ed83e902b58867"],
        "filters": {
            "entitiesOnly": false,
            "conceptsOnly": false,
            "categories": [],
            "threshold": {
                "factor": "score",
                "op": "gte",
                "value": 0.5
            }
        },
        "sort": {
            "sortBy": "score",
            "sortAsc": false
        },
        "limit": 100,
        "fields": ["ArticleID", "SnippetID", "Snippet", "Score"],
        "notes": [],
        "errors": [],
        "percentComplete": 100.0,
        "fileNames": ["https://ceapi.yewno.io/stage/CEHistory/snippets/e5c3bf12-537a-4d12-8707-bf780e77f6c5.3f3184f4-4605-46e0-9313-e0e298768d85.csv"],
        "fulfilledAt": "2021-01-27T20:12:15.379563",
        "createdAt": "2021-01-27T20:02:19.076187"
    }
}


Theme Request

Retrieve Theme
top

API to Retrieve Theme based off a supplied ConceptID

Operation HTTP Request Description
POST /api/request/theme Retrieves Theme for Supplied Concept
Requirements:
  • Authorization Header set to your token
  • concept Concept ID to generate a theme for
  • filters [OPTIONAL] Map with the following details to help filter your results:
    • threshold: [OPTIONAL] Filter Results by Threshold. Map with the following data: { "factor": options are score, "op": operation options are gt (greater than), gte (greater than equal to), lt (less than), lte (less than equal to), "value": float value to use as your threshold }
    • categories: [OPTIONAL] List of concept categories to include in file. Options [company, person, place, other]
  • limit [OPTIONAL] integer: total number of records returned
Example Requests:

curl --location --request POST 'https://ceapi.yewno.com/api/request/theme'
--header 'Authorization: ___YOUR_AUTH_CODE___'
--header 'Content-Type: application/json'
--data-raw '{
    "concept": "8de4a485422b0aa32304a9e47200c56d",
    "filters": {
        "categories": ["company", "place"],
        "threshold": {
            "factor": "score",
            "op": "gte",
            "value": 0.25
        }
    },
    "limit": 10
}

import requests
import json
url = "https://ceapi.yewno.com/api/request/theme"
payload = {'concept': '8de4a485422b0aa32304a9e47200c56d', 'filters': {'categories': ['company', 'place'], 'threshold':
    {'factor': 'score', 'op': 'gte', 'value': 0.25}}, 'limit': 10}
headers = {
  'Authorization': '___YOUR_AUTH_CODE___',
  'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=json.dumps(payload))
print(response.json())
Response Details:
  • concept: Title of the concept
  • conceptID: ID of the concept
  • category: Category of the concept
  • score: The theme-similarity metric identifies concepts that are closely related to the input concept, the calculation leverages the definition of the concepts and the most recent news similarity exposure metric.
Example Response:
{
    "status": 200,
    "message": "theme retrieved successfully",
    "data": [
        {
            "title": "NJOY",
            "category": "company",
            "cId": "9a6845238e78f8cea73f6de69e6a2ae1",
            "score": 0.505942053248873
        },
        {
            "title": "American Snuff Company",
            "category": "company",
            "cId": "3287d33eabea196056db77cc02a11a40",
            "score": 0.5029098047525622
        },
        {
            "title": "The Merck Manuals",
            "category": "company",
            "cId": "3995ef9f0b9c5ad283d71ac8b9f76a67",
            "score": 0.46856436115922406
        },
        {
            "title": "Healthier Choices Management Corp.",
            "category": "company",
            "cId": "8f5f62ed338018334671507b4b938d1a",
            "score": 0.46068631127127446
        },
        {
            "title": "Miles Laboratories",
            "category": "company",
            "cId": "5ef409258a9fb89409e6e87d9909a24b",
            "score": 0.4396199474867899
        },
        {
            "title": "Reynolds American",
            "category": "company",
            "cId": "64568ec8eb1da31f1a83715ec034ab73",
            "score": 0.41922633815556765
        },
        {
            "title": "Philip Morris International",
            "category": "company",
            "cId": "13a74cf28b1b9472e6cd4893baf75461",
            "score": 0.4183376356959343
        },
        {
            "title": "British American Tobacco Kenya Ltd.",
            "category": "company",
            "cId": "df0f95904e654759c5d3ec5f4b23d4f4",
            "score": 0.4181630050879903
        },
        {
            "title": "Vought",
            "category": "company",
            "cId": "41d598d6ed26ec10d33896c427ca62b1",
            "score": 0.41593022193410434
        },
        {
            "title": "Aftermath Services",
            "category": "company",
            "cId": "68ae9a92261c803d8f71a2749eec15d0",
            "score": 0.4095877810323145
        }
    ]
}


Change Log

Changes from v2.0 to v2.3
  • Themes
    • Addition of the theme request API

Previous Versions: