Open PermID - Entity Search · RESTful API

API Family: Open PermID

Entity Search - Quick Start Guide

Introduction

The goal of this Quick Start is to guide you through the Entity Search REST API using it's dedicated Swagger User Interface. Swagger UI is a great tool that documents and allows you to test REST APIs. This guide shows you how to use it along with the Entity Search REST API. Once you have completed this QuickStart, you'll be able to experiment and then better understand the different operations, parameters of the API as well as the server responses. 

This Quick Start will guide you through the following steps: 

Get your access-token

The Open PermID Entity Search API requires an access-token to be provided for every API operation you call. This access-token (also known as an API Key) is unique and associated to your Open PermID account. The same token can be used for all Open PermID APIs (Record Matching, Entity Search and Calais Tagging). If you already have an Open PermID account, you can skip the following section and directly jump to the Display and copy your access-token section.

Create your Open PermID account and the associated access-token

Before you call any of the Open PermID operations you must register yourself on the Open PermID portal. The registering process creates both the Open PermID account and the associated access-token you need to call the API operations. 

To register to Open PermID, please follow the steps below: 

  1. In this page click on the Dev Tools tab
  2. Click on the Request A Key button
  3. Fill in the registration form with the required information and click on the Register button

Note: The above instructions explain how to register and create your Open PermID account via the Dev Portal. Alternatively, you can directly register via the Open PermID portal. To this aim, open the permid.org home page, click on Register at the top right of the page and follow the instructions.

Display and copy your access-token

Once your Open PermID account is created, you have access to the associated access-token. As you will need this token in the next section for calling API operations on the server, it may be a good idea to copy it to the clipboard. Then, you'll just have to paste it into the appropriate parameter of the request. Please execute the following steps to copy the token:

  1. In this page click on the Dev Tools tab.
  2. Click on My API keys
    Your Open PermID access-token is displayed as shown below

    The access-token is displayed after the Your Key: label. As you can see, this token is related to the BOLD-REGISTERED-PRODUCT that is the Open PermID product name.
    Note: In the context of the Open PermID APIs, the “access-token” and “API key” terms have the same meaning. However, even if these terms are synonyms, Open PermID users tend to use “Access token” or simply “Token” more frequently than “API key”.
  3. Click on Copy Key to copy the access-token in the clipboard.

Note: The above instructions explain how to get your access-token from the Dev Portal. Alternatively, you can get it from the Open PermID portal. To this aim, go to the permid.org home page, log in, at the top right of the page move the mouse over you email address and click on Display my Token.

Call an API operation using the Swagger UI

Now that the access-token is in the clipboard, you are ready to call your first API operation. To this aim you'll use the Entity Search Swagger UI available under the Dev. Tools tab. This Swagger UI gives you access to the three GET operations of the Entity Search API (/{id}, /permid/search and /permid/{search}). The following instructions explain how to use the /permid/search GET operation to search for PermIDs that relates to the "micro" string.

  1. In the Dev Tools tab, click on the Swagger menu item to open the Entity Search Swagger UI
  2. Click on the /permid/search GET operation to expand it and display the related parameters.
  3. Paste your access-token (aka. API key) into the access-token field.
  4. Type "micro" in the q parameter.
  5. Leave the other fields blank
  6. Click on the Try it out! button

After you clicked on Try it out!, the Swagger UI sends the request to the Open PermID server, waits for the response and displays it.

This is the kind of response you should get:

Check the server response

Among other information, the Open PermID server replied with a Response Code and a Response Body

  • The Response Code gives you a status on the request you sent. If everything went fine the returned code should be "200", meaning the request has been treated successfully by the server.
  • The Response Body contains the actual data you requested. Here are the details:
{
  "result": {
    "organizations": {
      "entityType": "organizations",
      "total": 2001,
      "start": 1,
      "num": 5,
      "entities": [
        {
          "@id": "https://permid.org/1-4295903297",
          "organizationName": "Advanced Micro Devices Inc",
          "primaryTicker": "AMD",
          "orgSubtype": "Company",
          "hasHoldingClassification": "publiclyHeld",
          "hasURL": "http://www.amd.com/"
        },
        {
          "@id": "https://permid.org/1-4295903213",
          "organizationName": "Ingram Micro Inc",
          "primaryTicker": "IM",
          "orgSubtype": "Company",
          "hasHoldingClassification": "publiclyHeld",
          "hasURL": "http://www.ingrammicro.com/"
        },
        {
          "@id": "https://permid.org/1-4295878807",
          "organizationName": "Trend Micro Inc",
          "primaryTicker": "4704",
          "orgSubtype": "Company",
          "hasHoldingClassification": "publiclyHeld",
          "hasURL": "http://www.trendmicro.co.jp/"
        },
        {
          "@id": "https://permid.org/1-4295897861",
          "organizationName": "Micro Focus International PLC",
          "primaryTicker": "MCRO",
          "orgSubtype": "Company",
          "hasHoldingClassification": "publiclyHeld",
          "hasURL": "http://www.microfocus.com"
        },
        {
          "@id": "https://permid.org/1-4295907725",
          "organizationName": "RF Micro Devices Inc",
          "primaryTicker": "RFMD",
          "orgSubtype": "Company",
          "hasURL": "https://www.rfmd.com"
        }
      ]
    },
    "instruments": {
      "entityType": "instruments",
      "total": 173,
      "start": 1,
      "num": 5,
      "entities": [
        {
          "@id": "https://permid.org/1-8590934144",
          "hasName": "Advanced Micro Devices Ord Shs",
          "assetClass": "Ordinary Shares",
          "isIssuedByName": "Advanced Micro Devices Inc",
          "isIssuedBy": "https://permid.org/1-4295903297",
          "hasPrimaryQuote": "https://permid.org/1-55838319834",
          "primaryTicker": "AMD"
        },
        {
          "@id": "https://permid.org/1-8590925692",
          "hasName": "Ingram Micro Ord Shs Class A",
          "assetClass": "Ordinary Shares",
          "isIssuedByName": "Ingram Micro Inc",
          "isIssuedBy": "https://permid.org/1-4295903213",
          "hasPrimaryQuote": "https://permid.org/1-55838323215",
          "primaryTicker": "IM"
        },
        {
          "@id": "https://permid.org/1-8590943472",
          "hasName": "Trend Micro Ord Shs",
          "assetClass": "Ordinary Shares",
          "isIssuedByName": "Trend Micro Inc",
          "isIssuedBy": "https://permid.org/1-4295878807",
          "hasPrimaryQuote": "https://permid.org/1-55837426446",
          "primaryTicker": "4704"
        },
        {
          "@id": "https://permid.org/1-21500952706",
          "hasName": "Trend Micro Ord Shs",
          "assetClass": "Ordinary Shares",
          "isIssuedByName": "Trend Micro Inc",
          "isIssuedBy": "https://permid.org/1-4295878807"
        },
        {
          "@id": "https://permid.org/1-8590942645",
          "hasName": "Trend Micro ADR Rep 1 Ord Shs",
          "assetClass": "American Depository Receipts",
          "isIssuedByName": "Trend Micro Inc",
          "isIssuedBy": "https://permid.org/1-4295878807",
          "hasPrimaryQuote": "https://permid.org/1-55835429369",
          "primaryTicker": "TMICY"
        }
      ]
    },
    "quotes": {
      "entityType": "quotes",
      "total": 908,
      "start": 1,
      "num": 5,
      "entities": [
        {
          "@id": "https://permid.org/1-55838319834",
          "hasName": "ADVANCED MICRO DEVICES ORD",
          "assetClass": "Ordinary Shares",
          "isQuoteOfInstrumentName": "Advanced Micro Devices Ord Shs",
          "hasRIC": "AMD.OQ",
          "hasMic": "XNCM",
          "hasExchangeTicker": "AMD",
          "isQuoteOf": "https://permid.org/1-8590934144"
        },
        {
          "@id": "https://permid.org/1-55838323215",
          "hasName": "INGRAM MICRO CL A ORD",
          "assetClass": "Ordinary Shares",
          "isQuoteOfInstrumentName": "Ingram Micro Ord Shs Class A",
          "hasRIC": "IM.N",
          "hasMic": "XNYS",
          "hasExchangeTicker": "IM",
          "isQuoteOf": "https://permid.org/1-8590925692"
        },
        {
          "@id": "https://permid.org/1-55837426446",
          "hasName": "TREND MICRO ORD",
          "assetClass": "Ordinary Shares",
          "isQuoteOfInstrumentName": "Trend Micro Ord Shs",
          "hasRIC": "4704.T",
          "hasMic": "XTKS",
          "hasExchangeTicker": "4704",
          "isQuoteOf": "https://permid.org/1-8590943472"
        },
        {
          "@id": "https://permid.org/1-55836047311",
          "hasName": "MICRO FOCUS INTERNATIONAL ORD",
          "assetClass": "Ordinary Shares",
          "isQuoteOfInstrumentName": "Micro Focus International Ord Shs",
          "hasRIC": "MCRO.L",
          "hasMic": "XLON",
          "hasExchangeTicker": "MCRO",
          "isQuoteOf": "https://permid.org/1-8590922876"
        },
        {
          "@id": "https://permid.org/1-55839325640",
          "hasName": "RF MICRO DEVICES ORD",
          "assetClass": "Ordinary Shares",
          "isQuoteOfInstrumentName": "RF Micro Devices Ord Shs",
          "hasRIC": "RFMD.O^A15",
          "hasExchangeTicker": "RFMD",
          "isQuoteOf": "https://permid.org/1-8590922704"
        }
      ]
    }
  }
}

In the Response Body, the server returns all the entities that matched the “micro” search string you set in the q parameter of the request. The returned entities are categorized by type in the 3 objects of the result field. The organizations object contains the organization entities, the instruments object contains the instrument entities and the quotes object the quote entities. These three objects have an entities array that contains the found entities. Each entity has a number of fields that will not be explained in this Quick Start guide. Please refer to the Search Entity User Guide to learn more about them. However, it is worth mentioning the @id field that contains the URL of the related PermID. 
Details of these PermIDs can be displayed by opening these URLs in your usual browser. Below is an example for AMD: https://permid.org/1-4295903297

Troubleshooting

In the event things didn't go as expected, ensure you didn't make one of the following common mistakes:

The Dev. Tools tab has no Request a Key menu item and no My API keys menu item.
You are probably not logged in the Dev Portal. Please login or register if you do not have an account yet. 

My API keys displays "Looks like you have no apps" under the Apps & Keys title.
You probably didn’t create your Open PermID account and the associated access-token (aka. API key). Please follow the Create your Open PermID account and the associated access-token steps of this guide.

The Response Body has no content and the Response Headers displays the “no response from the server” error.
The access-token you used for the x-ag-access-token parameter may not be correct. Please verify you're using the right token.

To learn more

Now that you know how to use the Entity Search Swagger UI, we recommend you to spend some time experimenting the different operations and parameters of the API. 
We also recommend you to follow the Entity Search tutorials that explain how to leverage the API in Java example applications.

References

For more information, refer to the Entity Search User Guide.