Open PermID Release notes R1.2

Transcription

1 Preface Permid.org is the public-facing portal for Thomson Reuters core entities and metadata, providing the tools that enable you to work with PermIDs unique identifiers for objects in the Thomson Reuters Information Model (TRiM). Each PermID is associated with a web address, which serves as a permanent identity for that entity. Permid.org provides three different tools for returning PermIDs: 1. Entity Search: Search for a PermID by name or identifier, or use the PermID Lookup API to return PermIDs. 2. Record Matching: Upload up to 1,000 of your own record to return PermIDs for each one. 3. Open Calais Tagging: Use Open Calais to automatically extract PermIDs for the organizations, instruments, and quotes hidden within your unstructured text. Each of these capabilities also has an API associated with it, with API tokens available to registered users. This document is intended for existing users of Open PermID, and describes the changes in the current version relative to the previous release. Note For detailed information about the three APIs and their output, see the users guides available on the Open PermID developer portal: Note that because Open Calais is a stand-alone product that is hosted on Open PermID, it has a separate release schedule and dedicated release notes. The Open Calais release notes will document changes and enhancements to Open Calais.

2 New Features The following features and enhancements are included in this release: Atom Feed Entity Search API Lookup Entity lookup now supports the JSON-LD format Entity Search API Search by Identifiers The list of supported identifiers has been extended. Record Matching - Search by Identifiers The list of supported identifiers has been extended.

3 ATOM FEED Open PermID data is updated every 15 minutes. The incremental updates can be consumed for each of the entities via the PermID website and API. The Atom Feed feature is available only to registered Open PermID and Open Calais users. To use Atom Feed via the Open PermID site, please log in to the site using your registration credentials, and then click the relevant icon on the bottom right of the Open PermID screen. To use the API, please use the token provided within the registration . Need an account? Register here Atom Feed Content and Format Each entity (organization, instruments and quotes) has its own Atom feed. Each Atom feed enables retrieving up to 1000 latest updated records (up to 5 days back). In order to consume the Atom feed, the programmer should iterate the list of updated entities and do the following:

4 1. Retrieve the URI updated record by Entity Lookup API. 2. Replace the current stored entity record with the updated record. Request End point: Example: The request is an HTTP GET with the following query parameters: PARAMETER Access-Token DESCRIPTION If passed on HTTP parameters: "access-token=xyz" If passed (preferably) as HTTP header: X-AG-Access-Token: xyz Replace xyz with the provided registration token. Response PARAMETER Content Type Status DESCRIPTION The content type of the response: application/xml. Numeric return code for the request. The value corresponds to the HTTP return codes. For example, "200" indicates that the request was successfully processed. "400" is the code for a bad request. Example: Token through query parameters: HTTP REST GET See Appendix A for an output example.

5 ENTITY LOOKUP SUPPORTS JSON-LD FORMAT R1.2. provides entity data in JSON-LD as well as turtle (the default format). Request PARAMETER Accept DESCRIPTION Format of the returned result: text/turtle (the default), application/ld+json Access-Token If passed on HTTP parameters: "access-token=xyz" If passed (preferably) as HTTP header: X-AG-Access-Token: xyz Replace xyz with the provided regirstation token. Response Parameter Content Type Status Description The content type of the response: text/turtle (the default), application/ld+json The format of the response is temporary and is subject to change. Numeric return code for the request. The value corresponds to the HTTP return codes. For example, "200" indicates that the request was successfully processed. "400" is the code for a bad request. Example: Token through query parameters HTTP REST GET See Appendix B for an output example.

6 ENTITY SEARCH API - SEARCH BY ADDITIONAL IDENTIFIERS R1.2 expands the list of supported identifiers to include the following (in addition to ticker and RIC). Note The new identifiers must be searched by their type as context. Identifiers IDENTIFIER TYPE Entity Type(S) CONTEXT IN SEARCH AND MATCHING BEID Organization Beid CIDGEN Organization Cidgen CIK Organization Cik Data Stream Mnemonic Quote datastream_mnemonic ILX Ticker Qoute Ilx MXID Organization mxid RCP ID Orgaization Rcpid SDC CUSIP Organization Sdc WorldScopeCompanyID Organization Worldscopeid WorldScopeCompanyPermID Organization worldscopecompanypermid Example: Query: HTTP REST GET &access-token=<token> See Appendix C for an output example.

7 RECORD MATCHING API MATCH BY ADDITIONAL IDENTIFIERS The Record Matching API supports the same identifiers as search (see above). The identifier types must be included within the match query under the Specified identifier field. There are no change in the request and response definitions. Example: Plain Text Query HTTP REST POST http(s)://api.thomsonreuters.com/permid/match Parameters Content-Type:text/plain x-openmatch-numberofmatchesperrecord: 1 x-openmatch-datatype: Organization X-AG-Access-Token: YOUR TOKEN HERE Body LocalID,Standard Identifier 1,mxid: See Appendix D for an output example.

8 Backwards Compatibility R1.2 is fully backwards compatible with the April 21, 2015 release. We added support for the Accept parameter for Entity Lookup request. See Request in the section on JSON-LD format.

