Training
Learning path
Get started with Text Analytics for health - Training
Learn how to use Text Analytics for health in Microsoft Cloud for Healthcare.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
This article contains Text Analytics for health quickstarts that help with using the supported client libraries, C#, Java, NodeJS, and Python as well as with using the REST API.
Tip
You can use Azure AI Foundry to try summarization without needing to write code.
Reference documentation | More samples | Package (NuGet) | Library source code
Use this quickstart to create a Text Analytics for health application with the client library for .NET. In the following example, you create a C# application that can identify medical entities, relations, and assertions that appear in text.
Free F0
) to try the service (providing 5,000 text records - 1,000 characters each) and upgrade later to the Standard S
pricing tier for production. You can also start with the Standard S
pricing tier, receiving the same initial quota for free (5000 text records) before getting charged. For more information on pricing, visit Language Service Pricing.Your application must be authenticated to send API requests. For production, use a secure way of storing and accessing your credentials. In this example, you will write your credentials to environment variables on the local machine running the application.
To set the environment variable for your Language resource key, open a console window, and follow the instructions for your operating system and development environment.
LANGUAGE_KEY
environment variable, replace your-key
with one of the keys for your resource.LANGUAGE_ENDPOINT
environment variable, replace your-endpoint
with the endpoint for your resource.Important
If you use an API key, store it securely somewhere else, such as in Azure Key Vault. Don't include the API key directly in your code, and never post it publicly.
For more information about AI services security, see Authenticate requests to Azure AI services.
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
Note
If you only need to access the environment variables in the current running console, you can set the environment variable with set
instead of setx
.
After you add the environment variables, you might need to restart any running programs that will need to read the environment variables, including the console window. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example.
Using the Visual Studio IDE, create a new .NET Core console app. This action creates a "Hello World" project with a single C# source file: program.cs.
Install the client library by right-clicking on the solution in the Solution Explorer and selecting Manage NuGet Packages. In the package manager that opens select Browse and search for Azure.AI.TextAnalytics
. Select version 5.2.0
, and then Install. You can also use the Package Manager Console.
Copy the following code into your program.cs file. Then run the code.
Important
Go to the Azure portal. If the Language resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint by navigating to your resource's Keys and Endpoint page, under Resource Management.
Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.
using Azure;
using System;
using Azure.AI.TextAnalytics;
using System.Collections.Generic;
using System.Threading.Tasks;
namespace Example
{
class Program
{
// This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
private static readonly AzureKeyCredential credentials = new (Environment.GetEnvironmentVariable("LANGUAGE_KEY"));
private static readonly Uri endpoint = new (Environment.GetEnvironmentVariable("LANGUAGE_ENDPOINT"));
// Example method for extracting information from healthcare-related text
static async Task healthExample(TextAnalyticsClient client)
{
string document = "Prescribed 100mg ibuprofen, taken twice daily.";
List<string> batchInput = new List<string>()
{
document
};
AnalyzeHealthcareEntitiesOperation healthOperation = await client.StartAnalyzeHealthcareEntitiesAsync(batchInput);
await healthOperation.WaitForCompletionAsync();
await foreach (AnalyzeHealthcareEntitiesResultCollection documentsInPage in healthOperation.Value)
{
Console.WriteLine($"Results of Azure Text Analytics for health async model, version: \"{documentsInPage.ModelVersion}\"");
Console.WriteLine("");
foreach (AnalyzeHealthcareEntitiesResult entitiesInDoc in documentsInPage)
{
if (!entitiesInDoc.HasError)
{
foreach (var entity in entitiesInDoc.Entities)
{
// view recognized healthcare entities
Console.WriteLine($" Entity: {entity.Text}");
Console.WriteLine($" Category: {entity.Category}");
Console.WriteLine($" Offset: {entity.Offset}");
Console.WriteLine($" Length: {entity.Length}");
Console.WriteLine($" NormalizedText: {entity.NormalizedText}");
}
Console.WriteLine($" Found {entitiesInDoc.EntityRelations.Count} relations in the current document:");
Console.WriteLine("");
// view recognized healthcare relations
foreach (HealthcareEntityRelation relations in entitiesInDoc.EntityRelations)
{
Console.WriteLine($" Relation: {relations.RelationType}");
Console.WriteLine($" For this relation there are {relations.Roles.Count} roles");
// view relation roles
foreach (HealthcareEntityRelationRole role in relations.Roles)
{
Console.WriteLine($" Role Name: {role.Name}");
Console.WriteLine($" Associated Entity Text: {role.Entity.Text}");
Console.WriteLine($" Associated Entity Category: {role.Entity.Category}");
Console.WriteLine("");
}
Console.WriteLine("");
}
}
else
{
Console.WriteLine(" Error!");
Console.WriteLine($" Document error code: {entitiesInDoc.Error.ErrorCode}.");
Console.WriteLine($" Message: {entitiesInDoc.Error.Message}");
}
Console.WriteLine("");
}
}
}
static async Task Main(string[] args)
{
var client = new TextAnalyticsClient(endpoint, credentials);
await healthExample(client);
}
}
}
Results of Azure Text Analytics for health async model, version: "2022-03-01"
Entity: 100mg
Category: Dosage
Offset: 11
Length: 5
NormalizedText:
Entity: ibuprofen
Category: MedicationName
Offset: 17
Length: 9
NormalizedText: ibuprofen
Entity: twice daily
Category: Frequency
Offset: 34
Length: 11
NormalizedText:
Found 2 relations in the current document:
Relation: DosageOfMedication
For this relation there are 2 roles
Role Name: Dosage
Associated Entity Text: 100mg
Associated Entity Category: Dosage
Role Name: Medication
Associated Entity Text: ibuprofen
Associated Entity Category: MedicationName
Relation: FrequencyOfMedication
For this relation there are 2 roles
Role Name: Medication
Associated Entity Text: ibuprofen
Associated Entity Category: MedicationName
Role Name: Frequency
Associated Entity Text: twice daily
Associated Entity Category: Frequency
Tip
Fast Healthcare Interoperability Resources (FHIR) structuring is available using the Language REST API. The client libraries are not currently supported. Learn more on how to use FHIR structuring in your API call.
Reference documentation | More samples | Package (Maven) | Library source code
Use this quickstart to create a Text Analytics for health application with the client library for Java. In the following example, you create a Java application that can identify medical entities, relations, and assertions that appear in text.
Free F0
) to try the service (providing 5,000 text records - 1,000 characters each) and upgrade later to the Standard S
pricing tier for production. You can also start with the Standard S
pricing tier, receiving the same initial quota for free (5,000 text records) before getting charged. For more information on pricing, visit Language Service Pricing.Your application must be authenticated to send API requests. For production, use a secure way of storing and accessing your credentials. In this example, you will write your credentials to environment variables on the local machine running the application.
To set the environment variable for your Language resource key, open a console window, and follow the instructions for your operating system and development environment.
LANGUAGE_KEY
environment variable, replace your-key
with one of the keys for your resource.LANGUAGE_ENDPOINT
environment variable, replace your-endpoint
with the endpoint for your resource.Important
If you use an API key, store it securely somewhere else, such as in Azure Key Vault. Don't include the API key directly in your code, and never post it publicly.
For more information about AI services security, see Authenticate requests to Azure AI services.
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
Note
If you only need to access the environment variables in the current running console, you can set the environment variable with set
instead of setx
.
After you add the environment variables, you might need to restart any running programs that will need to read the environment variables, including the console window. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example.
Create a Maven project in your preferred IDE or development environment. Then add the following dependency to your project's pom.xml file. You can find the implementation syntax for other build tools online.
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-textanalytics</artifactId>
<version>5.2.0</version>
</dependency>
</dependencies>
Create a Java file named EntityLinking.java
. Open the file and copy the below code. Then run the code.
Important
Go to the Azure portal. If the Language resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint by navigating to your resource's Keys and Endpoint page, under Resource Management.
Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.
import com.azure.core.credential.AzureKeyCredential;
import com.azure.ai.textanalytics.models.*;
import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
import com.azure.ai.textanalytics.TextAnalyticsClient;
import java.util.List;
import java.util.Arrays;
import com.azure.core.util.Context;
import com.azure.core.util.polling.SyncPoller;
import com.azure.ai.textanalytics.util.*;
public class Example {
// This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
private static String KEY = System.getenv("LANGUAGE_KEY");
private static String ENDPOINT = System.getenv("LANGUAGE_ENDPOINT");
public static void main(String[] args) {
TextAnalyticsClient client = authenticateClient(languageKey, languageEndpoint);
healthExample(client);
}
// Method to authenticate the client object with your key and endpoint
static TextAnalyticsClient authenticateClient(String key, String endpoint) {
return new TextAnalyticsClientBuilder()
.credential(new AzureKeyCredential(key))
.endpoint(endpoint)
.buildClient();
}
// Example method for extracting information from healthcare-related text
static void healthExample(TextAnalyticsClient client){
List<TextDocumentInput> documents = Arrays.asList(
new TextDocumentInput("0",
"Prescribed 100mg ibuprofen, taken twice daily."));
AnalyzeHealthcareEntitiesOptions options = new AnalyzeHealthcareEntitiesOptions().setIncludeStatistics(true);
SyncPoller<AnalyzeHealthcareEntitiesOperationDetail, AnalyzeHealthcareEntitiesPagedIterable>
syncPoller = client.beginAnalyzeHealthcareEntities(documents, options, Context.NONE);
System.out.printf("Poller status: %s.%n", syncPoller.poll().getStatus());
syncPoller.waitForCompletion();
// Task operation statistics
AnalyzeHealthcareEntitiesOperationDetail operationResult = syncPoller.poll().getValue();
System.out.printf("Operation created time: %s, expiration time: %s.%n",
operationResult.getCreatedAt(), operationResult.getExpiresAt());
System.out.printf("Poller status: %s.%n", syncPoller.poll().getStatus());
for (AnalyzeHealthcareEntitiesResultCollection resultCollection : syncPoller.getFinalResult()) {
// Model version
System.out.printf(
"Results of Azure Text Analytics for health entities\" Model, version: %s%n",
resultCollection.getModelVersion());
for (AnalyzeHealthcareEntitiesResult healthcareEntitiesResult : resultCollection) {
System.out.println("Document ID = " + healthcareEntitiesResult.getId());
System.out.println("Document entities: ");
// Recognized healthcare entities
for (HealthcareEntity entity : healthcareEntitiesResult.getEntities()) {
System.out.printf(
"\tText: %s, normalized name: %s, category: %s, subcategory: %s, confidence score: %f.%n",
entity.getText(), entity.getNormalizedText(), entity.getCategory(),
entity.getSubcategory(), entity.getConfidenceScore());
}
// Recognized healthcare entity relation groups
for (HealthcareEntityRelation entityRelation : healthcareEntitiesResult.getEntityRelations()) {
System.out.printf("Relation type: %s.%n", entityRelation.getRelationType());
for (HealthcareEntityRelationRole role : entityRelation.getRoles()) {
HealthcareEntity entity = role.getEntity();
System.out.printf("\tEntity text: %s, category: %s, role: %s.%n",
entity.getText(), entity.getCategory(), role.getName());
}
}
}
}
}
}
Poller status: IN_PROGRESS.
Operation created time: 2022-09-15T19:06:11Z, expiration time: 2022-09-16T19:06:11Z.
Poller status: SUCCESSFULLY_COMPLETED.
Results of Azure Text Analytics for health entities" Model, version: 2022-03-01
Document ID = 0
Document entities:
Text: 100mg, normalized name: null, category: Dosage, subcategory: null, confidence score: 0.980000.
Text: ibuprofen, normalized name: ibuprofen, category: MedicationName, subcategory: null, confidence score: 1.000000.
Text: twice daily, normalized name: null, category: Frequency, subcategory: null, confidence score: 1.000000.
Relation type: DosageOfMedication.
Entity text: 100mg, category: Dosage, role: Dosage.
Entity text: ibuprofen, category: MedicationName, role: Medication.
Relation type: FrequencyOfMedication.
Entity text: ibuprofen, category: MedicationName, role: Medication.
Entity text: twice daily, category: Frequency, role: Frequency.
Tip
Fast Healthcare Interoperability Resources (FHIR) structuring is available using the Language REST API. The client libraries are not currently supported. Learn more on how to use FHIR structuring in your API call.
Reference documentation | More samples | Package (npm) | Library source code
Use this quickstart to create a Text Analytics for health application with the client library for Node.js. In the following example, you create a JavaScript application that can identify medical entities, relations, and assertions that appear in text.
Free F0
) to try the service (providing 5,000 text records - 1,000 characters each) and upgrade later to the Standard S
pricing tier for production. You can also start with the Standard S
pricing tier, receiving the same initial quota for free (5,000 text records) before getting charged. For more information on pricing, visit Language Service Pricing.Your application must be authenticated to send API requests. For production, use a secure way of storing and accessing your credentials. In this example, you will write your credentials to environment variables on the local machine running the application.
To set the environment variable for your Language resource key, open a console window, and follow the instructions for your operating system and development environment.
LANGUAGE_KEY
environment variable, replace your-key
with one of the keys for your resource.LANGUAGE_ENDPOINT
environment variable, replace your-endpoint
with the endpoint for your resource.Important
If you use an API key, store it securely somewhere else, such as in Azure Key Vault. Don't include the API key directly in your code, and never post it publicly.
For more information about AI services security, see Authenticate requests to Azure AI services.
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
Note
If you only need to access the environment variables in the current running console, you can set the environment variable with set
instead of setx
.
After you add the environment variables, you might need to restart any running programs that will need to read the environment variables, including the console window. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example.
In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.
mkdir myapp
cd myapp
Run the npm init
command to create a node application with a package.json
file.
npm init
Install the npm package:
npm install @azure/ai-language-text
Open the file and copy the below code. Then run the code.
Important
Go to the Azure portal. If the Language resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint by navigating to your resource's Keys and Endpoint page, under Resource Management.
Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.
"use strict";
const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
// This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
const key = process.env.LANGUAGE_KEY;
const endpoint = process.env.LANGUAGE_ENDPOINT;
const documents = ["Patient does not suffer from high blood pressure."];
async function main() {
console.log("== Text analytics for health sample ==");
const client = new TextAnalysisClient(endpoint, new AzureKeyCredential(key));
const actions = [
{
kind: "Healthcare",
},
];
const poller = await client.beginAnalyzeBatch(actions, documents, "en");
poller.onProgress(() => {
console.log(
`Last time the operation was updated was on: ${poller.getOperationState().modifiedOn}`
);
});
console.log(`The operation was created on ${poller.getOperationState().createdOn}`);
console.log(`The operation results will expire on ${poller.getOperationState().expiresOn}`);
const results = await poller.pollUntilDone();
for await (const actionResult of results) {
if (actionResult.kind !== "Healthcare") {
throw new Error(`Expected a healthcare results but got: ${actionResult.kind}`);
}
if (actionResult.error) {
const { code, message } = actionResult.error;
throw new Error(`Unexpected error (${code}): ${message}`);
}
for (const result of actionResult.results) {
console.log(`- Document ${result.id}`);
if (result.error) {
const { code, message } = result.error;
throw new Error(`Unexpected error (${code}): ${message}`);
}
console.log("\tRecognized Entities:");
for (const entity of result.entities) {
console.log(`\t- Entity "${entity.text}" of type ${entity.category}`);
if (entity.dataSources.length > 0) {
console.log("\t and it can be referenced in the following data sources:");
for (const ds of entity.dataSources) {
console.log(`\t\t- ${ds.name} with Entity ID: ${ds.entityId}`);
}
}
}
if (result.entityRelations.length > 0) {
console.log(`\tRecognized relations between entities:`);
for (const relation of result.entityRelations) {
console.log(
`\t\t- Relation of type ${relation.relationType} found between the following entities:`
);
for (const role of relation.roles) {
console.log(`\t\t\t- "${role.entity.text}" with the role ${role.name}`);
}
}
}
}
}
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
== Text analytics for health sample ==
The operation was created on Mon Feb 13 2023 13:12:10 GMT-0800 (Pacific Standard Time)
The operation results will expire on Tue Feb 14 2023 13:12:10 GMT-0800 (Pacific Standard Time)
Last time the operation was updated was on: Mon Feb 13 2023 13:12:10 GMT-0800 (Pacific Standard Time)
- Document 0
Recognized Entities:
- Entity "high blood pressure" of type SymptomOrSign
and it can be referenced in the following data sources:
- UMLS with Entity ID: C0020538
- AOD with Entity ID: 0000023317
- BI with Entity ID: BI00001
- CCPSS with Entity ID: 1017493
- CCS with Entity ID: 7.1
- CHV with Entity ID: 0000015800
- COSTAR with Entity ID: 397
- CSP with Entity ID: 0571-5243
- CST with Entity ID: HYPERTENS
- DXP with Entity ID: U002034
- HPO with Entity ID: HP:0000822
- ICD10 with Entity ID: I10-I15.9
- ICD10AM with Entity ID: I10-I15.9
- ICD10CM with Entity ID: I10
- ICD9CM with Entity ID: 997.91
- ICPC2ICD10ENG with Entity ID: MTHU035456
- ICPC2P with Entity ID: K85004
- LCH with Entity ID: U002317
- LCH_NW with Entity ID: sh85063723
- LNC with Entity ID: LA14293-7
- MDR with Entity ID: 10020772
- MEDCIN with Entity ID: 33288
- MEDLINEPLUS with Entity ID: 34
- MSH with Entity ID: D006973
- MTH with Entity ID: 005
- MTHICD9 with Entity ID: 997.91
- NANDA-I with Entity ID: 00905
- NCI with Entity ID: C3117
- NCI_CPTAC with Entity ID: C3117
- NCI_CTCAE with Entity ID: E13785
- NCI_CTRP with Entity ID: C3117
- NCI_FDA with Entity ID: 1908
- NCI_GDC with Entity ID: C3117
- NCI_NCI-GLOSS with Entity ID: CDR0000458091
- NCI_NICHD with Entity ID: C3117
- NCI_caDSR with Entity ID: C3117
- NOC with Entity ID: 060808
- OMIM with Entity ID: MTHU002068
- PCDS with Entity ID: PRB_11000.06
- PDQ with Entity ID: CDR0000686951
- PSY with Entity ID: 23830
- RCD with Entity ID: XE0Ub
- SNM with Entity ID: F-70700
- SNMI with Entity ID: D3-02000
- SNOMEDCT_US with Entity ID: 38341003
- WHO with Entity ID: 0210
Tip
Fast Healthcare Interoperability Resources (FHIR) structuring is available using the Language REST API. The client libraries are not currently supported. Learn more on how to use FHIR structuring in your API call.
Reference documentation | More samples | Package (PyPi) | Library source code
Use this quickstart to create a Text Analytics for health application with the client library for Python. In the following example, you create a Python application that can identify medical entities, relations, and assertions that appear in text.
Free F0
) to try the service (providing 5,000 text records - 1,000 characters each) and upgrade later to the Standard S
pricing tier for production. You can also start with the Standard S
pricing tier, receiving the same initial quota for free (5,000 text records) before getting charged. For more information on pricing, visit Language Service Pricing.Your application must be authenticated to send API requests. For production, use a secure way of storing and accessing your credentials. In this example, you will write your credentials to environment variables on the local machine running the application.
To set the environment variable for your Language resource key, open a console window, and follow the instructions for your operating system and development environment.
LANGUAGE_KEY
environment variable, replace your-key
with one of the keys for your resource.LANGUAGE_ENDPOINT
environment variable, replace your-endpoint
with the endpoint for your resource.Important
If you use an API key, store it securely somewhere else, such as in Azure Key Vault. Don't include the API key directly in your code, and never post it publicly.
For more information about AI services security, see Authenticate requests to Azure AI services.
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
Note
If you only need to access the environment variables in the current running console, you can set the environment variable with set
instead of setx
.
After you add the environment variables, you might need to restart any running programs that will need to read the environment variables, including the console window. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example.
After installing Python, you can install the client library with:
pip install azure-ai-textanalytics==5.2.0
Create a new Python file and copy the below code. Then run the code.
Important
Go to the Azure portal. If the Language resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint by navigating to your resource's Keys and Endpoint page, under Resource Management.
Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.
# This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
key = os.environ.get('LANGUAGE_KEY')
endpoint = os.environ.get('LANGUAGE_ENDPOINT')
from azure.ai.textanalytics import TextAnalyticsClient
from azure.core.credentials import AzureKeyCredential
# Authenticate the client using your key and endpoint
def authenticate_client():
ta_credential = AzureKeyCredential(key)
text_analytics_client = TextAnalyticsClient(
endpoint=endpoint,
credential=ta_credential)
return text_analytics_client
client = authenticate_client()
# Example function for extracting information from healthcare-related text
def health_example(client):
documents = [
"""
Patient needs to take 50 mg of ibuprofen.
"""
]
poller = client.begin_analyze_healthcare_entities(documents)
result = poller.result()
docs = [doc for doc in result if not doc.is_error]
for idx, doc in enumerate(docs):
for entity in doc.entities:
print("Entity: {}".format(entity.text))
print("...Normalized Text: {}".format(entity.normalized_text))
print("...Category: {}".format(entity.category))
print("...Subcategory: {}".format(entity.subcategory))
print("...Offset: {}".format(entity.offset))
print("...Confidence score: {}".format(entity.confidence_score))
for relation in doc.entity_relations:
print("Relation of type: {} has the following roles".format(relation.relation_type))
for role in relation.roles:
print("...Role '{}' with entity '{}'".format(role.name, role.entity.text))
print("------------------------------------------")
health_example(client)
Entity: 50 mg
...Normalized Text: None
...Category: Dosage
...Subcategory: None
...Offset: 31
...Confidence score: 1.0
Entity: ibuprofen
...Normalized Text: ibuprofen
...Category: MedicationName
...Subcategory: None
...Offset: 40
...Confidence score: 1.0
Relation of type: DosageOfMedication has the following roles
...Role 'Dosage' with entity '50 mg'
...Role 'Medication' with entity 'ibuprofen'
Tip
Fast Healthcare Interoperability Resources (FHIR) structuring is available using the Language REST API. The client libraries are not currently supported. Learn more on how to use FHIR structuring in your API call.
Use this quickstart to send language detection requests using the REST API. In the following example, you use cURL to identify medical entities, relations, and assertions that appear in text.
Free F0
) to try the service (providing 5,000 text records - 1,000 characters each) and upgrade later to the Standard S
pricing tier for production. You can also start with the Standard S
pricing tier, receiving the same initial quota for free (5,000 text records) before getting charged. For more information on pricing, visit Language Service Pricing.Note
\
line continuation character. If your console or terminal uses a different line continuation character, use that character.Your application must be authenticated to send API requests. For production, use a secure way of storing and accessing your credentials. In this example, you will write your credentials to environment variables on the local machine running the application.
To set the environment variable for your Language resource key, open a console window, and follow the instructions for your operating system and development environment.
LANGUAGE_KEY
environment variable, replace your-key
with one of the keys for your resource.LANGUAGE_ENDPOINT
environment variable, replace your-endpoint
with the endpoint for your resource.Important
If you use an API key, store it securely somewhere else, such as in Azure Key Vault. Don't include the API key directly in your code, and never post it publicly.
For more information about AI services security, see Authenticate requests to Azure AI services.
setx LANGUAGE_KEY your-key
setx LANGUAGE_ENDPOINT your-endpoint
Note
If you only need to access the environment variables in the current running console, you can set the environment variable with set
instead of setx
.
After you add the environment variables, you might need to restart any running programs that will need to read the environment variables, including the console window. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example.
parameter | Description |
---|---|
-X POST <endpoint> |
Specifies your endpoint for accessing the API. |
-H Content-Type: application/json |
The content type for sending JSON data. |
-H "Ocp-Apim-Subscription-Key:<key> |
Specifies the key for accessing the API. |
-d <documents> |
The JSON containing the documents you want to send. |
The following cURL commands are executed from a BASH shell. Edit these commands with your own resource name, resource key, and JSON values.
<your-language-resource-key>
with your key.<your-language-resource-endpoint>
with your endpoint URL.curl -i -X POST $LANGUAGE_ENDPOINT/language/analyze-text/jobs?api-version=2022-05-15-preview \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" \
-d '{"analysisInput":{"documents": [{"text": "The doctor prescried 200mg Ibuprofen.","language": "en","id": "1"}]},"tasks":[{"taskId": "analyze 1","kind": "Healthcare","parameters": {"fhirVersion": "4.0.1"}}]}'
Get the operation-location
from the response header. The value will look similar to the following URL:
https://your-resource.cognitiveservices.azure.com/language/analyze-text/jobs/{JOB-ID}?api-version=2022-05-15-preview
To get the results of the request, use the following cURL command. Be sure to replace {JOB-ID}
with the numerical ID value you received from the previous operation-location
response header:
curl -X GET $LANGUAGE_ENDPOINT/language/analyze-text/jobs/{JOB-ID}?api-version=2022-05-15-preview \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY"
{
"jobId": "{JOB-ID}",
"lastUpdatedDateTime": "2022-06-27T22:04:39Z",
"createdDateTime": "2022-06-27T22:04:38Z",
"expirationDateTime": "2022-06-28T22:04:38Z",
"status": "succeeded",
"errors": [],
"tasks": {
"completed": 1,
"failed": 0,
"inProgress": 0,
"total": 1,
"items": [
{
"kind": "HealthcareLROResults",
"lastUpdateDateTime": "2022-06-27T22:04:39.7086762Z",
"status": "succeeded",
"results": {
"documents": [
{
"id": "1",
"entities": [
{
"offset": 4,
"length": 6,
"text": "doctor",
"category": "HealthcareProfession",
"confidenceScore": 0.76
},
{
"offset": 21,
"length": 5,
"text": "200mg",
"category": "Dosage",
"confidenceScore": 0.99
},
{
"offset": 27,
"length": 9,
"text": "Ibuprofen",
"category": "MedicationName",
"confidenceScore": 1.0,
"name": "ibuprofen",
"links": [
{
"dataSource": "UMLS",
"id": "C0020740"
},
{
"dataSource": "AOD",
"id": "0000019879"
},
{
"dataSource": "ATC",
"id": "M01AE01"
},
{
"dataSource": "CCPSS",
"id": "0046165"
},
{
"dataSource": "CHV",
"id": "0000006519"
},
{
"dataSource": "CSP",
"id": "2270-2077"
},
{
"dataSource": "DRUGBANK",
"id": "DB01050"
},
{
"dataSource": "GS",
"id": "1611"
},
{
"dataSource": "LCH_NW",
"id": "sh97005926"
},
{
"dataSource": "LNC",
"id": "LP16165-0"
},
{
"dataSource": "MEDCIN",
"id": "40458"
},
{
"dataSource": "MMSL",
"id": "d00015"
},
{
"dataSource": "MSH",
"id": "D007052"
},
{
"dataSource": "MTHSPL",
"id": "WK2XYI10QM"
},
{
"dataSource": "NCI",
"id": "C561"
},
{
"dataSource": "NCI_CTRP",
"id": "C561"
},
{
"dataSource": "NCI_DCP",
"id": "00803"
},
{
"dataSource": "NCI_DTP",
"id": "NSC0256857"
},
{
"dataSource": "NCI_FDA",
"id": "WK2XYI10QM"
},
{
"dataSource": "NCI_NCI-GLOSS",
"id": "CDR0000613511"
},
{
"dataSource": "NDDF",
"id": "002377"
},
{
"dataSource": "PDQ",
"id": "CDR0000040475"
},
{
"dataSource": "RCD",
"id": "x02MO"
},
{
"dataSource": "RXNORM",
"id": "5640"
},
{
"dataSource": "SNM",
"id": "E-7772"
},
{
"dataSource": "SNMI",
"id": "C-603C0"
},
{
"dataSource": "SNOMEDCT_US",
"id": "387207008"
},
{
"dataSource": "USP",
"id": "m39860"
},
{
"dataSource": "USPMG",
"id": "MTHU000060"
},
{
"dataSource": "VANDF",
"id": "4017840"
}
]
}
],
"relations": [
{
"relationType": "DosageOfMedication",
"entities": [
{
"ref": "#/results/documents/0/entities/1",
"role": "Dosage"
},
{
"ref": "#/results/documents/0/entities/2",
"role": "Medication"
}
]
}
],
"warnings": [],
"fhirBundle": {
"resourceType": "Bundle",
"id": "95d61191-402a-48c6-9657-a1e4efbda877",
"meta": {
"profile": [
"http://hl7.org/fhir/4.0.1/StructureDefinition/Bundle"
]
},
"identifier": {
"system": "urn:ietf:rfc:3986",
"value": "urn:uuid:95d61191-402a-48c6-9657-a1e4efbda877"
},
"type": "document",
"entry": [
{
"fullUrl": "Composition/34b666d3-45e7-474d-a398-d3b0329541ad",
"resource": {
"resourceType": "Composition",
"id": "34b666d3-45e7-474d-a398-d3b0329541ad",
"status": "final",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "11526-1",
"display": "Pathology study"
}
],
"text": "Pathology study"
},
"subject": {
"reference": "Patient/68dd21ce-58ae-4e59-9445-8331f99899ed",
"type": "Patient"
},
"encounter": {
"reference": "Encounter/90c75fea-4526-4e94-82f8-8df3bc983a14",
"type": "Encounter",
"display": "unknown"
},
"date": "2022-06-27",
"author": [
{
"reference": "Practitioner/a8ef1526-d4ce-41df-96df-e9d03428c840",
"type": "Practitioner",
"display": "Unknown"
}
],
"title": "Pathology study",
"section": [
{
"title": "General",
"code": {
"coding": [
{
"system": "",
"display": "Unrecognized Section"
}
],
"text": "General"
},
"text": {
"div": "<div>\r\n\t\t\t\t\t\t\t<h1>General</h1>\r\n\t\t\t\t\t\t\t<p>The doctor prescried 200mg Ibuprofen.</p>\r\n\t\t\t\t\t</div>"
},
"entry": [
{
"reference": "List/c8ca6757-1d7c-4c49-94e9-ef5263cb943c",
"type": "List",
"display": "General"
}
]
}
]
}
},
{
"fullUrl": "Practitioner/a8ef1526-d4ce-41df-96df-e9d03428c840",
"resource": {
"resourceType": "Practitioner",
"id": "a8ef1526-d4ce-41df-96df-e9d03428c840",
"extension": [
{
"extension": [
{
"url": "offset",
"valueInteger": -1
},
{
"url": "length",
"valueInteger": 7
}
],
"url": "http://hl7.org/fhir/StructureDefinition/derivation-reference"
}
],
"name": [
{
"text": "Unknown",
"family": "Unknown"
}
]
}
},
{
"fullUrl": "Patient/68dd21ce-58ae-4e59-9445-8331f99899ed",
"resource": {
"resourceType": "Patient",
"id": "68dd21ce-58ae-4e59-9445-8331f99899ed",
"gender": "unknown"
}
},
{
"fullUrl": "Encounter/90c75fea-4526-4e94-82f8-8df3bc983a14",
"resource": {
"resourceType": "Encounter",
"id": "90c75fea-4526-4e94-82f8-8df3bc983a14",
"meta": {
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter"
]
},
"status": "finished",
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"display": "unknown"
},
"subject": {
"reference": "Patient/68dd21ce-58ae-4e59-9445-8331f99899ed",
"type": "Patient"
}
}
},
{
"fullUrl": "MedicationStatement/17aeee32-1189-47fc-9223-8abe174f1292",
"resource": {
"resourceType": "MedicationStatement",
"id": "17aeee32-1189-47fc-9223-8abe174f1292",
"extension": [
{
"extension": [
{
"url": "offset",
"valueInteger": 27
},
{
"url": "length",
"valueInteger": 9
}
],
"url": "http://hl7.org/fhir/StructureDefinition/derivation-reference"
}
],
"status": "active",
"medicationCodeableConcept": {
"coding": [
{
"system": "http://www.nlm.nih.gov/research/umls",
"code": "C0020740",
"display": "ibuprofen"
},
{
"system": "http://www.nlm.nih.gov/research/umls/aod",
"code": "0000019879"
},
{
"system": "http://www.whocc.no/atc",
"code": "M01AE01"
},
{
"system": "http://www.nlm.nih.gov/research/umls/ccpss",
"code": "0046165"
},
{
"system": "http://www.nlm.nih.gov/research/umls/chv",
"code": "0000006519"
},
{
"system": "http://www.nlm.nih.gov/research/umls/csp",
"code": "2270-2077"
},
{
"system": "http://www.nlm.nih.gov/research/umls/drugbank",
"code": "DB01050"
},
{
"system": "http://www.nlm.nih.gov/research/umls/gs",
"code": "1611"
},
{
"system": "http://www.nlm.nih.gov/research/umls/lch_nw",
"code": "sh97005926"
},
{
"system": "http://loinc.org",
"code": "LP16165-0"
},
{
"system": "http://www.nlm.nih.gov/research/umls/medcin",
"code": "40458"
},
{
"system": "http://www.nlm.nih.gov/research/umls/mmsl",
"code": "d00015"
},
{
"system": "http://www.nlm.nih.gov/research/umls/msh",
"code": "D007052"
},
{
"system": "http://www.nlm.nih.gov/research/umls/mthspl",
"code": "WK2XYI10QM"
},
{
"system": "http://ncimeta.nci.nih.gov",
"code": "C561"
},
{
"system": "http://www.nlm.nih.gov/research/umls/nci_ctrp",
"code": "C561"
},
{
"system": "http://www.nlm.nih.gov/research/umls/nci_dcp",
"code": "00803"
},
{
"system": "http://www.nlm.nih.gov/research/umls/nci_dtp",
"code": "NSC0256857"
},
{
"system": "http://www.nlm.nih.gov/research/umls/nci_fda",
"code": "WK2XYI10QM"
},
{
"system": "http://www.nlm.nih.gov/research/umls/nci_nci-gloss",
"code": "CDR0000613511"
},
{
"system": "http://www.nlm.nih.gov/research/umls/nddf",
"code": "002377"
},
{
"system": "http://www.nlm.nih.gov/research/umls/pdq",
"code": "CDR0000040475"
},
{
"system": "http://www.nlm.nih.gov/research/umls/rcd",
"code": "x02MO"
},
{
"system": "http://www.nlm.nih.gov/research/umls/rxnorm",
"code": "5640"
},
{
"system": "http://snomed.info/sct",
"code": "E-7772"
},
{
"system": "http://snomed.info/sct/900000000000207008",
"code": "C-603C0"
},
{
"system": "http://snomed.info/sct/731000124108",
"code": "387207008"
},
{
"system": "http://www.nlm.nih.gov/research/umls/usp",
"code": "m39860"
},
{
"system": "http://www.nlm.nih.gov/research/umls/uspmg",
"code": "MTHU000060"
},
{
"system": "http://hl7.org/fhir/ndfrt",
"code": "4017840"
}
],
"text": "Ibuprofen"
},
"subject": {
"reference": "Patient/68dd21ce-58ae-4e59-9445-8331f99899ed",
"type": "Patient"
},
"context": {
"reference": "Encounter/90c75fea-4526-4e94-82f8-8df3bc983a14",
"type": "Encounter",
"display": "unknown"
},
"dosage": [
{
"text": "200mg",
"doseAndRate": [
{
"doseQuantity": {
"value": 200
}
}
]
}
]
}
},
{
"fullUrl": "List/c8ca6757-1d7c-4c49-94e9-ef5263cb943c",
"resource": {
"resourceType": "List",
"id": "c8ca6757-1d7c-4c49-94e9-ef5263cb943c",
"status": "current",
"mode": "snapshot",
"title": "General",
"subject": {
"reference": "Patient/68dd21ce-58ae-4e59-9445-8331f99899ed",
"type": "Patient"
},
"encounter": {
"reference": "Encounter/90c75fea-4526-4e94-82f8-8df3bc983a14",
"type": "Encounter",
"display": "unknown"
},
"entry": [
{
"item": {
"reference": "MedicationStatement/17aeee32-1189-47fc-9223-8abe174f1292",
"type": "MedicationStatement",
"display": "Ibuprofen"
}
}
]
}
}
]
}
}
],
"errors": [],
"modelVersion": "2022-03-01"
}
}
]
}
}
Tip
Fast Healthcare Interoperability Resources (FHIR) structuring is available using the Language REST API. The client libraries are not currently supported. Learn more on how to use FHIR structuring in your API call.
If you want to clean up and remove an Azure AI services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.
Training
Learning path
Get started with Text Analytics for health - Training
Learn how to use Text Analytics for health in Microsoft Cloud for Healthcare.