Yewno Concept Exposures API Documentation

Version 2.5


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.
Download Postman Schema

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"
                        }
                    ]
                }
            ]
        }
    ]
}


Request Management

Request Search
top

API to search for requests by status and/or type. Request will return all requests open or fulfilled within the last 10 days with a max response of 1000 requests.

Operation HTTP Request Description
GET /api/requests Retrieves all requests ordered by creation date descending.
GET /api/requests?status=processing,awaiting Retrieves all requests by status. Options are awaiting, processing, complete, cancelled
GET /api/requests?requestType=scores Retrieves all requests by type. Options are sentiment, trending, snippets, metadata, scores
Requirements:
  • Authorization Header set to your token
  • status [OPTIONAL] Comma delimited list of statuses to retrieve
  • requestType [OPTIONAL] Comma delimited list of request types to retrieve
Example Requests:

curl --location --request GET 'https://ceapi.yewno.com/api/requests?status=processing,awaiting&requestType=scores' --header 'Authorization: ___YOUR_AUTH_CODE___'

import requests
url = "https://ceapi.yewno.com/api/requests?status=processing,awaiting&requestType=scores"
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
  • requestType: Type of request
  • percentComplete: Percent completed
  • fileNames: List of filenames by url which can be downloaded
  • createdAt: Time at which the request was created
  • modifiedAt: Time at which the request was last modified at
  • fulfilledAt: Time at which the request was fulfilled
Example Response:
{
    "status": 200,
    "message": "OK",
    "data": [
        {
            "id": "982c76b6-48e7-4e12-beb3-c7c5bc840fd6",
            "status": "processing",
            "requestType": "scores",
            "percentComplete": 96.774194,
            "fileNames": [],
            "createdAt": "2021-06-02T18:16:20.119704",
            "modifiedAt": "2021-10-04T22:07:14.100165",
            "fulfilledAt": null
        },
        {
            "id": "b03180e8-951f-4497-9b47-289016f12c52",
            "status": "awaiting",
            "requestType": "sores",
            "percentComplete": 0.0,
            "fileNames": [],
            "createdAt": "2021-02-17T11:14:40.955764",
            "modifiedAt": "2021-02-17T19:34:35.287356",
            "fulfilledAt": null
        },
        {
            "id": "15813469-8fa0-403e-a68e-65f57d4778ad",
            "status": "awaiting",
            "requestType": "scores",
            "percentComplete": 0.0,
            "fileNames": [],
            "createdAt": "2021-02-02T13:22:06.238470",
            "modifiedAt": "2021-02-02T21:25:49.881036",
            "fulfilledAt": null
        }
    ]
}
Cancel Active Requests
top

API to cancel requests

Operation HTTP Request Description
PUT /api/request/trending/982c76b6-48e7-4e12-beb3-c7c5bc840fd6?action=cancel Cancel a supplied request
Requirements:
  • Authorization Header set to your token
Example Requests:

curl --location --request PUT 'https://ceapi.yewno.com/api/request/trending/982c76b6-48e7-4e12-beb3-c7c5bc840fd6?action=cancel' --header 'Authorization: ___YOUR_AUTH_CODE___'

import requests
url = "https://ceapi.yewno.com/api/request/trending/982c76b6-48e7-4e12-beb3-c7c5bc840fd6?action=cancel"
headers = {'Authorization': '___YOUR_AUTH_CODE___'}
response = requests.request("PUT", url, headers=headers)
print(response.json())
Response Details:
  • id: Request ID
  • status: Status of request. Options are awaiting, processing, complete
  • requestType: Type of request
  • percentComplete: Percent completed
  • fileNames: List of filenames by url which can be downloaded
  • createdAt: Time at which the request was created
  • modifiedAt: Time at which the request was last modified at
  • fulfilledAt: Time at which the request was fulfilled