9 Appendix A: Atom Feed Format <?xml version="1.0" encoding="utf-8"?> <?xml-stylesheet type="text/xsl" media="screen" href="/public/459/atom/atom.xsl"?> <?xml-stylesheet type="text/css" media="screen" href="/public/459/atom/atom.css"?> <feed xmlns=" xmlns:opensearch=" <title>organization Feed</title> <link rel="self" href=" /> <link rel="first" href=" /> <link rel="next" href=" /> <link rel="last" href=" /> <author> <name>open PermID</name> <uri> </author> <subtitle>from date(utc) : T16:08:32.000Z, To date(utc) : T16:08:31.000Z, Window : Offset = 0, Length = 50, out of 1000 results.</subtitle> <id> <updated> t11:52:36z</updated> <opensearch:totalresults>1000</opensearch:totalresults> <opensearch:startindex>1</opensearch:startindex> <entry> <title>abc Leasing de Mexico 14-2 Abccb SA de CV</title> <link href=" /> <id> <updated> t11:52:36z</updated> </entry [... Additional entries] </feed>

10 Appendix B: Entity API Response in JSON-LD Format { "@id" : " "@type" : "tr-org:organization", "mdaas:headquartersaddress" : "1600 Amphitheatre Pkwy\nMOUNTAIN VIEW\nCALIFORNIA\n \nUnited States\n", "mdaas:registeredaddress" : "Corporation Trust Center\n1209 Orange Street\nNew Castle County\nWILMINGTON\nDELAWARE\n19801\nUnited States\n", "hasorganizationprimaryquote" : " "hasprimaryinstrument" : " "hasactivitystatus" : "tr-org:statusactive", "tr-org:hasheadquartersphonenumber" : " ", "hasholdingclassification" : "tr-org:publiclyheld", "hasipodate" : " T04:00:00Z", "hasorganizationfoundeddate" : " T00:00:00Z", "tr-org:hasregisteredfaxnumber" : " ", "tr-org:hasregisteredphonenumber" : " ", "isincorporatedin" : " "isdomiciledin" : " "hasurl" : " "vcard:organization-name" : "Google Inc", "@context" : { "hasipodate" : { "@id" : " "@type" : " "HeadquartersAddress" : { "@id" : " "@type" : " "hasregisteredfaxnumber" : { "@id" : " "@type" : " "organization-name" : { "@id" : " "@type" : " "hasregisteredphonenumber" : { "@id" : " "@type" : " "isdomiciledin" : { "@id" : " "@type" : "@id" "hasholdingclassification" : { "@id" : " "@type" : "@id"

11 "RegisteredAddress" : { "@id" : " "@type" : " "isincorporatedin" : { "@id" : " "@type" : "@id" "hasorganizationprimaryquote" : { "@id" : " "@type" : "@id" "hasactivitystatus" : { "@id" : " "@type" : "@id" "hasurl" : { "@id" : " "@type" : "@id" "hasprimaryinstrument" : { "@id" : " "@type" : "@id" "hasorganizationfoundeddate" : { "@id" : " "@type" : " "hasheadquartersphonenumber" : { "@id" : " "@type" : " "tr-common" : " "CorporateControl" : " "tr-fin" : " "fibo-be-oac-cpty" : " "mdaas" : " "fibo-be-le-fbo" : " FIBO/BE/LegalEntities/FormalBusinessOrganizations/", "tr-org" : " "xsd" : " "fibo-be-le-cb" : " "vcard" : "

12 Appendix C: Search by Identifer Example of search response: { { "result": { "organizations": { "entitytype": "organizations", "total": 1, "start": 1, "num": 1, "entities": [ { "@id": " "organizationname": "Microsoft Corp", "orgsubtype": "Company", "hasholdingclassification": "publiclyheld", "hasurl": " ] "instruments": { "entitytype": "instruments", "total": 0, "start": 1, "num": 0, "entities": [] "quotes": { "entitytype": "quotes", "total": 0, "start": 1, "num": 0, "entities": [] "ignore": " ", "unmatched": 0, "matched": { "total": 1, "excellent": 1 "numreceivedrecords": 1, "numprocessedrecords": 1, "numerrorrecords": 0, "headersidentifiedsuccessfully": [ "localid", "standard identifier" ],

13 "headersnotidentified": [], "headerssupportedwerenotsent": [ "name", "street", "city", "postalcode", "state", "country", "website" ], "errorcode": 0, "errorcodemessage": "Success", "resolvingtimeinms": 16, "requesttimeinms": 16, "outputcontentresponse": [ { "ProcessingStatus": "OK", "Match OpenPermID": " "Match OrgName": "Microsoft Corp", "Match Score": "100%", "Match Level": "Excellent", "Match Ordinal": "1", "Original Row Number": "2", "Input_LocalID": "1", "Input_Standard Identifier": "mxid: " ]

14 Appendix D: Match by Idenfier (Text Query) { "result": { "organizations": { "entitytype": "organizations", "total": 1, "start": 1, "num": 1, "entities": [ { "@id": " "organizationname": "Microsoft Corp", "orgsubtype": "Company", "hasholdingclassification": "publiclyheld", "hasurl": " ] "instruments": { "entitytype": "instruments", "total": 0, "start": 1, "num": 0, "entities": [] "quotes": { "entitytype": "quotes", "total": 0, "start": 1, "num": 0, "entities": []