Accessing NCBO Annotator Web Service in C#

The NCBO Annotator allows you to get annotations for (biomedical) text from a number of standard ontologies. For instance, if I want to find the corresponding RadLex codes for ‘abdomen knee’, I can type them into the textbox, and restrict the ontology list to just RadLex.


This manual approach works fine if you just want a few sentences annotated, but if you need to annotate multiple sentences in a systematic manner you need to do this programmatically. This is where the annotate web services come in. There are several client examples as well where you can find some sample code in several languages. There is a Java annotator client example, but unfortunately there is no C# example. For something I’m trying to implement I need to (or rather, I prefer to) use C#. Translating some Java code to C# isn’t hard, but in case someone’s looking for a ready-to-use C# example, following is a function/method you can use:

private void GetData()
            Uri address = new Uri("");

            // Create the web request  
            HttpWebRequest request = WebRequest.Create(address) as HttpWebRequest;

            // Set type to POST  
            request.Method = "POST";
            request.ContentType = "application/x-www-form-urlencoded";
            request.UserAgent = "Annotator Client Example - Annotator";

            String text = "abdomen knee";

            StringBuilder data = new StringBuilder();

            // Configure the form parameters
            data.Append("longestOnly=" + "false&");
            data.Append("wholeWordOnly=" + "true&");
            data.Append("filterNumber=" + "true&");
            data.Append("withDefaultStopWords=" + "true&");
            data.Append("isTopWordsCaseSensitive=" + "false&");
            data.Append("mintermSize=" + "3&");
            data.Append("scored=" + "true&");
            data.Append("withSynonyms=" + "true&");
            data.Append("ontologiesToExpand=" + "&");
            data.Append("ontologiesToKeepInResult=" + "1057&"); // from Use comma sep. list of ont. ids
            data.Append("isVirtualOntologyId=" + "true&");
            data.Append("semanticTypes=" + "&");
            data.Append("levelMax=" + "0&");
            data.Append("mappingTypes=" + "&"); //null, Automatic, Manual 
            data.Append("textToAnnotate=" + text + "&");
            data.Append("format=" + "xml&"); //Options are 'text', 'xml', 'tabDelimited'   
            data.Append("apikey=" + "YOUR_KEY");

            // Create a byte array of the data we want to send  
            byte[] byteData = UTF8Encoding.UTF8.GetBytes(data.ToString());

            // Set the content length in the request headers  
            request.ContentLength = byteData.Length;

            // Write data  
            using (Stream postStream = request.GetRequestStream())
                postStream.Write(byteData, 0, byteData.Length);

            // Get response  
            using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)

                XmlDocument doc = new XmlDocument();

                XmlNodeList nodes = doc.SelectNodes("/success/data/annotatorResultBean/annotations/annotationBean");
                foreach (XmlNode node in nodes)
                    string radlexId = node.SelectSingleNode("concept/localConceptId").InnerText.Split('/')[1];
                    string radlexDescription = node.SelectSingleNode("concept/preferredName").InnerText;

                // Or print to console [uncomment line: doc.Load(response.GetResponseStream());]
                //StreamReader reader = new StreamReader(response.GetResponseStream());

You can set breakpoints at radlexID/radlexDescription to see that what you get programmatically is exactly the same as what you get when you type the text directly into website. Per the comment in the code, pick the list of ontologies you are interested in from and pass it as a comma separated list (e.g., if I’m interested in RadLex and Snomed, I’ll use:
“data.Append(“ontologiesToKeepInResult=” + “1057,1353&”);
where 1353 is the ID for Snomed.

Before you can use the web service, you’ll need to sign up at and get an API key first (which you will then pass as the value for ‘apikey’).

This entry was posted in General and tagged , , , , , . Bookmark the permalink.

One Response to Accessing NCBO Annotator Web Service in C#

  1. Mantas says:

    Great blog! Love the RadLex/C# posts. Keep up the great work,

    Post More!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s