Example Response:
{
    "status": 200,
    "message": "OK",
    "data": [
        {
            "id": "982c76b6-48e7-4e12-beb3-c7c5bc840fd6",
            "status": "cancelled",
            "requestType": "trending",
            "percentComplete": 96.774194,
            "fileNames": [],
            "createdAt": "2021-06-02T18:16:20.119704",
            "modifiedAt": "2021-10-04T22:07:14.100165",
            "fulfilledAt": null
        }
    ]
}


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
  • requestType: Type of request
  • percentComplete: Percent completed
  • fileNames: List of filenames by url which can be downloaded
  • createdAt: Time at which the request was created
  • modifiedAt: Time at which the request was last modified at
  • fulfilledAt: Time at which the request was fulfilled
  • 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
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
  • requestType: Type of request
  • percentComplete: Percent completed
  • fileNames: List of filenames by url which can be downloaded
  • createdAt: Time at which the request was created
  • modifiedAt: Time at which the request was last modified at
  • fulfilledAt: Time at which the request was fulfilled
  • 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. Currently sentiment is only provided on news sourceType and over the short 1d or 2d window.

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": Options are exposureSentiment or directSentiment, "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 exposureSentiment or directSentiment
    • 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": "exposureSentiment"
    },
    "filters": {
        "entitiesOnly": true,
        "conceptsOnly": false,
        "categories": [],
        "threshold": {
            "factor": "exposureSentiment",
            "op": "gte",
            "value": 0.075
        }
    },
    "limit": 100,
    "fields": [
        "ReferenceDate",
        "RequestedConceptID",
        "RequestedConcept",
        "RequestedIsin",
        "ConceptID",
        "Concept",
        "ConceptIsin",
        "ExposureSentiment"
    ]
}'

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': 'exposureSentiment'}, 'filters': {'entitiesOnly': True,
    'conceptsOnly': False, 'categories': [], 'threshold': {'factor': 'exposureSentiment', 'op': 'gte', 'value': 0.075}},
    'limit': 100, 'fields': ['ReferenceDate', 'RequestedConceptID', 'RequestedConcept', 'RequestedIsin', 'ConceptID',
    'Concept', 'ConceptIsin', 'ExposureSentiment']}

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
  • DirectSentiment: Concept-to-concept sentiment score of how directly connected concepts impact each other over the last 1d window
  • ExposureSentiment: Concept-to-concept sentiment score of how concepts can indirectly impact each other by leveraging the 2d News Aggregate Exposure score.
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
  • requestType: Type of request
  • percentComplete: Percent completed
  • fileNames: List of filenames by url which can be downloaded
  • createdAt: Time at which the request was created
  • modifiedAt: Time at which the request was last modified at
  • fulfilledAt: Time at which the request was fulfilled
  • 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": "exposureSentiment",
                "op": "gte",
                "value": 0.75
            }
        },
        "sort": {
            "sortBy": "exposureSentiment",
            "sortAsc": false
        },
        "limit": 100,
        "fields": ["ReferenceDate", "RequestedConceptID", "RequestedConcept", "RequestedIsin", "ConceptID", "Concept", "ConceptCategory", "ConceptIsin", "ExposureSentiment"],
        "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.

Note, for Patents, Transcripts, Official Filing, and Clinical Trials sources will return data where the source concept ids are the concepts extracted from within the document whereas the destination concept ids are the companies that published the document.

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: (NEWS ONLY) Score of the snippet
  • Snippet: (NEWS ONLY) Actual text of the extracted snippet
  • SnippetID: (NEWS ONLY) 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
  • requestType: Type of request
  • percentComplete: Percent completed
  • fileNames: List of filenames by url which can be downloaded
  • createdAt: Time at which the request was created
  • modifiedAt: Time at which the request was last modified at
  • fulfilledAt: Time at which the request was fulfilled
  • 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
  • requestType: Type of request
  • percentComplete: Percent completed
  • fileNames: List of filenames by url which can be downloaded
  • createdAt: Time at which the request was created
  • modifiedAt: Time at which the request was last modified at
  • fulfilledAt: Time at which the request was fulfilled
  • 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.4 to v2.5
  • Request Management
    • Added ability to search through your requests
    • Added functionality to cancel requests

Previous Versions: