UMLS REST API:
Paging through results.
This tutorial explains how to properly perform paging
through search results
retrieved through UMLS REST API.
We use the Google Chrome API testing app called
Postman to illustrate the behavior of the API.
You need to have a basic understanding of how to
properly make calls against the UMLS REST API.
You can watch our video tutorial on API
authentication and calling to refresh your memory.
Specifically, remember that to submit a UMLS REST API request
you need
1) obtain a reusable Ticket Granting Ticket, or TGT, using your UMLS
credentials,
2) Use the TGT to obtain a single-use Service Ticket, or ST,
and 3) use the ST to submit your API request.
To properly perform paging through results retrieved by the /search endpoint of the API,
it’s important to understand how your calls are affected by two parameters.
One parameter is pageSize.
It specifies the number of results to include per retrieved page.
The other is pageNumber; it specifies which page number of results to retrieve.
By default, UMLS API search requests retrieve the first 25 records,
and if you do not specify the value for the pageNumber parameter,
the first page of results will be returned.
In other words, if you make a call using for example a
URL shown here with a search query for the string
“neuropathy” in the SNOMED CT source vocabulary to retrieve
source unique identifiers of matching objects, the
system assumes you are submitting a call with
pageSize=25 and pageNumber=1.
As the /search endpoint may retrieve a very large number of results,
it cannot upfront provide the total number of pages available.
Other UMLS REST API endpoints return values the pageCount parameter
that indicates the total number of pages,
but /search endpoint does not return that information.
Therefore, it is important to understand how to construct API calls
against the /search endpoint to retrieve all objects.
Let’s submit the call with pageSize set at 25 and
pageNumber set at 1 using the Postman app.
JSON data returned indicate what page number you are on,
as defined by the pageNumber parameter.
To retrieve the second page of results,
we will change the value for the pageNumber parameter from 1 to 2
and make a new call to retrieve the second page.
You will need to continue submitting calls while
increasing the pageNumber value without knowing the total number of pages available.
To know that you have reached the end of results, you would need to submit
one more call to get JSON data containing the structure that includes
strings “NONE” and “NO RESULTS”, which indicate you have retrieved data in full.
Note that the end of search results will always exist on its own unique page,
with no objects.
Hence, when writing code for your UMLS REST API calls,
you will need to explicitly define the pageSize parameter and
iterate through each page using a do/while logical loop
that breaks when returned data contain the
“NONE” or “NO RESULTS” string,
which you can identify by parsing the output.
This concludes our tutorial.
For additional information on the UMLS REST API,
go to the UMLS home page,
click on the API button, and then the UMLS REST API link.
The help documentation we have provided is very extensive.
You can also find sample collection of settings for Postman application,
including those we used in this demo,
and code samples in Python, Java, and Perl.
You can also send us your questions by clicking on the
Contact NLM link on the upper right corner of virtually every NLM page.
Thank you for watching!