Try out the Entity Search API using the Swagger UI
Swagger UI is a great tool that documents and allows you to test REST APIs. The goal of this tutorial is to guide you through the Entity Search REST API using it's dedicated Swagger User Interface. This guide shows you how to use it for trying out the Enity Search API.
The following instructions explains how to use the /permid/search GET operation to search for PermIDs related to the input search string. (Note: For representational purpose, the string used here is 'micro')
Instructions:
- Click on the 'Try it Out' button to enable the input parameter fields
- Paste your access token (API key) into the access-token field (If you do not have a access token, click here to view instructions to generate one)
- Type 'micro' in the 'q' parameter. (This fields also accepts standard identifiers such as tickers, RICs etc.)
- Leave the other fields blank, and click on 'Execute'
- At this instance, the Swagger UI sends the request to the PermID server, await for the response and displays it
- Among other information, the API response includes a Response Code and a Response Body
- Response Code: 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 handled successfully by the server
- Response Body: The Response Body contains the actual Search results . This means, in the Response Body, the server returns all the entities that matched against the string “micro”, in your input request. As shown, the returned entities are categorized by entityType in the 3 objects of the result field. The organizations object contains the organizations, the instruments object contains the instruments and the quotes object contains the quote entities.
{
"result": {
"organizations": {
"entityType": "organizations",
"total": 2003,
"start": 1,
"num": 5,
"entities": [
{
"@id": "https://permid.org/1-4295903297",
"organizationName": "Advanced Micro Devices Inc",
"primaryTicker": "AMD",
"orgSubtype": "Company",
"hasHoldingClassification": "publiclyHeld",
"hasURL": "https://www.amd.com/en"
},
{
"@id": "https://permid.org/1-4295867372",
"organizationName": "STMicroelectronics NV",
"primaryTicker": "STM",
"orgSubtype": "Company",
"hasHoldingClassification": "publiclyHeld",
"hasURL": "https://www.st.com/"
},
{
"@id": "https://permid.org/1-4295903213",
"organizationName": "Ingram Micro Inc",
"primaryTicker": "IM",
"orgSubtype": "Company",
"hasURL": "https://www.ingrammicro.com/IMD_WASWeb/jsp/login/corporate.jsp"
},
{
"@id": "https://permid.org/1-4295878807",
"organizationName": "Trend Micro Inc",
"primaryTicker": "4704",
"orgSubtype": "Company",
"hasHoldingClassification": "publiclyHeld",
"hasURL": "https://www.trendmicro.com/"
},
{
"@id": "https://permid.org/1-4295897861",
"organizationName": "Micro Focus International PLC",
"primaryTicker": "MCRO",
"orgSubtype": "Company",
"hasHoldingClassification": "publiclyHeld",
"hasURL": "https://www.microfocus.com/"
}
]
},
"instruments": {
"entityType": "instruments",
"total": 223,
"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-21725620193",
"hasName": "Advanced Micro Devices Inc Brazilian Depositary Receipt",
"assetClass": "Brazilian Depository Receipts",
"isIssuedByName": "Advanced Micro Devices Inc",
"isIssuedBy": "https://permid.org/1-4295903297",
"hasPrimaryQuote": "https://permid.org/1-21725620191",
"primaryTicker": "A1MD34"
},
{
"@id": "https://permid.org/1-25727374845",
"hasName": "Adv Micro Device Cedear",
"assetClass": "Argentinian Depository Receipts",
"isIssuedByName": "Advanced Micro Devices Inc",
"isIssuedBy": "https://permid.org/1-4295903297",
"hasPrimaryQuote": "https://permid.org/1-25727377413",
"primaryTicker": "AMD3"
},
{
"@id": "https://permid.org/1-8590942279",
"hasName": "Stmicroelectronics Ord Shs",
"assetClass": "Ordinary Shares",
"isIssuedByName": "STMicroelectronics NV",
"isIssuedBy": "https://permid.org/1-4295867372"
},
{
"@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"
}
]
},
"quotes": {
"entityType": "quotes",
"total": 1288,
"start": 1,
"num": 5,
"entities": [
{
"@id": "https://permid.org/1-21732546697",
"hasName": "MICRO LEASING ORD",
"assetClass": "Ordinary Shares",
"isQuoteOfInstrumentName": "Micro Leasing Ord Shs",
"hasRIC": "MICRO.BK",
"hasMic": "XBKK",
"hasExchangeTicker": "MICRO",
"isQuoteOf": "https://permid.org/1-21731689858"
},
{
"@id": "https://permid.org/1-55838319834",
"hasName": "ADVANCED MICRO DEVICES ORD",
"assetClass": "Ordinary Shares",
"isQuoteOfInstrumentName": "Advanced Micro Devices Ord Shs",
"hasRIC": "AMD.OQ",
"hasMic": "XNGS",
"hasExchangeTicker": "AMD",
"isQuoteOf": "https://permid.org/1-8590934144"
},
{
"@id": "https://permid.org/1-55835467238",
"hasName": "STMICROELECTRONICS ORD",
"assetClass": "Ordinary Shares",
"isQuoteOfInstrumentName": "Stmicroelectronics Ord Shs",
"hasRIC": "STM.PA",
"hasMic": "XPAR",
"hasExchangeTicker": "STM",
"isQuoteOf": "https://permid.org/1-8590942279"
},
{
"@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^L16",
"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"
}
]
}
}
}
These three objects have an entities array that has the matched entities, along with other attributes for that particular entity. Note that in the response, the @id field denotes the URL of the the related PermID (e.g: https://permid.org/1-4295903297), details of which can be viewed (as shown), by opening the URL in any standard web browser.
References
To learn more and for a detailed description of the API response, please refer the Entity Search API User Guide
We also recommend you to follow the Entity Search Tutorials that explains how to leverage the API in Java example applications
Questions?
If you have any querstions regarding the use of Entity Search API or any support questions in general, please use the Q&A section of the Developer Community and raise them there.