Entity Search - Search Tutorial

Download tutorial source code	Click here to download
Last update	August 2016
Environment	Windows, Linux
Compilers	JDK 1.7 or greater
Prerequisites	Components Java compiler, optional IDE, requesting access token Apache HTTP client (tested with http-components-client 4.4) Java-json is optional

Introduction

The PermID Service lets you utilize the permanent ID of about 5.96mn organizations, 300K equity instruments, and 1.72mn equity quotes (coverage as of May 2020), from the Refinitiv core entity data set. PermID Service provides access to Refinitiv permanent identifiers (permanent unique IDs formatted as Uniform Resource Identifiers) along with the associated descriptive fields that Refinitiv exposes to the public. The descriptive fields enable the user to verify that a consumed permID represents the entity of interest.

The data is live; records are updated every 15 minutes.

The goal of this tutorial is to retrieve an entity info by passing its permid to Entity Search Lookup access point

Description

The Entity-Search API enables users to retrieve entities in two ways:

By including in the request the PermID service itself.
By searching for an entity by name, ticker, RIC (Reuters Instrument Code).

This tutorial goes over the second way, and it illustrates the implementation in Java.

Please note that any language that supports HTTP can be used to implement.

Setup Steps

The steps include:

Get your access-token from the Try it Out! tab (read the Quick Start guide learn how to do it)
Review the example source code
Build and run
- Setup Eclipse or other Java project
- Or build the java example from the command line
- Include HTTP client prerequisite libraries provided with the tutorial

Review the example code

The steps include:

Specify the end-point URL

    	
            // specify end-point URL 
String url = "https://api-eit.refinitiv.com:443/permid/search?";

Specify the query to run

    	
             // query for entities that contain in their name "micro"
 url = url.concat("q=name:micro");

Specify Entity Type (Organization, Instrument or Quote)

    	
            // search for organizations only, not instruments
url = url.concat("entityType=Organization");

Create HTTP GET request

    	
            // create HTTP GET
CloseableHttpClient client = HttpClientBuilder.create().build();
HttpGet request = new HttpGet(url);

Set “X-AG-Access-Token” as header (please note, that token can be optionally be passed as query)

    	
            // add unique access token as request header
request.addHeader("X-AG-Access-Token", args[0]);

Issue request

    	
            // issue request
HttpResponse response = client.execute(request);

Process response (output)

    	
            // process response
BufferedReader rd = new BufferedReader(
new InputStreamReader(response.getEntity().getContent()));
 
StringBuffer result = new StringBuffer();
String line = "";
while ((line = rd.readLine()) != null) {
     result.append(line);
}

As an alternative to simple printing, one can pretty-print json object one can use java-json library included in the prerequisite folder:

    	
            ResponseHandler<String> responseHandler=new BasicResponseHandler();
 
// issue request
String strResponse = client.execute(request, responseHandler);
 
JSONObject jsonResponse=new JSONObject(strResponse);
           
// pretty-print json response
int spacesToIndentEachLevel = 2;
System.out.println("JSON
response:\n"+jsonResponse.toString(spacesToIndentEachLevel));

Build and run

The quickest way to build and run is with an IDE, Eclipse or NetBeans would work great

To build and run from the command line:

Build:

    	
            javac -cp ".;prereqs\httpclient-4.4.jar;prereqs\httpcore-4.4.jar;prereqs\java-json.jar" tr/test/*.java

    	
            java -cp ".;prereqs\httpclient-4.4.jar;prereqs\httpcore-4.4.jar;prereqs\commons-logging-1.2.jar;
            prereqs\java-json.jar;prereqs\httpmime-4.4.jar" tr.test.HTTPClientEntitySearchSearch YOURTOKENGOESHERE

Understanding the input

The request constructed by our example will look like this:

Request URL: https://api-eit.refinitiv.com:443/permid/search?q=name%3Amicro&Entitytype=organization

The request includes the path and the query parameters. What we do not see is that mandatory header “X-AG-Access-Token” is also included with the request. In this example we are requesting from api-eit.refinitiv.com search service to search for all organizations, whose name contains “micro”.

Understanding the expected output

This is the response we receive when we search for a name containing substring “micro” as shown above:

    	
            JSON response:
{"result": {
  "organizations": {
    "total": 2000,
    "entities": [
      {
        "hasURL": "http://www.amd.com/",
        "organizationName": "Advanced Micro Devices Inc",
        "orgSubtype": "Company",
        "primaryTicker": "AMD",
        "@id": "https://permid.org/1-4295903297",
        "hasHoldingClassification": "publiclyHeld"
      },
      {
        "hasURL": "http://www.ingrammicro.com/",
        "organizationName": "Ingram Micro Inc",
        "orgSubtype": "Company",
        "primaryTicker": "IM",
        "@id": "https://permid.org/1-4295903213",
        "hasHoldingClassification": "publiclyHeld"
      },
 
    …
 
   ],
    "entityType": "organizations",
    "num": 5,
    "start": 1
  }

Within the above JSON output contains organizations with the string "Micro" in their name.

For more information on JSON please refer to: http://json.org

Learn more

For more information, developer guides, FAQ and Release Notes check out the documentation

Download tutorial source code

Click here to download